NotionHelper

NotionHelper is a Python library that provides a convenient interface for interacting with the Notion API. It simplifies common tasks such as managing databases, pages, and file uploads, allowing you to integrate Notion's powerful features into your applications with ease.

For help constructing the JSON for the properties, use the Notion API - JSON Builder Streamlit app.

Features

Synchronous Operations: Uses notion-client and requests for straightforward API interactions.
Database Management: Create, query, and retrieve Notion databases.
Page Operations: Add new pages to databases and append content to existing pages.
File Handling: Upload files and attach them to pages or page properties.
Pandas Integration: Convert Notion database pages into a Pandas DataFrame for easy data manipulation.

Installation

To install NotionHelper, you can use pip:

pip install notionhelper

This will also install all the necessary dependencies, including notion-client, pandas, and requests.

Authentication

To use the Notion API, you need to create an integration and obtain an integration token.

Create an Integration: Go to My Integrations and create a new integration.
Get the Token: Copy the "Internal Integration Token".
Share with a Page/Database: For your integration to access a page or database, you must share it with your integration from the "Share" menu in Notion.

It is recommended to store your Notion token as an environment variable for security.

export NOTION_TOKEN="your_secret_token"

Usage

Here is an example of how to use the library:

import os
from notionhelper import NotionHelper

Initialize the NotionHelper class

notion_token = os.getenv("NOTION_TOKEN")

helper = NotionHelper(notion_token)

Retrieve a Database

database_id = "your_database_id"
database_schema = helper.get_database(database_id)
print(database_schema)

Create a New Page in a Database

page_properties = {
    "Name": {
        "title": [
            {
                "text": {
                    "content": "New Page from NotionHelper"
                }
            }
        ]
    }
}
new_page = helper.new_page_to_db(database_id, page_properties)
print(new_page)

Append Content to the New Page

blocks = [
    {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
            "rich_text": [{"type": "text", "text": {"content": "Hello from NotionHelper!"}}]
        }
    },
    {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
            "rich_text": [
                {
                    "type": "text",
                    "text": {
                        "content": "This content was appended synchronously."
                    }
                }
            ]
        }
    }
]
helper.append_page_body(page_id, blocks)
print(f"Successfully appended content to page ID: {page_id}")

Get all pages as a Pandas DataFrame

  df = helper.get_all_pages_as_dataframe(database_id)
  print(df.head())

Upload a File and Attach to a Page

file_path = "path/to/your/file.pdf"  # Replace with your file path
upload_response = helper.upload_file(file_path)
file_upload_id = upload_response["id"]
# Replace with your page_id
page_id = "your_page_id"
attach_response = helper.attach_file_to_page(page_id, file_upload_id)
print(f"Successfully uploaded and attached file: {attach_response}")

Metadata

Release files for notionhelper 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for notionhelper 0.1.1
File	Size	Uploaded
notionhelper-0.1.1.tar.gz	4.0 MB	Jul 17, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for notionhelper 0.1.1
File	Interpreter	ABI	Platform	Reset
notionhelper-0.1.1-py3-none-any.whl 7.0 kB Jul 17, 2025	Python 3	none	any	Details

Total release size: 4.0 MB

Release files / notionhelper-0.1.1.tar.gz

Download URL	notionhelper-0.1.1.tar.gz
Size	4.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`d85b050832a72957b883b48dc67ef2ce6b86fe3d66784c7a65e1051347a0592d`
BLAKE2b-256 checksum How to use checksums	`391123e2df593bd5dc4feb883b995920c685c34f61bb643bd3b8825dec3c5dd0`
Upload date	Jul 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.7.14`

Release files / notionhelper-0.1.1-py3-none-any.whl

Download URL	notionhelper-0.1.1-py3-none-any.whl
Size	7.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8a9beb37478bda4e83fa5ad58a9cce9990c9c5af297589161879b6396c5a5b47`
BLAKE2b-256 checksum How to use checksums	`735769f6a3e76a92b585c49eca613b898a5f349422b6b4a9bcde4380c5379bc9`
Upload date	Jul 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.7.14`