Repository navigation
ADR 0012 arrow pycapsule bulk path
The Python package will offer one bulk path for whole columns of dates, through the Arrow PyCapsule Interface, instead of separate NumPy and Arrow code paths.
Last reviewed: 31 Oct 2026
Accepted on 31 Oct 2026. Decided by the research documents: the research proposal ("Ecosystem bindings") and the gap analysis ("Binding and platform risks"). Planned for 0.2 on the Roadmap. Not built in 0.1.0, where every Python call handles one value.
Data engineers apply a calendar to millions of dates at once. The proposal argues that most of the time for a single date goes into crossing the language boundary, so a bulk path is where a compiled core should pay off. That is a claim to be measured by the per-binding benchmarks planned for 0.2; it is not measured yet.
The gap analysis recommended one path through the Arrow PyCapsule Interface rather than separate NumPy and Arrow paths. Its source, the Polars user guide, lists "No required dependency on pyarrow." among the benefits for library maintainers (Polars). The research documents quoted this in lower case; the source capitalises it (Evidence). The documents also say the interface works with Polars, pyarrow, DuckDB and Arrow-backed pandas; the Polars page does not name DuckDB or pandas, so that part is unverified.
- No required heavy dependency for users who never use the bulk path.
- One code path to test, not one per data-frame library.
- Results identical to the per-value path.
Pros:
- NumPy is widely installed.
Cons:
- Makes NumPy a dependency, and Polars and Arrow users need conversions.
Pros:
- Full Arrow support.
Cons:
- pyarrow is a large dependency for a small library.
Pros:
- Exchanges Arrow data with libraries that implement the interface, with no required pyarrow dependency (per the Polars guide).
Cons:
- Users of libraries that do not implement the interface still need a conversion.
- Needs Arrow-aware code in the binding or the core, which must stay a conversion layer under ADR-0002.
Pros:
- Native Polars expressions with no Python per row.
Cons:
- The proposal notes a plug-in must be built for each supported Polars version; it plans one later, as a separate package, only on demand.
Option 3 as the one Python bulk path, with the Polars plug-in (Option 4) deferred until there is demand. The bulk path must return the same values as the per-value API for every conformance case.
Good:
- No new required Python dependency.
Bad:
- 0.1.0 users process columns by looping in Python, which the proposal expects to be slower; how much slower is unmeasured.
- Which libraries work with the path is partly unverified (see Context); that needs checking before the documentation claims it.
fiscalclock is licensed under MIT OR Apache-2.0 (MIT, Apache-2.0). Last reviewed: 31 Oct 2026. Found an error on this page? Report it with the documentation form.