iaxys-notion-utils 0.2.0

Abstraction layer for the Notion API with declarative schema mapping

notion-api-utils

Abstraction layer for the Notion API. Define schemas declaratively and convert Python dicts to Notion's JSON format without writing boilerplate.

Install

pip install notion-api-utils

Usage

from notion_api_utils import Schema, Field, Title, RichText, Number, Select, Date, to_notion_properties

# Define a schema mapping your data to Notion properties
schema = Schema(fields={
    "name":   Field("Name", Title),
    "email":  Field("Email", Email),
    "age":    Field("Age", Number),
    "status": Field("Status", Select),
    "date":   Field("Created At", Date),
})

# Your data
data = {
    "name": "Lucas",
    "email": "[e-mail]",
    "age": 25,
    "status": "Active",
    "date": "2026-03-25",
}

# Convert to Notion properties JSON
properties = to_notion_properties(data, schema)
# Use `properties` in your Notion API call body

Output:

{
  "Name": {"title": [{"text": {"content": "Lucas"}}]},
  "Email": {"email": "[e-mail]"},
  "Age": {"number": 25},
  "Status": {"select": {"name": "Active"}},
  "Created At": {"date": {"start": "2026-03-25"}}
}

Supported Property Types

Type	Input
Title	str
RichText	str
Number	int | float
Select	str
MultiSelect	list[str]
Date	str | date | datetime or {"start": ..., "end": ...}
Checkbox	bool
Email	str
Url	str
PhoneNumber	str
Status	str
Relation	list[str] (page IDs)
People	list[str] (user IDs)
Files	list[str] (URLs)

Custom Source Key

When your dict key differs from the schema key:

schema = Schema(fields={
    "nome": Field("Name", Title, source_key="nome_completo"),
})

data = {"nome_completo": "Lucas"}
properties = to_notion_properties(data, schema)