← 输入框|github.com|刷新
Skip to content

Update PyO3 to 0.30 and enable type stub generation - #410

Merged
g-bauer merged 1 commit into
mainfrom
pyo3_0.30
Nov 17, 2026
Merged

g-bauer merged 1 commit into
mainfrom
pyo3_0.30

Conversation

@g-bauer

@g-bauer g-bauer commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Updates PyO3 to 0.30 and uses its experimental-inspect feature to generate type stubs (.pyi) for the feos Python package automatically.

Dependencies

  • pyo3, numpy and pythonize 0.30; quantity and num-dual 0.16 (all released versions, no patches).
  • New py-feos feature experimental-inspect (forwards to pyo3 and quantity) that embeds the introspection data used for stub generation.

API changes

  • Verbosity::None is renamed to Verbosity::Silent in feos-core, and Verbosity.None to Verbosity.Silent in Python: None is not a valid attribute name in Python (it produced an invalid stub) and is easily confused with Option::None in Rust. This is a breaking change for Rust users as well.
  • State.critical_point_binary raises a ValueError instead of a RuntimeError for wrong units, like all other functions that accept a temperature or a pressure.
  • ThreePhaseEquilibrium is exported, so PhaseEquilibrium.heteroazeotrope is typed.
  • EquationOfState.parameters and Dataset.evaluate return numpy arrays of dynamic dimension instead of untyped objects (a cast, no copy). They are typed in Rust, but appear as Incomplete in the stubs until numpy provides type hints.

Internal changes

  • The Python module is declared as an inline #[pymodule] mod feos (required for introspection). The rayon thread pool setup moves to an argument-less #[pymodule_init].

  • The hand-written text_signatures are removed; they were partly outdated and disagreed with the generated signatures in 60 methods according to mypy's stubtest.

  • Arguments that accept several types are now extracted into Rust types whose FromPyObject implementation carries the type hint, instead of taking Bound<PyAny> and parsing it in the function body. Like the pyclasses, they are named after the corresponding feos type with a Py prefix; they are internal, only the union of the accepted types appears in the stubs:

    • PyComposition (renamed from Compositions, + PyStateComposition for the partial densities accepted by State)
    • PyTemperatureOrPressure; arguments that depend on the specification (tp_init, min_tp, ...) are converted with .temperature() / .pressure()
    • PyDensityInitialization (Literal['vapor', 'liquid'] | SIObject)
    • PyParametersOrGcParameters (in parameter, so other models can reuse it)

    Error messages are unchanged. Arguments that are parsed in a single place (AD parameter names/values, Dataset.evaluate's eos, SMILES identifiers) keep Bound<PyAny> and get string annotations in their signature.

Generating the stubs

cargo install pyo3-introspection --version 0.30.1
cargo build -p py_feos --features "wheel experimental-inspect"
pyo3-introspection target/debug/libfeos.dylib feos <output dir>

Notes

  • The released numpy 0.30 has no experimental-inspect support, so numpy arrays appear as Incomplete (i.e. Any) in the stubs for now.
  • String annotations in signature are copied verbatim into the stub, without imports. They can only use builtins and names defined in the stub (e.g. list[str] instead of Sequence[str]).

Testing

  • cargo clippy -p py_feos without warnings for wheel, emscripten_wheel, pcsaft, epcsaft, gc_pcsaft, ad and dft, each with and without experimental-inspect.
  • cargo test --workspace --all-features (excluding py_feos): all tests pass.
  • Smoke tests of the release wheel (states with all composition variants, VLE with temperature and pressure specifications incl. tp_init, critical points, phase diagrams, DFT interfaces, AD derivatives, datasets, GC parameters from SMILES), including the error messages for invalid inputs.
  • Generated stubs: pyright and mypy's stubtest (--ignore-missing-stub) report no errors.

🤖 Generated with Claude Code

@g-bauer
g-bauer force-pushed the pyo3_0.30 branch 2 times, most recently from dd1b7f5 to 92ada06 Compare November 17, 2026 15:35
- Bump pyo3, numpy and pythonize to 0.30, and quantity and num-dual to
  0.16, which support PyO3 0.30.
- Add the `experimental-inspect` feature (forwarding to pyo3 and
  quantity) to embed introspection data for stub generation.
- Declare the Python module as an inline `#[pymodule] mod feos`, which
  is required for introspection. The rayon thread pool setup moves to an
  argument-less `#[pymodule_init]`, so the module is not marked
  incomplete and `__all__` is emitted.
- Rename `Verbosity::None` to `Verbosity::Silent` in feos-core (and
  `Verbosity.None` to `Verbosity.Silent` in Python): `None` is not a
  valid attribute name in Python and produced an invalid stub, and in
  Rust it is easily confused with `Option::None`.
- Remove the hand-written `text_signature`s: they were partly outdated
  (missing `$self`, defaults) and disagreed with the generated stubs in
  60 methods according to mypy's stubtest.

Arguments that accept several types: instead of taking `Bound<PyAny>`
and parsing it inside the function, the arguments are extracted into
Rust types whose `FromPyObject` implementation carries the union of the
accepted types as `INPUT_TYPE`. Like the pyclasses, they are named after
the corresponding feos type with a `Py` prefix. They are internal: only
the union of the accepted types appears in the stubs.
- `PyComposition` (renamed from `Compositions`): moles, total moles,
  molefracs, or a single molefrac; plus `PyStateComposition` for the
  partial densities accepted by `State`.
- `PyTemperatureOrPressure` for phase equilibrium specifications.
  Arguments that depend on the specification (`tp_init`, `min_tp`, ...)
  are converted with `PyTemperatureOrPressure::temperature/pressure`.
  `State.critical_point_binary` now raises a `ValueError` (instead of a
  `RuntimeError`) for wrong units, like all other functions.
- `PyDensityInitialization` (`Literal['vapor', 'liquid'] | SIObject`).
- `PyParametersOrGcParameters` for `EquationOfState.pcsaft`.
Error messages are unchanged. Arguments that are only parsed in one place
(AD parameter names and values, datasets' `eos`, SMILES identifiers) keep
`Bound<PyAny>` and are annotated with strings in their signatures.

Returns: `EquationOfState.parameters` and `Dataset.evaluate` return
numpy arrays of dynamic dimension (`PyArrayDyn`) instead of untyped
objects (the conversion is a cast, no copy). They appear as `Incomplete`
in the stubs until numpy provides type hints. The `grid` of DFT profiles
is `SIObject | list[SIObject]` and `ThreePhaseEquilibrium` is exported,
so `heteroazeotrope` is typed.

numpy 0.30 does not provide type hints, so numpy arrays appear as
`Incomplete` (i.e. `Any`) in the stubs. The 21 `Any` are
pythonize/JSON outputs, user-defined Python models and the AD parameter
values. pyright and mypy's stubtest report no errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@g-bauer
g-bauer merged commit b269841 into main Nov 17, 2026
18 checks passed
@g-bauer
g-bauer deleted the pyo3_0.30 branch November 17, 2026 16:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants