DuckPlus 1.4.7

DuckPlus 1.4.7 finalises the 1.4 series by locking the static typed contracts to what ships on PyPI. The ty and mypy suites now exercise the entire static-typed API surface, and the release gate demands 100 percent parity so editor integrations stay aligned with runtime behaviour. Unsigned integer factories are exported alongside the rest of the numeric hierarchy and type-casting now infers their DuckDB representations automatically, rounding out the migration away from generated registries.

Earlier 1.4.x releases extended the direct-Python helper strategy to DuckDB’s scalar macro surface so decorator-backed modules now publish the split_part family, array helpers, and PostgreSQL catalog shims. The static typed API imports those modules during package initialisation, ensuring both runtime and typed namespaces resolve the real helper implementations instead of the generated function catalog. The macro helpers remain bound to their expression classes, enabling fluent method calls like ducktype.Generic("items").array_to_string(", ") without dropping down to the namespace objects. Documentation and package metadata highlight the macro migration so contributors can rely on the override modules when exploring the function surface.

Tip

All code snippets in the 1.4 guides run against the duckplus package published on PyPI. They assume Python 3.11+ and DuckDB 0.10+; if you are pinned to an older runtime, consult the ../typed_api appendix for migration notes and breaking-change callouts.

Release highlights

• Ty and mypy parity contracts – Version-gated integration tests now enforce 100 percent agreement between the type checkers and the runtime API surface, ensuring editors surface every helper and diagnostic that succeeds in Python.

• Unsigned integer factory exports – Uinteger, Usmallint, and Utinyint factories are public package members, and casting derives their DuckDB types automatically so literal parsing and expression casts stay consistent.

• Decorator-backed scalar macros – DuckPlus 1.4 adds :mod:duckplus.functions.scalar modules for string, list, PostgreSQL catalog, privilege, and visibility macros. Import-time decorators register overloads on the correct namespaces so IDEs and documentation resolve the Python implementations instead of generated metadata.

• Fluent macro chaining – Static typed overrides now attach string and array macros directly to their corresponding expression classes (for example, VarcharExpression.split_part and GenericExpression.array_to_string), so user code can chain helpers without manually referencing the typed namespaces.

• Typed namespace override coverage – :mod:duckplus.static_typed now imports the macro override package by default, replacing the generated entries with the decorator-backed helpers as soon as the typed namespace loads. Regression tests pin helper provenance so future migrations stay honest.

• Documentation alignment for macros – the Sphinx build and release guides describe the new macro buckets and link directly to the override modules so contributors can find the canonical implementations without spelunking through generated sources.

The sections below walk through the features in increasing depth. Jump straight to the area you care about or read sequentially to build a mental model of the entire stack.

Start here

• Getting started
  • Verifying your environment
  • Opening a connection
  • Working with immutable relations
  • Typed expression DSL
  • Next steps
  • Documentation navigation
• Connection management with DuckCon
  • Lifecycle management
  • Extension loading
  • Connection configuration
  • Relationship with relations
  • Registering custom helpers
  • Testing patterns
• Immutable relation helpers
  • Constructing relations
  • Column management
  • Projection builder
  • Aggregation and window functions
  • Filtering and joins
  • Schema utilities
  • Introspection and diagnostics
  • Exporting data
• Typed expression API
  • Creating typed expressions
  • Arithmetic and comparison helpers
  • Aggregation helpers
  • Window functions
  • Conditional expressions and aliases
  • Scalar helpers
  • Select builder
  • Debugging typed expressions
• DuckDB function modules
  • Importing the aggregate helpers
  • Working within a domain package
  • Scalar string macro helpers
  • Scalar list macro helpers
  • Scalar catalog macro helpers
  • Scalar PostgreSQL privilege macro helpers
  • Scalar PostgreSQL visibility macro helpers
  • When to add new modules
• File and table readers
  • CSV reader
  • Parquet reader
  • JSON, Arrow, and database connectors
  • Composing with custom helpers
• File append helpers
  • CSV appends
  • Parquet appends
  • Table utilities
• Community extension coverage
  • Nano-ODBC
  • Excel
  • Bundled extensions
  • Roadmap
• Schema management
  • Inspecting schemas
  • Diffing relations
  • Exporters
  • Table utilities
• Practitioner demos
  • Language Server Demonstration
  • Sanitised traceability pipeline
  • DuckDB demo parity guides

If you are upgrading from DuckPlus 1.3, the Getting started chapter highlights the stable import paths while the deep-dive guides explain how each helper composes with DuckDB. The derived :doc:practitioner_demos include a DuckDB parity checklist that mirrors the interactive demo site, and the expanded :doc:core/function_modules page documents the direct-Python helper catalog so static tooling and application developers can reason about DuckPlus without inspecting the generated sources.