This project aims to extend Notion's functionality to work more broadly for a variety of users and provide a skeleton for other developers to create well-formulated extensions using Notion's API.
Inspired by personal need and the lack of support for advanced to-do list functionality in Notion, I decided to build a rough version of the functionality I wanted using Notion's API.
Initially, I implemented this using Notion's Javascript SDK. However, the json was clunky to work with, and the lack of typing made it difficult to develop on top of the API. To resolve this, I opted to switch to Python, using mypy for static typechecking, and create an ORM wrapper around Notion databases. This has several advantages:
- Static type checking helps catch many bugs before they are deployed, increasing overall code quality (and readability)
- ORM layer provides a clean, typed, programmatic interface to Notion's API
- ORM generator means that we can easily handle database changes or interfacing with new databases, increasing development velocity dramatically
- ORM layer can be extended to support other Notion data types, or even other Notion objects (e.g. pages). This will make it simple to develop clean extensions for most use cases
Different extensions are run using GitHub actions for simplicity. Secrets can easily be stored to be passed to actions, and schedules or triggers can be customized. For an example of setting up actions, see below.
This project's primary value is as an example for others to use when developing against Notion's API.
The core value of this project is its wrapper around Notion databases (which can be extended to generic pages). Once you've generated the Python wrapper for your database, you can query Notion incredibly easily.
The following features are supported by this project.
This extension adds support for recurring tasks to Notion to do lists. It requires two tables to function, one containing tasks, and the other containing timestamps of its executions. The latter is used to limit query sizes by only looking at tasks modified since the last execution.
This extension supports Cron string schedules, as well as the following forms:
- Every (X) (days|weeks|months|years)
- Every (X) (days|weeks|months|years), at (9am)
- Every (X) (days|weeks|months|years), from (due date/completed date)
- Every (X) (days|weeks|months|years), from (due date/completed date), at (9am)
- Every (X) (days|weeks|months|years), at (9am), from (due date/completed date)
- Every (X) weeks, on (mon/tue/wed, etc.)
- Every (X) weeks, on (mon/tue/wed, etc.), at (9am)
- Every (X) months, on the last day
- Every (X) months, on the last day, at (9am)
- Every (X) (weeks|months|years), on day (1/3/5-7)
- Every (X) (weeks|months|years), on day (1/3/5-7), at (9am)
- Every (X) (weeks|months|years), at (9am), on day (X)
- Every (day|weekday)
- Every (day|weekday), at (9am)
- Every (mon/tue/wed, etc.)
- Every (mon/tue/wed, etc.), at (9am)
where values in parentheses are specified by the user.
The syntax in these strings is extremely important. Our parser expects that each part of the schedule be separated by a comma, and that consecutive elements of lists be separated by forward slashes (/). Some examples of valid strings are:
- "Every mon/tuesday, at 9am" (equivalent to "Every 1 weeks, on day 1/2, at 9am")
- "Every 1 months, on day 1/5-9" ("5-9" will be interpreted as a range, meaning the schedule should execute on days 1, 5, 6, 7, 8, and 9)
- "Every 1 months, on day 1"
- "Every 1 months, on the last day"
To specify days of the week, you may use either abbreviations (e.g. mon, tue) or the full day name (monday, tuesday). Time (9am) must be in dateutil-compatible string format.
If "from (due date/completed date)" is not specified, we will choose a default, depending on the configuration. Note that you cannot specify both "start from" and specific days to execute on.
First, clone the provided todo list template. You may also use your own databases, with the following requirements:
- The database you store your tasks in must have:
- name (title)
- last_edited_time (datetime)
- done (checkbox)
- status (select; with option "to do")
- due date (datetime)
- schedule (str)
- The database you store executions in must have:
- name (title)
- date_created (datetime)
- The database you store timezone information in must have:
- name (title), containing at least one entry with a correctly formatted timezone string
If you create your own databases, you will need to regenerate ORM classes.
Once your databases are created, create an integration and give it access to both databases. Next, fork this repository. Finally, create the following repository secrets on your fork:
- NOTION_TASKS_DB_ID (your tasks database ID; see here for how to get a database ID)
- NOTION_EXECUTIONS_DB_ID (your executions database ID)
- NOTOIN_TIMEZONE_DB_ID (your timezone database ID)
- NOTION_API_KEY (your integration token; if you didn't copy it earlier, you may copy it by going to "Settings & Members" -> "Integrations", clicking the ellipsis next to your api key, and selecting "Copy internal integration token")
And just like that, you should be good to go! Now, you can customize your databases or the extension's schedule.
To be implemented.
To be implemented.
To be implemented.