StubConfig

class StubConfig(execution_mode: ExecutionMode = ExecutionMode.RUNTIME, include_private: bool = False, respect_all: bool = True, verbose: bool = False, strict: bool = False, union_style: str = 'modern', alias_style: str = 'compatible', include_docstrings: bool = False, exclude: list[str] = <factory>, output_dir: str | None = None, infer_types_from_docstrings: bool = False, incremental_update: bool = False)[source]

Bases: object

Per-run configuration options for stub generation.

All fields have sensible defaults so callers need not supply any arguments for standard usage.

Parameters:

  • execution_mode (ExecutionMode) – Defaults to RUNTIME.

  • include_private (bool) – When True, symbols whose names start with _ are included. Defaults to False.

  • respect_all (bool) – When True and __all__ is present, only names in __all__ are stubbed. Defaults to True.

  • verbose (bool) – When True, INFO-level diagnostics are printed. Defaults to False.

  • strict (bool) – When True, any ERROR diagnostic causes a non-zero exit. Defaults to False.

  • union_style (str) – Output style for union annotations. "modern" emits PEP 604 X | Y syntax (e.g. str | None); "legacy" emits Optional[X] / Union[X, Y]. Defaults to "modern".

  • include_docstrings (bool) – When True, copy the docstring from each function, method, and class into the generated stub as a literal string body instead of .... Useful when a stub doubles as quick-reference documentation without requiring the original source. Defaults to False.

  • alias_style (str) –

    Output format for type alias declarations.

    • "compatible" (default) — always emit Name: TypeAlias = <rhs> using the TypeAlias annotation from typing. Works on all Python 3.10+ versions.

    • "pep695" — emit the Python 3.12+ type Name = <rhs> soft-keyword form (PEP 695). Only use this when your project targets Python 3.12+.

    • "auto" — use pep695 when running on Python 3.12+, otherwise fall back to compatible.

  • exclude (list of str) – Glob patterns (relative to the package root) for files to skip during package processing. Only used by generate_package(). Defaults to [].

  • output_dir (str or None) – Default output directory for package processing. None means stubs are written alongside the source files. Defaults to None.

  • infer_types_from_docstrings (bool) – When True, attempt to infer parameter and return types from NumPy, Google, or Sphinx-style docstrings for functions and methods that lack explicit annotations. Inferred types are emitted as inline # type: comments rather than live annotations, making their origin clearly visible. Defaults to False.

  • incremental_update (bool) – When True, wrap the generated stub in # stubpy: auto-generated begin/end markers and merge it into any existing .pyi file, preserving content outside the markers. When False (default) the .pyi is overwritten completely.

execution_mode: ExecutionMode = 'runtime'
include_private: bool = False
respect_all: bool = True
verbose: bool = False
strict: bool = False
union_style: str = 'modern'
alias_style: str = 'compatible'
include_docstrings: bool = False
exclude: list[str]
output_dir: str | None = None
infer_types_from_docstrings: bool = False
incremental_update: bool = False
__init__(execution_mode: ExecutionMode = ExecutionMode.RUNTIME, include_private: bool = False, respect_all: bool = True, verbose: bool = False, strict: bool = False, union_style: str = 'modern', alias_style: str = 'compatible', include_docstrings: bool = False, exclude: list[str] = <factory>, output_dir: str | None = None, infer_types_from_docstrings: bool = False, incremental_update: bool = False) → None

See also

Public API reference — overview of all public names.