Public API reference

All names exported from the top-level stubpy package form the stable public interface. Everything else is internal and may change between minor versions.

Core entry points

stubpy.generator.generate_stub	Generate a .pyi stub file for the Python source at filepath.
stubpy.generator.generate_package	Generate .pyi stubs for every .py file in package_dir.
stubpy.generator.PackageResult	Outcome of a generate_package() run.

See stubpy.generator for full documentation.

Configuration

stubpy.context.StubConfig	Per-run configuration options for stub generation.
stubpy.context.StubContext	Mutable state container scoped to one stub-generation run.
stubpy.context.ExecutionMode	Controls whether the target module is executed during stub generation.
stubpy.context.AliasEntry	A pairing of a live annotation object with its stub alias string.
stubpy.config.load_config	Load a StubConfig from the nearest config file.
stubpy.config.find_config_file	Walk upward from search_dir looking for a stubpy config file.

See stubpy.context and stubpy.config for full documentation.

Diagnostics

stubpy.diagnostics.DiagnosticCollector	Mutable accumulator for Diagnostic records produced during one stub-generation run.
stubpy.diagnostics.Diagnostic	An immutable record of a single issue detected during stub generation.
stubpy.diagnostics.DiagnosticLevel	Severity of a single diagnostic message.
stubpy.diagnostics.DiagnosticStage	Pipeline stage that produced a diagnostic.

See stubpy.diagnostics for full documentation.

Stub emitters

stubpy.emitter.generate_class_stub	Generate the full .pyi block for cls.
stubpy.emitter.generate_function_stub	Generate the .pyi stub line(s) for a module-level function.
stubpy.emitter.generate_variable_stub	Generate a name: Type line for a module-level variable.
stubpy.emitter.generate_alias_stub	Re-emit a TypeVar, TypeAlias, NewType, ParamSpec, or TypeVarTuple declaration.
stubpy.emitter.generate_overload_group_stub	Emit one @overload-decorated stub per variant in group.

See stubpy.emitter for full documentation.

Annotation handling

stubpy.annotations.annotation_to_str	Convert any annotation object to a valid .pyi string.
stubpy.annotations.format_param	Format a single inspect.Parameter as a stub-ready string.
stubpy.annotations.register_annotation_handler	Register a custom annotation-to-string handler.

See stubpy.annotations for full documentation.

Docstring type inference

stubpy.docstring.parse_docstring_types	Parse type information from a structured docstring.
stubpy.docstring.DocstringTypes	Result of parsing one docstring for type information.

See stubpy.docstring for full documentation.

Incremental stub merge

stubpy.stub_merge.merge_stubs	Merge generated stub content into existing .pyi content.
stubpy.stub_merge.wrap_generated	Wrap content between canonical begin/end markers.
stubpy.stub_merge.read_and_merge	Read output_path (if it exists) and merge generated into it.

See stubpy.stub_merge for full documentation.