Module pystub 

pystub — the three Python package stubs under crates/atune_py/python/atune, composed from the live module and an explicit annotation table (D27, docs/design/11-documentation-plan.md §8).

Why a generator and not a hand-written stub

The Python surface is 8 classes, 3 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 (§1.3.4). 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 21 #[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 (§7’s Needs column).

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.

Three 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, and schedulers.pyi. The same live-module introspection and table coverage pass feeds all three files. Keeping the files as separate GeneratedDoc entries makes every path visible to the generate-all registry and lets drift fail closed per file.

Structs

LiveCoverage 🔒

Live names collected before checking the annotation table’s coverage.

Member 🔒

One member of a module or class.

ModuleSurface 🔒

One module’s public surface, as the live interpreter reports it.

Param 🔒

One parameter of a callable.

PythonStub

One generated Python package stub.

SymbolTypes 🔒

One callable’s (or property’s) annotations.

TypeTable 🔒

The annotations pyo3 cannot supply, read from TABLE.

Enums

MemberKind 🔒

The shapes a member can take.

StubModule 🔒

Which package module a generated stub describes.

Constants

GENERATOR 🔒

The generator’s name, for error messages.

MODULES 🔒

The three modules the stubs cover, parent first.

SKIPPED_DUNDERS 🔒

Attributes every #[pyclass] carries that the stub does not restate.

TABLE 🔒

The annotation table, relative to the repository root.

Functions

annotation_source 🔒

Collects the annotation text owned by one live module.

banner 🔒

The banner every generated stub opens with.

callable_block 🔒

Renders one function or method.

callable_kind 🔒

Reads a callable’s __text_signature__.

canonicalize_aliases 🔒

Replaces duplicate public names for one live Python class with aliases.

class_block 🔒

Renders one class.

class_kind 🔒

Reads a class’s bases and members.

code_span_labels 🔒

Puts the label of [label](rust::path) into a code span.

docstring 🔒

Reads __doc__, treating an empty string as absent.

docstring_block 🔒

Renders a docstring at indent columns.

enum_block 🔒

Renders one enum.Enum subclass and its members.

enum_kind 🔒

Reads an enum class’s mixin type and its members.

filtered_import 🔒

Filters one candidate from-import line to names used by a module.

identifier_used 🔒

Whether identifier appears as a whole identifier in text.

introspect 🔒

Imports the live module and reads the three surfaces out of it.

is_descriptor 🔒

Whether value is one of the descriptor types pyo3 produces for a getter.

is_enum_class 🔒

Whether value is a subclass of enum.Enum.

literal 🔒

Accepts a default only if it is a plain Python literal.

missing 🔒

The error a symbol with no table entry fails with.

module_imports 🔒

Renders only the candidate imports used by one module.

module_prelude 🔒

Selects type aliases and variables referenced by one module’s annotations.

module_surface 🔒

Reads one module’s surface.

parse_signature 🔒

Parses ($self, name, low, *, log=False) into parameters.

property_block 🔒

Renders one @property.

render_module 🔒

Renders one of the three generated package stubs.

split_top_level 🔒

Splits on commas that are not inside a bracket or a quote.

string_array 🔒

Reads an array of TOML strings from item[key].

string_value 🔒

Reads a TOML string, or fails naming context.

unclassifiable 🔒

Wraps a message as this generator’s fail-closed error.