Qiskit / qiskit-fermions / 29510949104

98%

push

github

Proper stub typing (#186)

* fix: make the package properly typed by committing _lib-rooted stubs

The package shipped a `py.typed` marker but was not actually typed for installed
consumers. Two independent problems:

1. Shadowing. `pyo3-stub-gen` was rooted at the public package name and its
   `#[gen_stub_*(module = ...)]` annotations used the logical public paths, so it
   emitted aggregator `__init__.pyi` files next to the hand-written `__init__.py`
   of every public sub-package. Type checkers prefer `.pyi` over `.py`, so those
   generated stubs shadowed the real re-exports -- `from qiskit_fermions.operators
   import FermionOperator`, and the whole pure-Python API, became invisible to
   mypy and pyright. In-tree `mypy python/qiskit_fermions/` never caught it; only
   installed wheels were affected.
2. No stubs in the wheel. Stubs were gitignored and generated only by a separate
   `make pystubs` step, so a plain `pip wheel` / `python -m build` shipped none.

The fix follows pyo3-stub-gen's intended usage (jij-inc/pyo3-stub-gen#416, #417):
the stub `module` must be the *physical* runtime path, not the logical one. Stub
generation is rooted at `qiskit_fermions._lib` and every `#[gen_stub_*(module =
...)]` points at the real `qiskit_fermions._lib.*` module (including the nested
`operators_library`, `operators_terms`, `mappers_library`, `majorana_fermion`
names). Generated stubs now land under `python/qiskit_fermions/_lib/**`, which has
no hand-written `__init__.py`, so nothing is shadowed; the public API is typed by
the hand-written `__init__.py` re-exports that import from `_lib`.
`#[pyclass(module = ...)]` keeps the public path (so runtime `__module__`, `repr`,
and error messages stay user-facing) while a decoupled `#[gen_stub(module = ...)]`
gives the stub its physical path.

The `_lib` stubs are now committed -- the ecosystem norm (pydantic-core,
cryptography, tokenizers all commit their native stubs) -- and:
- packaged into the wheel via `_l... (continued)

50 of 51 new or added lines in 13 files covered. (98.04%)

8023 of 8209 relevant lines covered (97.73%)

155.44 hits per line