stubpy.config¶

Configuration file discovery and parsing.

stubpy looks for configuration in two places, in order:

A stubpy.toml file in the project root (or any parent directory).
A [tool.stubpy] section inside pyproject.toml.

The first file found wins. If neither exists the default StubConfig is returned unchanged.

Supported keys¶

[tool.stubpy]
include_private = false
execution_mode  = "runtime"   # "runtime" | "ast_only" | "auto"
output_dir      = "stubs"     # output directory for package processing
exclude         = ["**/test_*.py", "setup.py"]
union_style    = "modern"    # "modern" (PEP 604) | "legacy" (Optional[])

All keys are optional. Unknown keys are silently ignored so that future versions can add new keys without breaking older configs.

Examples

>>> from stubpy.config import load_config
>>> cfg = load_config(".")
>>> cfg.union_style
'modern'

find_config_file(search_dir: str | Path) → Path | None[source]¶

Walk upward from search_dir looking for a stubpy config file.

Checks each directory for (in order):

stubpy.toml
pyproject.toml (only if it contains [tool.stubpy])

Returns the first matching Path, or None when no config is found before the filesystem root.

Parameters:: search_dir (str or Path) – Directory to start searching from (typically the package root or the source file’s parent).
Returns:: Path or None

Examples

>>> from stubpy.config import find_config_file
>>> result = find_config_file(".")   # returns None if no config present

load_config(search_dir: str | Path) → StubConfig[source]¶

Load a StubConfig from the nearest config file.

Searches upward from search_dir for stubpy.toml or a [tool.stubpy] section in pyproject.toml. Returns a default StubConfig when no config file is found.

Parameters:: search_dir (str or Path) – Directory to begin the upward search (typically the package being stubbed, or the current working directory).
Returns:: StubConfig – Fully populated config, falling back to defaults for any key not present in the file.

Examples

>>> from stubpy.config import load_config
>>> cfg = load_config(".")
>>> cfg.union_style in ("modern", "legacy")
True

Configuration file format

stubpy reads configuration from the first file found by walking upward from the target directory:

stubpy.toml — the whole file is the config section.
pyproject.toml — only the [tool.stubpy] section is read.

stubpy.toml example:

include_private = false
execution_mode  = "runtime"    # "runtime" | "ast_only" | "auto"
union_style    = "modern"     # "modern" (X | None) | "legacy" (Optional[X])
output_dir      = "stubs"
exclude         = ["**/test_*.py", "setup.py"]

pyproject.toml example:

[tool.stubpy]
include_private = false
union_style    = "legacy"
exclude         = ["docs/conf.py"]

TOML parsing

On Python 3.11+ the stdlib tomllib is used. On Python 3.10 the tomli backport is used if installed; otherwise a minimal built-in parser handles the simple key/value syntax that stubpy needs. Unknown keys are silently ignored so that future versions can add new options without breaking existing config files.

Supported keys

Key	Default	Description
`include_private`	`false`	Include symbols whose names start with `_`.
`respect_all`	`true`	When `__all__` is present, only stub names listed in it.
`execution_mode`	`"runtime"`	`"runtime"` / `"ast_only"` / `"auto"`.
`union_style`	`"modern"`	`"modern"` emits `X \| None`; `"legacy"` emits `Optional[X]`.
`alias_style`	`"compatible"`	`"compatible"` emits `Name: TypeAlias = <rhs>` (Python 3.10+); `"pep695"` emits `type Name = <rhs>` (Python 3.12+); `"auto"` selects `pep695` on Python 3.12+, otherwise `compatible`.
`output_dir`	`null`	Output root for `generate_package()`.
`exclude`	`[]`	Glob patterns (relative) for files to skip in package processing.
`verbose`	`false`	Print all diagnostics to `stderr`.
`strict`	`false`	Exit with code 1 if any ERROR diagnostic is recorded.

File-level ignore directive

To exclude a specific source file from stub generation without adding it to exclude patterns, place # stubpy: ignore as a comment at the very top of the file (before any code):

# This file is auto-generated — do not stub.
# stubpy: ignore
...

stubpy writes a minimal stub and records an INFO diagnostic.