obsidian: Initial implementation of synchronization to Obsidian Tasks

Author: jvalenzuela

README.md

@@ -79,6 +79,11 @@ At the moment the list of supported synchronizations is the following:
     <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-md-gtasks.md">README</a></td>
+    <td> <a href="https://publish.obsidian.md/tasks/Introduction">Obsidian Markdown Taks</a> ⬄  <a href="https://support.google.com/tasks/answer/7675772">Google Tasks</a></td>
+    <td><tt>md-gtasks-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>
@@ -510,6 +515,48 @@ Options:
 </details>
 
 <!-- END sniff-and-replace -->
+<!-- START sniff-and-replace md_gtasks_sync --help START -->
+
+<details>
+ <summary><tt>md_gtasks_sync --help</tt></summary>
+
+```
+Usage: md_gtasks_sync [OPTIONS]
+
+  Synchronize lists from your Google Tasks with Obsidian Tasks Markdown file.
+
+    The list of MD tasks can be based on a Markdown file path
+    while the list in GTasks should be provided by their name. if it doesn't
+    exist it will be created.
+
+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
+  -m, --markdown-file TEXT        Name of the Markdown file including tasks
+                                  list 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>
 
 ## Mechanics / Automatic synchronization
 

docs/readme-md-gtasks.md

@@ -0,0 +1,101 @@
+# [Markdown Obsidian Tasks](https://publish.obsidian.md/tasks/Introduction) ⬄ [Google Tasks](https://support.google.com/tasks/answer/7675772)
+
+![logo](../misc/meme-md-gtasks.png)
+
+## Description
+
+Given all tasks in your Google Task task list and a Markdown file with
+Obsidian tasks, synchronise all the addition /
+modification / deletion events between them.
+
+## Motivation
+
+While Obsidian Tasks is good for taking notes, tracking tasks across projects,
+keeping track of project goals etc., lacks the portability, simplicity and
+minimalistic design of Google Tasks. The latter also has the following
+advantages:
+
+- Automatic sync across all your devices
+- Comfortable addition/modification of events using voice commands
+- Actual reminding of events with a variety of mechanisms
+
+## Usage Examples
+
+Run the `md_gtasks_sync` to synchronise the Google Tasks list of your choice with
+the selected Markdown file. Run with `--help` for the list of options.
+
+```sh
+# Sync the +remindme Taskwarrior tag with the Google Tasks list named "TW Reminders"
+
+md_gtasks_sync --help
+md_gtasks_sync -m tasks.md -l "MD Tasks"
+```
+
+## Installation
+
+### Package Installation
+
+Install the `syncall` package from PyPI, enabling the `google` and `md`
+extras:
+
+```sh
+pip3 install syncall[google,tw]
+```
+
+## Notes re this synchronization
+
+- Currently subtasks of a Google Tasks item are treated as completely
+  independent of the parent task when converted to Markdown
+- It's not possible to get the time part of the "due" field of a task using the
+  Google Tasks API. Due to this restriction we currently do currently do sync
+  the date part (without the time) from Google Tasks to Markdown, but in
+  order not to remove the time part when doing the inverse synchronization, we
+  don't sync the date at all from Markdown to Google Tasks. More
+  information in [this ticket](https://issuetracker.google.com/u/1/issues/128979662)
+
+<details>
+<summary>Overriding Google Tasks API key (not required)</summary>
+
+**This step isn't since the Google Console app of this project is now verified.**
+
+At the moment the Google Console app that makes use of the Google Tasks API is
+still in Testing mode and awaiting approval from Google. This means that if it
+raches more than 100 users, the integration may stop working for you. In that
+case in order to use this integration you will have to register for your own
+developer account with the Google Tasks API with the following steps:
+
+Firstly, remove the `~/.gtasks_credentials.pickle` file on your system since
+that will be reused if found by the app.
+
+For creating your own Google Cloud Developer App:
+
+- Go to the [Google Cloud developer console](https://console.cloud.google.com/)
+- Make a new project
+- From the sidebar go to `API & Services` and once there click the `ENABLE APIS AND SERVICES` button
+- Look for and Enable the `Tasks API`
+
+Your newly created app now has access to the Tasks API. We now have to create
+and download the credentials:
+
+- Again, from the sidebar under `API And Services` click `Credentials`
+- In the Google Tasks API screen, click the `CREATE CREDENTIALS` button.
+- Select the `User data` radio button (not the `Application data`).
+- Fill in the `OAuth Consent Screen` information (shouldn't affect the process)
+- Allow the said credentials to access the following scopes:
+  - `Create, edit, organize, and delete all your tasks`
+  - `View your tasks`
+- Create a new `OAuth Client ID`. Set the type to `Desktop App` (app name is not
+  important).
+- Finally download the credentials in JSON form by clicking the download button
+  as shown below. This is the file you need to point to when running
+  `tw_gtasks_sync`.
+
+  ![download-btn](../misc/gcal-json-btn.png)
+
+To specify your custom credentials JSON file use the `--google-secret` flag as follows:
+
+```sh
+md_gtasks_sync -l "<list-name>" -m tasks.md --google-secret "<path/to/downloaded/json/file>"
+```
+
+</details>

misc/meme-md-gtasks.png

@@ -49,6 +49,8 @@ tw_notion_sync = "syncall.scripts.tw_notion_sync:main"
 fs_gkeep_sync = "syncall.scripts.fs_gkeep_sync:main"
 tw_caldav_sync = "syncall.scripts.tw_caldav_sync:main"
 tw_gtasks_sync = "syncall.scripts.tw_gtasks_sync:main"
+md_gtasks_sync = "syncall.scripts.md_gtasks_sync:main"
+
 
 # end-user dependencies --------------------------------------------------------
 [tool.poetry.dependencies]
@@ -89,7 +91,7 @@ tw = ["taskw-ng", "xdg"]
 fs = ["xattr"]
 
 # dev dependencies -------------------------------------------------------------
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 black = { version = "22.3.0", allow-prereleases = true }
 identify = "^2.6.0"
 isort = "^5.13.2"

pyproject.toml

@@ -357,6 +357,30 @@ def opt_gtasks_list():
     )
 
 
+# markdown file -------------------------------------------------------------------------------
+def opts_markdown():
+    def decorator(f):
+        for d in reversed(
+            [
+                _opt_md_file,
+                _opt_prefer_scheduled_date,
+            ],
+        ):
+            f = d()(f)
+        return f
+
+    return decorator
+
+
+def _opt_md_file():
+    return click.option(
+        "-m",
+        "--markdown-file",
+        type=str,
+        help="Name of the Markdown file including tasks list to synchronize",
+    )
+
+
 # google-related options ----------------------------------------------------------------------
 def opt_google_secret_override():
     return click.option(
@@ -459,6 +483,14 @@ def opt_filename_extension():
         default=".md",
     )
 
+def opt_filename_path():
+    return click.option(
+        "--path",
+        "--filename-path",
+        "filename_path",
+        type=str,
+        help="Use this file path for locally saved data",
+    )
 
 # general options -----------------------------------------------------------------------------
 def opts_miscellaneous(side_A_name: str, side_B_name: str):

syncall/cli.py

@@ -0,0 +1,114 @@
+import datetime
+import re
+import uuid
+
+from typing import Optional
+
+from item_synchronizer.types import ID
+from syncall.concrete_item import ConcreteItem, ItemKey, KeyType
+from syncall.filesystem.filesystem_file import FilesystemFile
+
+MD_TASK_CHECKBOX_RE = r"\[[ xX]\]"
+MD_TASK_LINE_START_RE = r"-\s*" + MD_TASK_CHECKBOX_RE
+MD_TASK_SCHEDULED_EMOJI = "⏳"
+MD_TASK_DUE_EMOJI = "📅"
+MD_TASK_DONE_EMOJI = "✅"
+
+MD_TASK_DATE_RE = r"(?<={EMOJI} )\d{4}-\d{2}-\d{2}"
+
+MD_TASK_SCHEDULED_RE = MD_TASK_DATE_RE.replace('{EMOJI}', MD_TASK_SCHEDULED_EMOJI)
+MD_TASK_DUE_RE = MD_TASK_DATE_RE.replace('{EMOJI}', MD_TASK_DUE_EMOJI)
+MD_TASK_DONE_RE = MD_TASK_DATE_RE.replace('{EMOJI}', MD_TASK_DONE_EMOJI)
+
+class MarkdownTaskItem(ConcreteItem):
+    """A task line inside a Markdown file."""
+
+    def __init__(self, is_checked: bool = False, title: str = ""):
+        super().__init__(
+            keys=(
+                ItemKey("is_checked", KeyType.String),
+                ItemKey("title", KeyType.String),
+                ItemKey("last_modified_date", KeyType.Date),
+            )
+        )
+
+        self._persistent_id = None
+        self.last_modified_date = None
+        self.scheduled_date = None
+        self.due_date = None
+        self.done_date = None
+        self.deleted = False
+        self.is_checked = is_checked
+        self.title = title
+
+    @classmethod
+    def from_raw_item(cls, markdown_raw_item: str) -> "MarkdownTaskItem":
+        """Create a MarkdownTaskItem given the raw item at hand."""
+
+        result = cls(
+            is_checked=markdown_raw_item["is_checked"],
+            title=markdown_raw_item["title"]
+        )
+        return result
+
+    @classmethod
+    def from_markdown(cls, markdown_text: str, markdown_file: FilesystemFile) -> "MarkdownTaskItem":
+        """Create a MarkdownTaskItem given the line of text."""
+
+        markdown_task = re.match(MD_TASK_LINE_START_RE, markdown_text)
+
+        if markdown_task is None:
+            return None
+
+        checkbox_found = re.search(MD_TASK_CHECKBOX_RE, markdown_text)
+        is_checked = 'X' in checkbox_found.group(0).upper()
+
+        md_task_split_re = "(\\s*{}\\s*|\\s*{}\\s*|\\s*{}\\s*|\\s*{}\\s*)".format(MD_TASK_CHECKBOX_RE, MD_TASK_SCHEDULED_EMOJI, MD_TASK_DUE_EMOJI, MD_TASK_DONE_EMOJI)
+        title = re.split(md_task_split_re, markdown_text)[2].strip()
+
+        result = cls(
+            is_checked=is_checked,
+            title=title
+        )
+        result.last_modified_date = markdown_file.last_modified_date
+
+        due_date = re.search(MD_TASK_DUE_RE, markdown_text)
+        scheduled_date = re.search(MD_TASK_SCHEDULED_RE, markdown_text)
+        done_date = re.search(MD_TASK_DONE_RE, markdown_text)
+
+        if due_date:
+            result.due_date = datetime.datetime.fromisoformat(due_date.group(0))
+
+        if scheduled_date:
+            result.scheduled_date = datetime.datetime.fromisoformat(scheduled_date.group(0))
+
+        if done_date:
+            result.done_date = datetime.datetime.fromisoformat(done_date.group(0))
+
+        return result
+
+    def __str__(self):
+        result = '- [{}] {}'.format(
+            'X' if self.is_checked else ' ',
+            self.title)
+
+        if self.scheduled_date:
+            result += " " + MD_TASK_SCHEDULED_EMOJI + " " + self.scheduled_date.date().isoformat()
+
+        if self.due_date:
+            result += " " + MD_TASK_DUE_EMOJI + " " + self.due_date.date().isoformat()
+
+        if self.done_date:
+            result += " " + MD_TASK_DONE_EMOJI + " " + self.done_date.date().isoformat()
+
+        return result
+
+    def _id(self) -> ID:
+        return uuid.uuid5(uuid.NAMESPACE_OID, self.title)
+
+    @property
+    def id(self) -> Optional[ID]:
+        return self._persistent_id or self._id()
+
+    def delete(self) -> None:
+        self.deleted = True