Function namespace generator retirement plan#

scripts/generate_function_namespaces.py still emits the massive duckplus.static_typed._generated_function_namespaces module so that static helper classes can mirror DuckDB’s catalog. Now that helpers are registered through import-time decorators, we can retire the generator once the per-function modules provide complete coverage.

Why the generator is being retired#

  • Decorator-based registration already binds helpers directly to duckplus.duckcon.DuckCon and the typed expression namespaces. Keeping a generator that writes dictionary literals works against the direct-Python design constraint.

  • The generated module is difficult to audit or review. Per-function modules keep signatures and documentation close to the implementation so tooling can inspect them at import time.

  • Removing the generator eliminates a DuckDB connection requirement from the build toolchain and simplifies contributor setup.

Readiness criteria#

Before the generator can be removed, all of the following must be true:

  1. Every helper emitted today has a hand-authored module that registers the same behaviour through decorators during import.

  2. Tests in tests/test_typed_function_namespace.py cover the decorator-backed namespaces without importing _generated_function_namespaces.

  3. Documentation in docs/typed_api.md and release notes reference the new modules directly so contributors know where helpers live.

  4. duckplus/typed/functions.py and other compatibility shims emit clear deprecation warnings when the generated catalog is imported, nudging downstream code to adopt the new modules.

  5. The release branch that removes the generator keeps the old module in the git history so tags can rebuild past releases if required.

Migration timeline#

Release

Status

1.2.0

Ship decorator-backed modules alongside the generated catalog and mark the generator as deprecated in release notes.

1.3.0

Stop importing _generated_function_namespaces by default. Tests should fail if the generator is required.

1.4.0

Publish scalar macro overrides from decorator-backed modules, refresh release docs to point at the override packages, and delete scripts/generate_function_namespaces.py once parity is confirmed.

If the decorator-backed modules slip, push the retirement by one minor release while keeping the deprecation notice active.

Contributor expectations#

  • Move helpers into duckplus/typed/functions/ (or a similar per-function directory) and register them with the existing decorators.

  • Update or add tests as helpers graduate from the generated catalog so we can detect gaps early.

  • Mention the migration window in pull requests that touch typed functions so reviewers can keep the roadmap in view.

Communication plan#

  • Reference this plan from docs/registry_inventory.md so contributors can find the retirement schedule while auditing registries.

  • Summarise progress and remaining blockers in TODO.md under the “Active Notes” section whenever the status changes.

  • When the generator is finally removed, record the breaking change in the changelog and update prior release documentation so the removal history stays discoverable.