Metadata-Version: 2.4
Name: iaxys-notion-utils
Version: 0.2.5
Summary: Abstraction layer for the Notion API with declarative schema mapping
License-Expression: MIT
Requires-Python: >=3.7
Requires-Dist: httpx
Description-Content-Type: text/markdown

# 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

```bash
pip install notion-api-utils
```

## Usage

```python
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": "lucas@example.com",
    "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:

```json
{
  "Name": {"title": [{"text": {"content": "Lucas"}}]},
  "Email": {"email": "lucas@example.com"},
  "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:

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

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