Repository navigation
feat(python): ship public API type stubs - #50
Merged
Merged
Conversation
Add PEP 561 stubs matching the extension graph module, strict consumer checks, and runtime signature parity tests. Document the typing workflow and check wheel inclusion. Runtime and benchmark validation remain pending the coordinated build.
# Conflicts: # docs/api-reference.md
prrao87
marked this pull request as ready for review
October 26, 2026 16:37
Deploying lance-csr with
|
| Latest commit: |
9e4cbb8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://15da7386.lance-csr.pages.dev |
| Branch Preview URL: | https://codex-issue-22-python-stubs.lance-csr.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem and change
Resolves #22. Publish PEP 561 typing metadata for the compiled
lance_csr._internal.graphmodule and the public facade, including all enums, graph/query classes, andDirNamespace. Signatures match the PyO3 definitions; dataset dictionaries, scalar parameters, execution options, and statistics returns receive concrete types.A strict consumer exercises the public surface, including expected type errors. Runtime tests compare exported classes, members, argument kinds, and defaults against the installed stubs. The wheel smoke check now requires the marker and both stub files. The handwritten API reference and Python development guide explain usage and local validation.
pyarrow-stubsis a development dependency only.Validation
Head
6175122bd24cc8fe95ddd4cf82d7492975ea6e7d; frozen parent54e02307a48e467a98d9da2183f5adcb767e7c99. Focused checks and regression details record commands, results, documentation and compatibility. The release receipt pins wheel/archive identity and 3 installed tests.Both complete workloads pass unchanged goldens in memory and lazy modes. Retained first-pass geometric mean speedups are below (greater than one is faster). Per-query results and paired investigations remain in the audit archive.
Measurements use the same Apple M4 Max (16 cores, 128 GiB), macOS 26.6.2 arm64 and Python 3.13.17, with Q30 revision
6260689and IC revisionc185123. Reproduction instructions pin settings, data checksums, locks and commands. The frozen main baseline is code-identical to current main90114f3; the equivalence check also verifies clean prospective main-target merges.Individual review gates pass under the recorded repeat/controlled-investigation rules. Initial failed measurements remain intact in the audit record.
User impact
Ships py.typed and stubs matching top-level/compiled graph exports, DirNamespace, enums, methods and properties. Wheel/sdist content, strict consumer typing and runtime parity are checked. Handwritten API documentation remains.
Review ledger · Current contribution guide
Audit archive: 47,675,190 bytes; SHA-256
b3486fb30a34639c830b5d49353b3838f96369f95df959ac35f85511f7f8b2de. The small current-main supplement preserves the documentation update. Original absolute paths in receipts map to included records through the archive index.Submitted by David Hughes (@stugorf), with AI Collaboration.