Client-agnostic model wrapper for Notion API.
This library does not do any interaction over the network itself, so it can be used with any existing client that exposes as output and accepts as input raw JSONable data.
Note that this project is in active development, so major changes in its structure and API are quite possible in the near future.
Just like any other python package out there, it can be installed via pip:
pip install basic-notionAll of the examples assume that you put the following code
in a file and name it models.py:
frombasic_notion.pageimportNotionPage, NotionPageListfrombasic_notion.fieldimportSelectField, TitleField, MultiSelectFieldclassReadingListItem(NotionPage):
type=SelectField(property_name='Type')
name=TitleField(property_name='Name')
status=SelectField(property_name='Status')
authors=MultiSelectField(property_name='Author')
classReadingList(NotionPageList[ReadingListItem]):
ITEM_CLS=ReadingListItemAll the other examples are using the notion-client package
for sending and fetching data.
See the package's homepage on GitHub
(assuming you put the contents of previous example in models.py)
importasyncioimportosfromnotion_clientimportAsyncClientfrombasic_notion.queryimportQueryfrommodelsimportReadingListasyncdefget_reading_list() ->ReadingList:
database_id=os.environ['DATABASE_ID']
notion_token=os.environ['NOTION_TOKEN']
notion=AsyncClient(auth=notion_token)
data=awaitnotion.databases.query(
**Query.database(
database_id
).filter(
# Construct filter using model's field# (only one filter expression is supported)ReadingList.item.type.filter.equals('Book')
).sorts(
# And, similarly, the result's sorting# (multiple fields can be listed here)ReadingList.item.name.sort.ascending
).serialize()
)
returnReadingList(data=data)
defprint_reading_list(reading_list: ReadingList) ->None:
foriteminreading_list.items():
print(f'[{item.type.name}] {item.name.one_item.content}')
asyncdefmain() ->None:
reading_list=awaitget_reading_list()
print_reading_list(reading_list)
asyncio.run(main())fromnotion_clientimportClientfrommodelsimportReadingListItemdefcreate_page(client: Client, database_id: str) ->ReadingListItem:
page=ReadingListItem.make(
parent={'database_id': database_id},
type='Book',
name=['The Best Book Ever'],
authors=['John Doe'],
)
response=client.pages.create(**page.data)
item=ReadingListItem(data=response)
# assert len(item.id) == 36# assert item.type.name == 'Book'# assert item.name.get_text() == 'The Best Book Ever'# assert item.authors.get_text() == 'John Doe'# assert not item.name[0].boldreturnitemfromnotion_clientimportClientfrombasic_notion.databaseimportNotionDatabasefrommodelsimportReadingListItemdefcreate_database(client: Client, parent_page_id: str) ->NotionDatabase:
database=NotionDatabase.make(
title=['My New Shiny Database'],
parent={'page_id': parent_page_id},
properties=ReadingListItem.schema,
)
response=client.pages.create(**database.data)
created_database=NotionDatabase(data=response)
returncreated_databaseYou can also see the files in tests/ for more examples
and more thorough usage of the various attributes and properties
Install
pip install -Ue .[testing]Create file .env with the following content:
NOTION_API_TOKEN=<your-notion-token>
ROOT_PAGE_ID=<your-page-id>
Where:
<your-notion-token>is your Notion API developer's token. You will need to create a Notion integration for this: visit https://www.notion.so/my-integrations.<your-page-id>is the ID of a page where the tests will create new child pages and databases. It must have read/write permissions for your access token.
Run the tests:
pytest testsAnd always validate typing:
mypy src/basic_notionOr simply
make test(it will run all test commands)
Homepage on GitHub: https://github.com/altvod/basic-notion
Project's page on PyPi: https://pypi.org/project/basic-notion/
Notion API: https://developers.notion.com/