Module pystub 

pystub — the four Python package stubs under crates/atune_py/python/atune, composed from the live module and an explicit annotation table (D27).

Why a generator and not a hand-written stub

The Python surface includes classes, exception types and several dozen callables. A hand-written stub rots; a fully automatic one is impossible, because pyo3 knows the names of a binding’s parameters but not their types — experimental-inspect marks a #[pymodule]-registered module Incomplete and hands back def __getattr__(name: str) -> Incomplete. So this generator composes two sources:

• the live module, imported through the embedded interpreter atune_python::init_python already gives the bindings’ own tests — the symbol set (each module’s __all__), the parameter names and defaults pyo3 derives into __text_signature__ from the #[pyo3(signature = …)] attributes, and the docstrings pyo3 sets from ///;
• crates/atune_dev/pystub_types.toml, for the annotations pyo3 cannot supply.

No wheel is built: append_to_inittab! makes import atune resolve in-process, which is what keeps this generator inside the fast rust.yml gate.

Fail-closed, in both directions

A symbol in the module with no table entry is an error naming the symbol and the file to edit — never an Any. A table entry that matches no symbol is also an error, so a removed binding cannot leave a stale annotation behind to be silently reused by the next binding of the same name.

Four owned files

Maturin’s mixed-package layout copies the Python source tree into the wheel, so each live module has its own generated sibling stub: __init__.pyi, samplers.pyi, schedulers.pyi, and pb2.pyi. The live-module introspection and table coverage pass feeds all four files. Keeping the files as separate GeneratedDoc entries makes every path visible to the generate-all registry and lets drift fail closed per file.

The pure-Python Optuna adapter ships inline annotations. Its source is loaded into the embedded interpreter for export/parameter coverage and API links, without producing a stub or requiring Optuna during generation.

Re-exports

pub use python_stub::PythonStub;

Modules

introspection 🔒

Introspection of the live embedded Python package.

python_stub 🔒

render 🔒

Rendering: one .pyi stub, composed from the live module surface and the annotation table.

table 🔒

Annotation table parsing and live-surface coverage checks.