todoist-org-mode

Convert Todoist projects into Org mode files

What this project does

This is a Python language project with code to retrieve Todoist projects, sections and items using the Todoist Sync API (v9) and convert them into Org mode headings to be written to files.

Todoist is an application for maintaining to-do lists and planning projects. Org mode is a GNU Emacs major mode for convenient plain text markup and much more, including maintaining to-do lists and planning projects.

todoist-org-mode Python files:

• todoist2org - Library for generating Org mode headings from Todoist projects, sections and items.
• todoist2org_convert - Command-line (CLI) program to retrieve Todoist projects, sections and items, convert them to Org mode headings using todoist2org and write each heading to stdout or to the specified output file.

No part of this project modifies remote Todoist user data, it is only retrieved and converted locally.

Dependencies

• requests
• python-dateutil
• pytz

Using this project

To use this project, follow the steps below.

1. Clone or download and extract the repository.

   git clone https://github.com/drmfinlay/todoist-org-mode.git

2. Open a command prompt or terminal in the repository's root directory.

   cd todoist-org-mode

3. Install the required dependencies.

   pip install -r requirements.txt

todoist2org_convert program usage

Run todoist2org_convert, passing your Todoist API token and an optional output file path as the arguments. Your API token can be found under Settings->Integrations.

# Either convert and print all headings to stdout.
python todoist2org_convert.py 0123456789abcdef0123456789abcdef01234567

# Or convert and write all headings to output.org.
python todoist2org_convert.py 0123456789abcdef0123456789abcdef01234567 -o output.org

todoist2org library usage

The todoist2org library can be used for custom conversion of Todoist projects, sections and/or items. For example, it could be used to convert all items in the special Inbox project and write an Inbox.org file:

import todoist2org

# Use the API token to sync user resources.
api_token = "0123456789abcdef0123456789abcdef01234567"
state = todoist2org.sync_todoist_state(api_token)

# Assume the API request was successful and the Inbox project is first.
project = state["projects"][0]
project_id = project["id"]

# Write an Org mode file header followed by each generated heading to Inbox.org.
with open("Inbox.org", "w") as f:
    for line in todoist2org.generate_file_header(state, "Inbox"):
        f.write(line + "\n")
    f.write("\n")
    for heading in todoist2org.generate_project_headings(state, project_id, False):
     f.write(heading + "\n")

Limitations

• This project does not work in the other direction, i.e. it will not parse Org mode files and update Todoist with the equivalent projects, sections and items.
• Conversion of recurring due dates is not supported. Project items with recurring due dates will be tagged with :IS_RECURRING: for manual user conversion. Warnings will be logged for every item encountered that has a recurring due date. See the Org Manual Repeated Tasks section for how to specify recurring due dates in Org mode.
• Project comments, item comments, calendar feeds, reminders and templates are not brought over in the conversion process.
• Archived projects and sections are not included by default. There is an optional CLI -a / --include-archived argument and equivalent library function parameters that can be used to include archived projects and sections. If these are used, archived projects and sections will be tagged with :ARCHIVED: and output in roughly their original positions as if they were never archived. They will not be filed under a separate heading.

License

This is free software licensed under the MIT licence.