# Setup and Auth

Use this reference for imports, tokens, Notion integration access, and ID handling.

## Import and Initialize

```python
import os
from notionhelper import NotionHelper

helper = NotionHelper(os.environ["NOTION_TOKEN"])
```

Constructor options:

```python
helper = NotionHelper(
    notion_token=os.environ["NOTION_TOKEN"],
    debug=True,
    max_retries=3,
    retry_base_delay=1.0,
    request_timeout=30.0,
)
```

Use `MLNotionHelper` only for experiment tracking workflows; it inherits the base `NotionHelper` methods.

## Token Rules

- Read tokens from environment variables, app secrets, or a secret manager.
- Never commit tokens, paste them into source files, or log the `Authorization` header.
- If Notion returns 401 or 403, check both the token and whether the page/database was shared with the integration.

## Integration Access

Notion integrations can only access objects explicitly shared with them. If `NotFoundError` occurs for a valid ID, the object may not be shared with the integration.

## IDs

Use IDs according to the Notion object:

- `database_id`: database container.
- `data_source_id`: table/schema inside a database; use this to query and create rows.
- `page_id`: standalone page or row page.

Normalize a page URL or raw ID with:

```python
page_id = helper.extract_page_id_from_url(page_url_or_id)
```

This accepts hyphenated UUIDs, compact 32-character IDs, and shared page URLs.
