Skip to content

notion

diapason.connectors.notion

Notion connector — syncs pages via the Notion REST API.

Uses a Notion internal integration token stored locally. All network calls are isolated in module-level functions (_notion_api_*) to make them trivially mockable in tests.

Users create an internal integration at https://www.notion.so/my-integrations and paste the generated token to authenticate.

NotionConnector

Bases: BaseConnector

Connector that syncs pages from Notion via the REST API.

Authentication uses a Notion internal integration token. Users create an integration at https://www.notion.so/my-integrations and paste the generated secret token.

Parameters

token: Notion integration token. If provided, it takes priority over any stored credentials file. credentials_path: Path to the JSON file where the token is stored. Defaults to ~/.diapason/connectors/notion.json.

auth_url()

Return the URL where users can create a Notion integration token.

disconnect()

Clear the in-memory token and delete the stored credentials file.

handle_callback(code)

Persist the integration token to the credentials file.

The code parameter holds the raw token string (pasted by the user).

is_connected()

Return True if a valid token is available.

mcp_tools()

Expose two MCP tool specs for real-time Notion queries.

sync(*, since=None, cursor=None)

Yield :class:Document objects for Notion pages.

Paginates through /v1/search and fetches block content for each page, rendering it to markdown.

Parameters

since: If provided, skip pages whose last_edited_time is before this datetime. cursor: next_cursor from a previous sync to resume pagination.

sync_status()

Return sync progress from the most recent :meth:sync call.