A simplified object model for the Notion SDK. This is loosely modeled after concepts found in SQLAlchemy.

:warning: Work In Progress: The interfaces in this module are still in development
and are likely to change frequently. Furthermore, documentation is pretty sparse so use
at your own risk!

That being said, if you do use this library, please drop a message! I'd love to see your
use case and how you are incorporating this into your project.


Install using PyPi:

pip install notional

Note: it is recommended to use a virtual environment (venv) for installing libraries
to prevent conflicting dependency versions.


Connect to the API using an integration token or an OAuth access token:

import notional

notion = notional.connect(auth=AUTH_TOKEN)

# do some things


The iterators provide convenient access to the Notion endpoints. Rather than looking for
each page of data, the iterators take care of this and expose a standard Python iterator:

import notional

from notional.iterator import EndpointIterator

notion = notional.connect(auth=AUTH_TOKEN)

tasks = EndpointIterator(
            'direction': 'ascending',
            'property': 'Last Update'

for data in tasks:
    # do the things

Note that the parameters to the iterator follow the standard API parameters for the
given endpoint.

Query Builder

Notional provides a query builder for interating with the Notion API. Query targets can be
either a specific database ID or a custom ORM type (with a __database__ property).

notion = notional.connect(auth=auth_token)
sorts = [{"direction": "ascending", "property": "Last Update"}]
query = notion.query(dbid).sort(sorts)

for data in query.execute():
    # something magic happens

For more information about querying,
read the official documentation.


This library has support for defining custom data types that wrap Notion pages. Typically,
these pages are entries in a database (collection) with a consistent schema.

from notional import types
from notional.records import Page, Property

class Task(Page):
    __database__ = NOTION_DATABASE_ID
    Title = Property('Title', types.Title)
    Priority = Property('Priority', types.SelectOne)
    DueDate = Property('Due Date', types.Date)

for task in notion.query(Task).execute():
    print(f"{task.Title} => {task.Priority}")
    task.DueDate =

See the examples for more information.

Token Security

It is generally a best practice to read the auth token from an environment variable or
a secrets file. To prevent accidental exposure, it is NOT recommended to save the token
in source. For more information, read about Notion authorization here.