feat(connector): Notion database target

[badmonster0]

Summary

Adds cocoindex.connectors.notion — a declarative target for Notion databases (called data sources in the 2025-09-03 API), with the same upsert + automatic-delete reconcile semantics as connectors.postgres.

Two modes:

• managed_by="user" (default) — point at an existing data source; the connector validates the live property schema matches at mount, then syncs rows.
• managed_by="system" — give the connector a parent page or database plus a title; it finds or creates the data source on first run, PATCH-adds new properties as the dataclass grows, and rejects destructive changes unless allow_destructive=True.

The archive-on-undeclare path is the main thing the hand-rolled HTTP code in cocoindex-gtm couldn't do — drop a row from the declared set, re-run, the matching Notion page gets archived.

Design doc (approved): https://www.notion.so/372daa511a0880fea8c2d9852b1d9f82

What's in this PR

• Connector (python/cocoindex/connectors/notion/):

  • NotionClient — token-scoped, async, rate-limited (3 req/s semaphore), Retry-After-aware exponential backoff (inline manual retry — no tenacity dep).
  • DatabaseSchema — binds a Python row class to Notion properties via Annotated[T, notion.SomeProp(...)] (or property_map={...}). Validates against the live data source at mount; diff_against() splits additive from destructive changes.
  • mount_database_target(client, data_source_id=None, schema, *, managed_by, parent_page_id, parent_database_id, title, on_delete, allow_destructive) — plus the lower-level database_target and declare_database_target.
  • 9 property types: TitleProp, RichTextProp, NumberProp, UrlProp, EmailProp, SelectProp, MultiSelectProp, DateProp, CheckboxProp. Each has encode / decode / to_notion_schema() for create/PATCH bodies.
  • Query-on-miss page_id resolution (one Notion query per unknown PK, cached for the rest of the run).
  • OnDelete.ARCHIVE (default) / HARD / IGNORE.

• Test suite (python/tests/connectors/test_notion_target.py, 12 cases — all passing locally against a real Notion workspace):

  • 3 schema-validation tests that don't touch Notion (run anywhere):
    • test_property_map_typo_raises
    • test_schema_requires_at_most_one_title
    • test_managed_by_args_validation
  • 9 integration tests gated by NOTION_TEST_TOKEN + NOTION_TEST_PARENT_PAGE:
    • test_insert_update_archive — full lifecycle: insert 3, update 1, drop 1 → drops archived
    • test_on_delete_ignore_leaves_page — OnDelete.IGNORE doesn't touch the page on undeclare
    • test_on_delete_hard — OnDelete.HARD actually removes from active queries
    • test_noop_when_no_changes — re-run with identical data → zero PATCHes (verified via last_edited_time)
    • test_property_types_roundtrip — title + rich_text + number + url + checkbox + select + date all round-trip cleanly
    • test_first_run_against_existing_page — pre-seeded page with declared PK gets PATCHed, not duplicated (query-on-miss happy path)
    • test_schema_validation_type_mismatch — wrong type at mount → ValueError, zero writes
    • test_schema_validation_missing_property — missing column at mount → ValueError, zero writes
    • test_system_creates_and_evolves — system mode creates the data source on first run, PATCH-adds a new property on the second run

  Suite runs in ~42s end-to-end. Each integration test creates its own temp data source and archives it in teardown.

• Docs: docs/src/content/docs/connectors/notion.mdx covers connection setup, both modes, all property types, delete strategies, page-id persistence, and the four Notion-API setup gotchas (integration sharing, parent access, internal vs public integrations, API version pinning). Sidebar entry added.

• Example: examples/notion_target_basics/ — runnable demo with Person rows + README showing the insert / no-op / archive lifecycle.

• Packaging: pyproject.toml gains a notion optional extra (aiohttp only).

Deferred to follow-up PRs

• RelationProp / PeopleProp / FilesProp — these prop types aren't enumerated in the design doc and relations specifically need cross-target ordering, which is its own design problem. Out of scope here, happy to add RelationProp if you want.

CI status

• fast-check (ruff format/lint, end-of-file fixers, etc.): pass
• e2e-type-check (strict mypy, Python 3.11–3.14): pass on all four versions
• build-test (Rust compile + pytest across Linux/macOS/Windows): in progress — Linux 3.11, Linux 3.14, macOS 3.11 already passing.

Test plan

• All 12 tests pass locally against a real Notion workspace (pytest python/tests/connectors/test_notion_target.py, ~42s).
• Connector imports clean (from cocoindex.connectors import notion).
• Manual end-to-end via the examples/notion_target_basics demo also still works.
• CI matrix entries for macOS-15-intel, macOS-3.14, Ubuntu-arm, Windows-3.11, Windows-3.14 still pending — those are slower architectures and will signal whether the test pattern is portable.

🤖 Generated with Claude Code