{"id":18365498,"url":"https://github.com/altvod/basic-notion","last_synced_at":"2025-10-08T18:00:07.854Z","repository":{"id":44547289,"uuid":"418073836","full_name":"altvod/basic-notion","owner":"altvod","description":"Client-agnostic model wrapper for Notion API","archived":false,"fork":false,"pushed_at":"2022-05-12T20:06:48.000Z","size":137,"stargazers_count":7,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T03:23:37.212Z","etag":null,"topics":["models","notion","notion-api","notion-database","python","python-library","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/altvod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-17T09:07:48.000Z","updated_at":"2024-07-03T12:16:59.000Z","dependencies_parsed_at":"2022-08-26T20:30:55.960Z","dependency_job_id":null,"html_url":"https://github.com/altvod/basic-notion","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Fbasic-notion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Fbasic-notion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Fbasic-notion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Fbasic-notion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/altvod","download_url":"https://codeload.github.com/altvod/basic-notion/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247512653,"owners_count":20950896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["models","notion","notion-api","notion-database","python","python-library","python3"],"created_at":"2024-11-05T23:13:49.115Z","updated_at":"2025-10-08T18:00:02.360Z","avatar_url":"https://github.com/altvod.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# basic-notion\nClient-agnostic model wrapper for Notion API.\n\nThis library does not do any interaction over the network itself,\nso it can be used with any existing client that exposes as output\nand accepts as input raw JSONable data.\n\nNote that this project is in active development, so major changes\nin its structure and API are quite possible in the near future.\n\n## Installation\n\nJust like any other python package out there, it can be installed via `pip`:\n\n```bash\npip install basic-notion\n```\n\n## Basic Examples\n\n### Defining Models\n\nAll of the examples assume that you put the following code\nin a file and name it `models.py`:\n\n```python\nfrom basic_notion.page import NotionPage, NotionPageList\nfrom basic_notion.field import SelectField, TitleField, MultiSelectField\n\n\nclass ReadingListItem(NotionPage):\n    type = SelectField(property_name='Type')\n    name = TitleField(property_name='Name')\n    status = SelectField(property_name='Status')\n    authors = MultiSelectField(property_name='Author')\n\n\nclass ReadingList(NotionPageList[ReadingListItem]):\n    ITEM_CLS = ReadingListItem\n```\n\nAll the other examples are using the `notion-client` package\nfor sending and fetching data.\nSee the package's [homepage on GitHub](https://github.com/ramnes/notion-sdk-py)\n\n### Fetching a page list from a database\n\n(assuming you put the contents of previous example in `models.py`)\n\n```python\nimport asyncio\nimport os\n\nfrom notion_client import AsyncClient\nfrom basic_notion.query import Query\n\nfrom models import ReadingList\n\n\nasync def get_reading_list() -\u003e ReadingList:\n    database_id = os.environ['DATABASE_ID']\n    notion_token = os.environ['NOTION_TOKEN']\n    notion = AsyncClient(auth=notion_token)\n    data = await notion.databases.query(\n        **Query.database(\n            database_id\n        ).filter(\n            # Construct filter using model's field\n            # (only one filter expression is supported)\n            ReadingList.item.type.filter.equals('Book')\n        ).sorts(\n            # And, similarly, the result's sorting\n            # (multiple fields can be listed here)\n            ReadingList.item.name.sort.ascending\n        ).serialize()\n    )\n    return ReadingList(data=data)\n\n\ndef print_reading_list(reading_list: ReadingList) -\u003e None:\n    for item in reading_list.items():\n        print(f'[{item.type.name}] {item.name.one_item.content}')\n\n\nasync def main() -\u003e None:\n    reading_list = await get_reading_list()\n    print_reading_list(reading_list)\n\n\nasyncio.run(main())\n```\n\n### Creating a new page\n\n```python\nfrom notion_client import Client\nfrom models import ReadingListItem\n\ndef create_page(client: Client, database_id: str) -\u003e ReadingListItem:\n    page = ReadingListItem.make(\n        parent={'database_id': database_id},\n        type='Book',\n        name=['The Best Book Ever'],\n        authors=['John Doe'],\n    )\n    response = client.pages.create(**page.data)\n    item = ReadingListItem(data=response)\n    # assert len(item.id) == 36\n    # assert item.type.name == 'Book'\n    # assert item.name.get_text() == 'The Best Book Ever'\n    # assert item.authors.get_text() == 'John Doe'\n    # assert not item.name[0].bold\n    return item\n```\n\n### Creating a new database\n\n```python\nfrom notion_client import Client\nfrom basic_notion.database import NotionDatabase\nfrom models import ReadingListItem\n\ndef create_database(client: Client, parent_page_id: str) -\u003e NotionDatabase:\n    database = NotionDatabase.make(\n        title=['My New Shiny Database'],\n        parent={'page_id': parent_page_id},\n        properties=ReadingListItem.schema,\n    )\n    response = client.pages.create(**database.data)\n    created_database = NotionDatabase(data=response)\n    return created_database\n```\n\nYou can also see the files in `tests/` for more examples\nand more thorough usage of the various attributes and properties\n\n## Development and Testing\n\n### Configuring the test environment\n\nInstall\n\n```bash\npip install -Ue .[testing]\n```\n\nCreate file `.env` with the following content:\n\n```\nNOTION_API_TOKEN=\u003cyour-notion-token\u003e\nROOT_PAGE_ID=\u003cyour-page-id\u003e\n```\n\nWhere:\n- `\u003cyour-notion-token\u003e` is your Notion API developer's token.\n  You will need to create a Notion integration for this:\n  visit https://www.notion.so/my-integrations.\n- `\u003cyour-page-id\u003e` is the ID of a page where the tests will\n  create new child pages and databases.\n  It must have read/write permissions for your access token.\n\n### Testing\n\nRun the tests:\n\n```bash\npytest tests\n```\n\nAnd always validate typing:\n\n```bash\nmypy src/basic_notion\n```\n\nOr simply\n\n```bash\nmake test\n```\n\n(it will run all test commands)\n\n## Links\n\nHomepage on GitHub: https://github.com/altvod/basic-notion\n\nProject's page on PyPi: https://pypi.org/project/basic-notion/\n\nNotion API: https://developers.notion.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltvod%2Fbasic-notion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltvod%2Fbasic-notion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltvod%2Fbasic-notion/lists"}