syncall

<p align="center"> <img src="https://raw.githubusercontent.com/bergercookie/syncall/master/misc/meme.png"/> </p> <a href="https://github.com/bergercookie/syncall/actions" alt="master"> <img src="https://github.com/bergercookie/syncall/actions/workflows/tests.yml/badge.svg?branch=master" /></a> <img src="https://github.com/bergercookie/syncall/actions/workflows/linters.yml/badge.svg?branch=master" /></a> <a href='https://coveralls.io/github/bergercookie/syncall?branch=master'> <img src='https://coveralls.io/repos/github/bergercookie/syncall/badge.svg?branch=master' alt='Coverage Status' /></a> <a href="https://github.com/pre-commit/pre-commit"> <img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white" alt="pre-commit"></a> <a href="https://github.com/bergercookie/syncall/blob/master/LICENSE" alt="LICENSE"> <img src="https://img.shields.io/github/license/bergercookie/syncall.svg" /></a> <a href="https://pypi.org/project/syncall" alt="PyPI"> <img src="https://img.shields.io/pypi/pyversions/syncall.svg" /></a> <a href="https://badge.fury.io/py/syncall"> <img src="https://badge.fury.io/py/syncall.svg" alt="PyPI version" height="18"></a> <a href="https://pepy.tech/project/syncall"> <img alt="Downloads" src="https://pepy.tech/badge/syncall"></a> <a href="https://github.com/psf/black"> <img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>

Description

syncall is your one-stop software to bi-directionally synchronize and keep in sync the data from a variety of services. The framework is targeted towards, but not limited to, the synchronization of note-taking and task management data. Each synchronization comes with its own executable which handles the synchronization services/sides at hand.

One of the main goals of syncall is to be extendable. Thus it should be easy to introduce support for either a new service / synchronization side (e.g., ClickUp) or a new synchronization altogether (e.g., ClickUp <-> Google Keep) given that you implement the corresponding synchronization sides and conversion methods. See also the CONTRIBUTING guide to get started.

At the moment the list of supported synchronizations is the following:

<table style="undefined;table-layout: fixed; width: 823px"> <thead> <tr> <th></th> <th>Description</th> <th>Executable</th> </tr> </thead> <tbody> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-tw-gtasks.md">README</a></td> <td> <a href="https://taskwarrior.org/">Taskwarrior</a> ⬄ <a href="https://support.google.com/tasks/answer/7675772">Google Tasks</a></td> <td><tt>tw-gtasks-sync</tt></td> </tr> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-tw-gcal.md">README</a></td> <td> <a href="https://taskwarrior.org/">Taskwarrior</a> ⬄ <a href="https://calendar.google.com/">Google Calendar</a></td> <td><tt>tw-gcal-sync</tt></td> </tr> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-tw-notion.md">README</a></td> <td> <a href="https://taskwarrior.org/">Taskwarrior</a> ⬄ <a href="https://notion.so">Notion Checkboxes</a></td> <td><tt>tw-notion-sync</tt></td> </tr> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-tw-gkeep.md">README</a></td> <td> <a href="https://taskwarrior.org/">Taskwarrior</a> ⬄ <a href="https://www.google.com/keep/">Google Keep Checkboxes</a></td> <td><tt>tw-gkeep-sync</tt></td> </tr> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-tw-asana.md">README</a></td> <td> <a href="https://taskwarrior.org/">Taskwarrior</a> ⬄ <a href="https://www.asana.com">Asana Tasks</a></td> <td><tt>tw-asana-sync</tt></td> </tr> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-tw-caldav.md">README</a></td> <td> <a href="https://taskwarrior.org/">Taskwarrior</a> ⬄ Generic <a href="https://en.wikipedia.org/wiki/CalDAV">Caldav </a> server</td> <td><tt>tw-caldav-sync</tt></td> </tr> <tr> <td><a href="https://github.com/bergercookie/syncall/blob/master/docs/readme-fs-gkeep.md">README</a></td> <td> Local Files ⬄ <a href="https://www.google.com/keep/">Google Keep Notes</a></td> <td><tt>fs-gkeep-sync</tt></td> </tr> </tbody> </table>

Each of the above should support bi-directional synchronization between the said services. This means that on an addition, modification, or deletion of an item on one side, a corresponding addition, modification or deletion of the counterpart item will occur on the other side so that the two sides are eventually in sync. All synchronizations also support conflict resolution meaning that it can successfully deal with item edits on both sides.

Currently unless the executable at hand specifies otherwise, the following conflict resolution strategies are available:

<!-- START sniff-and-replace tw_gcal_sync --list-resolution-strategies START --> <!-- OVERRIDES --no-collapsible --no-markdown OVERRIDES -->

1. MostRecentRS
2. LeastRecentRS
3. AlwaysFirstRS
4. AlwaysSecondRS

<!-- END sniff-and-replace -->

By the end of the run, it should show you a summary of what's been done, like the following.

Google Keep
-----------
        * Items created: 3
        * Items updated: 2
        * Items deleted: 1

Taskwarrior
-----------
        * Items created: 1
        * Items updated: 0
        * Items deleted: 0

Refer to the corresponding README from the list above for instructions specific to the synchronization with that particular service. Before jumping to that though, please complete the installation instructions below.

Installation instructions

Requirements

• Python version >= 3.8
• For the integrations that require Taskwarrior - (Installation instructions) version >=2.6 is required.

Installation Options

You have to specify at least one extra. To do so use the [] syntax in pip:

# for installing integration with google (e.g. Google Keep / Calendar) and Notion
pip3 install syncall[notion,google]

Here's some of the available options for installing it:

• From PyPI - e.g., Specify three extras for integrations - Google (Calendar/Tasks), Google Keep, Notion):

  pip3 install --user --upgrade syncall[notion,google,gkeep]
  

• From Github - e.g., Specify two extras:

  pip3 install --user "syncall[gkeep,fs] @ git+https://github.com/bergercookie/syncall"
  

• Download and install devel branch locally - bleeding edge

  git clone https://github.com/bergercookie/syncall
  cd syncall
  git checkout devel
  pip3 install --user --upgrade .[gkeep,fs,google,tw,caldav,asana]
  

• Setup using poetry - handy for local development and for isolation of dependencies:

  git clone https://github.com/bergercookie/syncall
  poetry install --all-extras
  # get an interactive shell
  poetry shell
  
  # now the executables of all the services should be in your PATH for the
  # current shell and you can also edit the source code without further
  # re-installation ...
  

Sample Usage Instructions

Here's the CLI help page for the synchronizations available.

<!-- START sniff-and-replace tw_gtasks_sync --help START --> <details> <summary><tt>tw_gtasks_sync --help</tt></summary>

Usage: tw_gtasks_sync [OPTIONS]

  Synchronize lists from your Google Tasks with filters from Taskwarrior.

  The list of TW tasks is determined by a combination of TW tags and a TW
  project while the list in GTasks should be provided by their name. if it
  doesn't exist it will be crated

Options:
  -l, --gtasks-list TEXT          Name of the Google Tasks list to synchronize
                                  (will be created if not there)
  --google-secret FILE            Override the client secret used for the
                                  communication with the Google APIs
  --oauth-port INTEGER            Port to use for OAuth Authentication with
                                  Google Applications
  -t, --taskwarrior-tags TEXT     Taskwarrior tags to synchronize
  -p, --tw-project TEXT           Taskwarrior project to synchronize
  --list-combinations             List the available named TW<->Google Tasks
                                  combinations
  --list-resolution-strategies    List all the available resolution strategies
                                  and exit
  -r, --resolution-strategy [MostRecentRS|LeastRecentRS|AlwaysFirstRS|AlwaysSecondRS]
                                  Resolution strategy to use during conflicts
  -b, --combination TEXT          Name of an already saved TW<->Google Tasks
                                  combination
  -s, --save-as TEXT              Save the given TW<->Google Tasks filters
                                  combination using a specified custom name.
  --prefer-scheduled-date         Prefer using the "scheduled" date field
                                  instead of the "due" date if the former is
                                  available
  -v, --verbose
  --version                       Show the version and exit.
  --help                          Show this message and exit.

</details> <!-- END sniff-and-replace --> <!-- START sniff-and-replace tw_gcal_sync --help START --> <details> <summary><tt>tw_gcal_sync --help</tt></summary>

Usage: tw_gcal_sync [OPTIONS]

  Synchronize calendars from your Google Calendar with filters from
  Taskwarrior.

  The list of TW tasks is determined by a combination of TW tags and a TW
  project while the calendar in GCal should be provided by their name. if it
  doesn't exist it will be crated

Options:
  -c, --gcal-calendar TEXT        Name