Metadata-Version: 2.1
Name: foursquare-swarm-ical
Version: 1.0.3
Summary: Sync Foursquare Swarm check-ins to local sqlite DB and generate iCalendar
Author-email: Tomáš Janoušek <tomi@nomi.cz>
License: MIT
Project-URL: Homepage, https://github.com/liskin/foursquare-swarm-ical
Project-URL: Release Notes, https://github.com/liskin/foursquare-swarm-ical/releases
Project-URL: Issues, https://github.com/liskin/foursquare-swarm-ical/issues
Project-URL: CI, https://github.com/liskin/foursquare-swarm-ical/actions
Project-URL: Donations (GitHub), https://github.com/sponsors/liskin
Project-URL: Donations (PayPal), https://www.paypal.me/lisknisi/5EUR
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Requires-Python: ~=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML
Requires-Dist: click~=8.0
Requires-Dist: click-config-file
Requires-Dist: foursquare
Requires-Dist: icalendar>=5.0.2
Requires-Dist: importlib-metadata; python_version < "3.10"
Requires-Dist: importlib-resources; python_version < "3.9"
Requires-Dist: platformdirs>=2.1
Provides-Extra: dev
Requires-Dist: build>=0.7; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: prysk>=0.20.0; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-pytz; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-recording; extra == "test"

# foursquare-swarm-ical

[![PyPI Python Version badge](https://img.shields.io/pypi/pyversions/foursquare-swarm-ical)](https://pypi.org/project/foursquare-swarm-ical/)
[![PyPI Version badge](https://img.shields.io/pypi/v/foursquare-swarm-ical)](https://pypi.org/project/foursquare-swarm-ical/)
![License badge](https://img.shields.io/github/license/liskin/foursquare-swarm-ical)

## Overview

**Sync Foursquare Swarm check-ins to local sqlite DB (incrementally) and generate iCalendar.**

![Example screenshot of the output in Google Calendar](https://github.com/liskin/foursquare-swarm-ical/assets/300342/b2c88749-3196-4645-8e2d-8574e19dfaa5)

## Installation

Using [pipx][]:

```
pipx ensurepath
pipx install foursquare-swarm-ical
```

To keep a local git clone around:

```
git clone https://github.com/liskin/foursquare-swarm-ical
make -C foursquare-swarm-ical pipx
```

Alternatively, if you don't need the isolated virtualenv that [pipx][]
provides, feel free to just:

```
pip install foursquare-swarm-ical
```

[pipx]: https://github.com/pypa/pipx

## Setup and usage

* Obtain a Foursquare API Access Token. The easiest way to obtain one is to
  use their [API Exporer](https://foursquare.com/developers/explore/). Grant
  it permission for your account, open DevTools, let it execute an API call
  and then inspect the request and copy `oauth_token` from the Query String
  Parameters.

  * Chrome: <https://developer.chrome.com/docs/devtools/network/reference#payload-encodings>
  * Firefox: <https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor/request_list>

* Run `foursquare-swarm-ical`:

  ```
  $ foursquare-swarm-ical --access-token TOKENTOKENTOKEN --max-size 1M -o swarm-checkins.ical
  ```

* Import `swarm-checkins.ical` into your calendar app of choice.

  (Note that Google Calendar refreshes iCal URLs once a day and cannot be
  tweaked in any way. Manual refresh isn't possible either.)

## Command line options

<!-- include tests/readme/help.md -->
    $ foursquare-swarm-ical --help
    Usage: foursquare-swarm-ical [OPTIONS]
    
      Sync Foursquare Swarm check-ins to local sqlite DB and generate iCalendar
    
    Options:
      -v, --verbose             Logging verbosity (0 = WARNING, 1 = INFO, 2 =
                                DEBUG)
      --sync / --no-sync        Sync again or just use local database?  [default:
                                sync]
      --full / --no-full        Perform full sync instead of incremental
                                [default: no-full]
      --access-token TEXT       Foursquare oauth2 access token  [env var:
                                FOURSQUARE_TOKEN]
      --database PATH           SQLite database file  [default: /home/user/.local/
                                share/foursquare_swarm_ical/checkins.sqlite]
      -e, --emoji / --no-emoji  Prefix summary with venue category as emoji
                                [default: emoji]
      -o, --output FILENAME     Output file
      -m, --max-size SIZE       Maximum size of the output file in bytes (accepts
                                K and M suffixes as well)
      --config FILE             Read configuration from FILE.  [default: /home/use
                                r/.config/foursquare_swarm_ical/config.yaml]
      --config-sample           Show sample configuration file
      --help                    Show this message and exit.
<!-- end include -->

## Configuration file

Access token (and other options) can be set permanently in a config file,
which is located at `~/.config/foursquare_swarm_ical/config.yaml` by default
(on Linux; on other platforms see output of `--help`).

Sample config file can be generated using the `--config-sample` flag:

<!-- include tests/readme/config-sample.md -->
    $ foursquare-swarm-ical --config-sample
    # Logging verbosity (0 = WARNING, 1 = INFO, 2 = DEBUG)
    verbose: 0
    
    # Sync again or just use local database?
    sync: true
    
    # Perform full sync instead of incremental
    full: false
    
    # Foursquare oauth2 access token
    access_token: TEXT
    
    # SQLite database file
    database: /home/user/.local/share/foursquare_swarm_ical/checkins.sqlite
    
    # Prefix summary with venue category as emoji
    emoji: true
    
    # Output file
    output: '-'
    
    # Maximum size of the output file in bytes (accepts K and M suffixes as well)
    max_size: SIZE
<!-- end include -->

## Donations (♥ = €)

If you like this tool and wish to support its development and maintenance,
please consider [a small donation](https://www.paypal.me/lisknisi/5EUR) or
[recurrent support through GitHub Sponsors](https://github.com/sponsors/liskin).

By donating, you'll also support the development of my other projects. You
might like these:

* [strava-offline](https://github.com/liskin/strava-offline) – Keep a local mirror of Strava activities for further analysis/processing
* [strava-ical](https://github.com/liskin/strava-ical) – Generate iCalendar with your Strava activities
