| Name | ultimate-notion JSON |
| Version |
0.9.1
JSON |
| download |
| home_page | None |
| Summary | The ultimate Python client for Notion! |
| upload_time | 2025-09-03 18:53:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
notion
notion client
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img
src="https://raw.githubusercontent.com/ultimate-notion/ultimate-notion/master/docs/assets/images/logo_with_text.svg"
alt="Ultimate-Notion logo" width="500" role="img">
</div>
<br/>
Ultimate Notion is the ultimate Python client for [Notion]!
| | |
|---------|------------------------------------|
| CI/CD | [![Tests][Tests-image]][Tests-link] [![Coverage][Coverage-image]][Coverage-link] [![Publish Package][Publish-image]][Publish-link] [![Build Docs][Docs-image]][Docs-link] [![EffVer Versioning][EffVer-image]][EffVer-link] |
| Package | [![PyPI - Version][PyPI_ver-image]][PyPI_ver-link] [![PyPI - Downloads][PyPI_down-image]][PyPI_down-link] [![PyPI - Python Version][PyPI_py-image]][PyPI_py-link] [![GitHub Sponsors][sponsor-image]][sponsor-link] |
| Details | [![Hatch project][hatch-image]][hatch-link] [![Linting - Ruff][ruff-image]][ruff-link] [![Pre-Commit][precommit-image]][precommit-link] [![test - pytest][pytest-image]][pytest-link] [![Types - Mypy][mypy-image]][mypy-link] [![License - MIT][MIT-image]][MIT-link] [![Docs - mkdocs][mkdocs-image]][mkdocs-link] |
## ✨ Features
- 🐍 **Pythonic API** — Clean, intuitive Python interfaces with robust type annotations.
- 🗂️ **CRUD operations** — Create, read, update, and delete Notion pages, databases, and blocks.
- 🔎 **Rich querying capabilities** — Support for filters, sorting, pagination, and searching.
- 🪄 **Flexible exports** — Convert Notion pages to Markdown, HTML, and databases to pandas, Polars.
- ⬆️ **File upload support** — Easily upload and manage files in Notion pages and databases.
- 🧩 **Built atop notion-sdk-py** — Enhancing the functionality of the popular low-level client.
- 💯 **100% feature parity** — Full compatibility with all notion-sdk-py capabilities and more.
- 🖥️ **Command line interface** — Convenient CLI for quick operations and automation scripts.
- 🔒 **Token-based authentication** — Secure access using Notion integration tokens.
- 🚀 **One-step setup** — Getting up to speed with a [simple setup guide].
👉 Want to learn more? Explore the full [feature breakdown].
## 📦 Installation
Install the most recent release using [PyPI] with:
```console
pip install ultimate-notion
```
or to install all additional dependencies, use:
```console
pip install 'ultimate-notion[all]'
```
### 🧪 Installing the Development Version
To install the latest (potentially unstable) version directly from the main branch on GitHub:
```console
pip install git+https://github.com/ultimate-notion/ultimate-notion.git@main
```
or with all optional dependencies:
```console
pip install 'ultimate-notion[all] @ git+https://github.com/ultimate-notion/ultimate-notion.git@main'
```
## 🚀 Usage
Make sure you have set the environment variable `NOTION_TOKEN` to your Notion
integration token. Then it's as simple as:
```python
import ultimate_notion as uno
PAGE_TITLE = 'Getting Started'
with uno.Session() as notion:
page = notion.search_page(PAGE_TITLE).item()
page.show()
# Alternatively, without a context manager:
notion = uno.Session()
page = notion.search_page(PAGE_TITLE).item()
page.show()
notion.close()
```
Check out the official [Ultimate Notion documentation] for more details.
Especially the page about [creating a Notion integration] to get the token.
## 💬 Getting help
If you are stuck with a problem and need help or just want to brag about what you did,
the [Discussion] area is the right place for you. Here, you can ask questions, provide
suggesions and discuss with other users.
## 🤝 Contributing
After having cloned this repository:
1. make sure [hatch] is installed globally, e.g. `pipx install hatch`,
2. make sure [pre-commit] is installed globally, e.g. with `pipx install pre-commit`,
and then you are already set up to start hacking. Use `hatch run test` to run the unit tests or `hatch run vcr-only`
to run the offline unit tests using [VCR.py]. Regenerate the cassettes with `hatch run vcr-rewrite`.
Check out the environment setup of hatch in [pyproject.toml](pyproject.toml) for many more commands.
If you are using [VS Code], it's quite convenient to create a file `.vscode/.env` with
```ini
NOTION_TOKEN=TOKEN_TO_YOUR_TEST_NOTION_ACCOUNT
ULTIMATE_NOTION_CONFIG=/path/to/repo/.ultimate-notion/config.toml
```
Check out this [page about contributing] for more details.
## 📄 License & Credits
Ultimate Notion is released under the terms of the [MIT license](LICENSE.txt).
It is built on top of [notion-sdk-py] and was initially inspired by [notional],
with the overall project structure adapted from [hatch].
Documentation is created using [Material for MkDocs] and hosted on [GitHub Pages].
[Notion]: https://www.notion.so/
[hatch]: https://hatch.pypa.io/
[pre-commit]: https://pre-commit.com/
[notional]: https://github.com/jheddings/notional/
[notion-sdk-py]: https://github.com/ramnes/notion-sdk-py/
[Material for MkDocs]: https://github.com/squidfunk/mkdocs-material
[GitHub Pages]: https://docs.github.com/en/pages
[Ultimate Notion documentation]: https://ultimate-notion.com/
[creating a Notion integration]: https://ultimate-notion.com/latest/usage/getting_started/
[page about contributing]: https://ultimate-notion.com/latest/contributing/
[VS Code]: https://code.visualstudio.com/
[PyPI]: https://pypi.org/
[VCR.py]: https://vcrpy.readthedocs.io/
[Discussion]: https://github.com/ultimate-notion/ultimate-notion/discussions
[Tests-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/run-tests.yml/badge.svg
[Tests-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/run-tests.yml
[Coverage-image]: https://img.shields.io/coveralls/github/ultimate-notion/ultimate-notion/master.svg?logo=coveralls&label=Coverage
[Coverage-link]: https://coveralls.io/r/ultimate-notion/ultimate-notion
[Publish-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/publish-pkg.yml/badge.svg
[Publish-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/publish-pkg.yml
[EffVer-image]: https://img.shields.io/badge/Versioning-EffVer-0097a7
[EffVer-link]: https://jacobtomlinson.dev/effver
[Docs-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/build-dev-docs.yml/badge.svg
[Docs-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/build-dev-docs.yml
[PyPI_ver-image]: https://img.shields.io/pypi/v/ultimate-notion.svg?logo=pypi&label=PyPI&logoColor=gold
[PyPI_ver-link]: https://pypi.org/project/ultimate-notion/
[PyPI_down-image]: https://img.shields.io/pypi/dm/ultimate-notion.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold
[PyPI_down-link]: https://clickpy.clickhouse.com/dashboard/ultimate-notion
[PyPI_py-image]: https://img.shields.io/pypi/pyversions/ultimate-notion.svg?logo=python&label=Python&logoColor=gold
[PyPI_py-link]: https://pypi.org/project/ultimate-notion/
[hatch-image]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg
[hatch-link]: https://github.com/pypa/hatch
[ruff-image]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[ruff-link]: https://github.com/charliermarsh/ruff
[mypy-image]: https://img.shields.io/badge/Types-mypy-blue.svg
[mypy-link]: https://mypy-lang.org/
[MIT-image]: https://img.shields.io/badge/License-MIT-9400d3.svg
[MIT-link]: LICENSE.txt
[sponsor-image]: https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=ff69b4
[sponsor-link]: https://github.com/sponsors/FlorianWilhelm
[mkdocs-image]: https://img.shields.io/static/v1?label=&message=mkdocs&logo=Material+for+MkDocs&color=526CFE&logoColor=white
[mkdocs-link]: https://ultimate-notion.com/
[precommit-image]: https://img.shields.io/static/v1?label=&message=pre-commit&logo=pre-commit&color=76877c
[precommit-link]: https://pre-commit.com/
[pytest-image]: https://img.shields.io/static/v1?label=&message=Pytest&logo=Pytest&color=0A9EDC&logoColor=white
[pytest-link]: https://docs.pytest.org/
[simple setup guide]: https://ultimate-notion.com/latest/usage/getting_started/
[feature breakdown]: https://ultimate-notion.com/latest/features/
Raw data
{
"_id": null,
"home_page": null,
"name": "ultimate-notion",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "notion, notion client",
"author": null,
"author_email": "Florian Wilhelm <Florian.Wilhelm@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/94/ac/837d466a1ca64087a893c42bf653719480ab81fdcf861bec7f010e48dcdd/ultimate_notion-0.9.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img\nsrc=\"https://raw.githubusercontent.com/ultimate-notion/ultimate-notion/master/docs/assets/images/logo_with_text.svg\"\nalt=\"Ultimate-Notion logo\" width=\"500\" role=\"img\">\n</div>\n<br/>\n\nUltimate Notion is the ultimate Python client for [Notion]!\n\n| | |\n|---------|------------------------------------|\n| CI/CD | [![Tests][Tests-image]][Tests-link] [![Coverage][Coverage-image]][Coverage-link] [![Publish Package][Publish-image]][Publish-link] [![Build Docs][Docs-image]][Docs-link] [![EffVer Versioning][EffVer-image]][EffVer-link] |\n| Package | [![PyPI - Version][PyPI_ver-image]][PyPI_ver-link] [![PyPI - Downloads][PyPI_down-image]][PyPI_down-link] [![PyPI - Python Version][PyPI_py-image]][PyPI_py-link] [![GitHub Sponsors][sponsor-image]][sponsor-link] |\n| Details | [![Hatch project][hatch-image]][hatch-link] [![Linting - Ruff][ruff-image]][ruff-link] [![Pre-Commit][precommit-image]][precommit-link] [![test - pytest][pytest-image]][pytest-link] [![Types - Mypy][mypy-image]][mypy-link] [![License - MIT][MIT-image]][MIT-link] [![Docs - mkdocs][mkdocs-image]][mkdocs-link] |\n\n## \u2728 Features\n\n- \ud83d\udc0d **Pythonic API** \u2014 Clean, intuitive Python interfaces with robust type annotations.\n- \ud83d\uddc2\ufe0f **CRUD operations** \u2014 Create, read, update, and delete Notion pages, databases, and blocks.\n- \ud83d\udd0e **Rich querying capabilities** \u2014 Support for filters, sorting, pagination, and searching.\n- \ud83e\ude84 **Flexible exports** \u2014 Convert Notion pages to Markdown, HTML, and databases to pandas, Polars.\n- \u2b06\ufe0f **File upload support** \u2014 Easily upload and manage files in Notion pages and databases.\n- \ud83e\udde9 **Built atop notion-sdk-py** \u2014 Enhancing the functionality of the popular low-level client.\n- \ud83d\udcaf **100% feature parity** \u2014 Full compatibility with all notion-sdk-py capabilities and more.\n- \ud83d\udda5\ufe0f **Command line interface** \u2014 Convenient CLI for quick operations and automation scripts.\n- \ud83d\udd12 **Token-based authentication** \u2014 Secure access using Notion integration tokens.\n- \ud83d\ude80 **One-step setup** \u2014 Getting up to speed with a [simple setup guide].\n\n\ud83d\udc49 Want to learn more? Explore the full [feature breakdown].\n\n## \ud83d\udce6 Installation\n\nInstall the most recent release using [PyPI] with:\n\n```console\npip install ultimate-notion\n```\n\nor to install all additional dependencies, use:\n\n```console\npip install 'ultimate-notion[all]'\n```\n\n### \ud83e\uddea Installing the Development Version\n\nTo install the latest (potentially unstable) version directly from the main branch on GitHub:\n\n```console\npip install git+https://github.com/ultimate-notion/ultimate-notion.git@main\n```\n\nor with all optional dependencies:\n\n```console\npip install 'ultimate-notion[all] @ git+https://github.com/ultimate-notion/ultimate-notion.git@main'\n```\n\n## \ud83d\ude80 Usage\n\nMake sure you have set the environment variable `NOTION_TOKEN` to your Notion\nintegration token. Then it's as simple as:\n\n```python\nimport ultimate_notion as uno\n\nPAGE_TITLE = 'Getting Started'\n\nwith uno.Session() as notion:\n page = notion.search_page(PAGE_TITLE).item()\n page.show()\n\n# Alternatively, without a context manager:\nnotion = uno.Session()\npage = notion.search_page(PAGE_TITLE).item()\npage.show()\nnotion.close()\n```\n\nCheck out the official [Ultimate Notion documentation] for more details.\nEspecially the page about [creating a Notion integration] to get the token.\n\n## \ud83d\udcac Getting help\n\nIf you are stuck with a problem and need help or just want to brag about what you did,\nthe [Discussion] area is the right place for you. Here, you can ask questions, provide\nsuggesions and discuss with other users.\n\n## \ud83e\udd1d Contributing\n\nAfter having cloned this repository:\n\n1. make sure [hatch] is installed globally, e.g. `pipx install hatch`,\n2. make sure [pre-commit] is installed globally, e.g. with `pipx install pre-commit`,\n\nand then you are already set up to start hacking. Use `hatch run test` to run the unit tests or `hatch run vcr-only`\nto run the offline unit tests using [VCR.py]. Regenerate the cassettes with `hatch run vcr-rewrite`.\nCheck out the environment setup of hatch in [pyproject.toml](pyproject.toml) for many more commands.\n\nIf you are using [VS Code], it's quite convenient to create a file `.vscode/.env` with\n\n```ini\nNOTION_TOKEN=TOKEN_TO_YOUR_TEST_NOTION_ACCOUNT\nULTIMATE_NOTION_CONFIG=/path/to/repo/.ultimate-notion/config.toml\n```\n\nCheck out this [page about contributing] for more details.\n\n## \ud83d\udcc4 License & Credits\n\nUltimate Notion is released under the terms of the [MIT license](LICENSE.txt).\nIt is built on top of [notion-sdk-py] and was initially inspired by [notional],\nwith the overall project structure adapted from [hatch].\nDocumentation is created using [Material for MkDocs] and hosted on [GitHub Pages].\n\n[Notion]: https://www.notion.so/\n[hatch]: https://hatch.pypa.io/\n[pre-commit]: https://pre-commit.com/\n[notional]: https://github.com/jheddings/notional/\n[notion-sdk-py]: https://github.com/ramnes/notion-sdk-py/\n[Material for MkDocs]: https://github.com/squidfunk/mkdocs-material\n[GitHub Pages]: https://docs.github.com/en/pages\n[Ultimate Notion documentation]: https://ultimate-notion.com/\n[creating a Notion integration]: https://ultimate-notion.com/latest/usage/getting_started/\n[page about contributing]: https://ultimate-notion.com/latest/contributing/\n[VS Code]: https://code.visualstudio.com/\n[PyPI]: https://pypi.org/\n[VCR.py]: https://vcrpy.readthedocs.io/\n[Discussion]: https://github.com/ultimate-notion/ultimate-notion/discussions\n\n[Tests-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/run-tests.yml/badge.svg\n[Tests-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/run-tests.yml\n[Coverage-image]: https://img.shields.io/coveralls/github/ultimate-notion/ultimate-notion/master.svg?logo=coveralls&label=Coverage\n[Coverage-link]: https://coveralls.io/r/ultimate-notion/ultimate-notion\n[Publish-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/publish-pkg.yml/badge.svg\n[Publish-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/publish-pkg.yml\n[EffVer-image]: https://img.shields.io/badge/Versioning-EffVer-0097a7\n[EffVer-link]: https://jacobtomlinson.dev/effver\n[Docs-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/build-dev-docs.yml/badge.svg\n[Docs-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/build-dev-docs.yml\n[PyPI_ver-image]: https://img.shields.io/pypi/v/ultimate-notion.svg?logo=pypi&label=PyPI&logoColor=gold\n[PyPI_ver-link]: https://pypi.org/project/ultimate-notion/\n[PyPI_down-image]: https://img.shields.io/pypi/dm/ultimate-notion.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold\n[PyPI_down-link]: https://clickpy.clickhouse.com/dashboard/ultimate-notion\n[PyPI_py-image]: https://img.shields.io/pypi/pyversions/ultimate-notion.svg?logo=python&label=Python&logoColor=gold\n[PyPI_py-link]: https://pypi.org/project/ultimate-notion/\n[hatch-image]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg\n[hatch-link]: https://github.com/pypa/hatch\n[ruff-image]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n[ruff-link]: https://github.com/charliermarsh/ruff\n[mypy-image]: https://img.shields.io/badge/Types-mypy-blue.svg\n[mypy-link]: https://mypy-lang.org/\n[MIT-image]: https://img.shields.io/badge/License-MIT-9400d3.svg\n[MIT-link]: LICENSE.txt\n[sponsor-image]: https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=ff69b4\n[sponsor-link]: https://github.com/sponsors/FlorianWilhelm\n[mkdocs-image]: https://img.shields.io/static/v1?label=\u200e&message=mkdocs&logo=Material+for+MkDocs&color=526CFE&logoColor=white\n[mkdocs-link]: https://ultimate-notion.com/\n[precommit-image]: https://img.shields.io/static/v1?label=\u200e&message=pre-commit&logo=pre-commit&color=76877c\n[precommit-link]: https://pre-commit.com/\n[pytest-image]: https://img.shields.io/static/v1?label=\u200e&message=Pytest&logo=Pytest&color=0A9EDC&logoColor=white\n[pytest-link]: https://docs.pytest.org/\n[simple setup guide]: https://ultimate-notion.com/latest/usage/getting_started/\n[feature breakdown]: https://ultimate-notion.com/latest/features/\n",
"bugtrack_url": null,
"license": null,
"summary": "The ultimate Python client for Notion!",
"version": "0.9.1",
"project_urls": {
"Changelog": "https://ultimate-notion.com/latest/changelog/",
"Documentation": "https://ultimate-notion.com/latest/usage/getting_started/",
"Download": "https://pypi.org/project/ultimate-notion/#files",
"Homepage": "https://ultimate-notion.com",
"Source": "https://github.com/ultimate-notion/ultimate-notion",
"Sponsor": "https://github.com/sponsors/FlorianWilhelm",
"Tracker": "https://github.com/ultimate-notion/ultimate-notion/issues"
},
"split_keywords": [
"notion",
" notion client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "64102dc9001a0ff54f99bee338fe32e38943de6ff584bbd6b9e19631d2db8b3d",
"md5": "e3d0caa6c4f3ad06273b8b7c7551061a",
"sha256": "3fc97f9b1f7ab1a33fecb3039b5e9112f240ad25e4122bcf7fbd29f2b7c51c78"
},
"downloads": -1,
"filename": "ultimate_notion-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3d0caa6c4f3ad06273b8b7c7551061a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 131767,
"upload_time": "2025-09-03T18:53:18",
"upload_time_iso_8601": "2025-09-03T18:53:18.225564Z",
"url": "https://files.pythonhosted.org/packages/64/10/2dc9001a0ff54f99bee338fe32e38943de6ff584bbd6b9e19631d2db8b3d/ultimate_notion-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "94ac837d466a1ca64087a893c42bf653719480ab81fdcf861bec7f010e48dcdd",
"md5": "c8f66c3bf6ea17c8ac27ecab3e98b09b",
"sha256": "13a1ec80aa3a2a5f91a5913fdec3d3d2c1954f2e920a31f58465b2026941a3a2"
},
"downloads": -1,
"filename": "ultimate_notion-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "c8f66c3bf6ea17c8ac27ecab3e98b09b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 113641,
"upload_time": "2025-09-03T18:53:20",
"upload_time_iso_8601": "2025-09-03T18:53:20.038892Z",
"url": "https://files.pythonhosted.org/packages/94/ac/837d466a1ca64087a893c42bf653719480ab81fdcf861bec7f010e48dcdd/ultimate_notion-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 18:53:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ultimate-notion",
"github_project": "ultimate-notion",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ultimate-notion"
}
