pypi / sphinx-autodoc-typehints
sphinx-autodoc-typehints
What changed in sphinx-autodoc-typehints 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-22.
2 breaking5 new APIs and options1 performance18 behavior and defaults53 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initsphinx-autodoc-typehints 379 changes
Breaking changes 2
Invalid formatter and defaults settings report configuration errors; an empty formatter result hides the type and removes fields it empties.
The setting defaults to
autodoc_typehints_format = "fully-qualified"; an explicit value still takes precedence.
New APIs and options 5
Adds a default style that marks parameters callers may omit without printing their default values.
Adds an option to render legacy typing aliases with current Python spelling.
Configure selected Annotated metadata to appear in rendered types.
A
@typing.overridemethod gains anOverridesfield linking to the base-class member it replaces.A property gains a
Setter acceptsfield when its setter annotation differs from the getter return type.
Performance 1
The extension avoids importing every module in an intersphinx inventory and stops unwrapping at Sphinx mocks, reducing unnecessary work.
Behavior and default changes 18
Callbacks can read descriptions from Annotated metadata classes other than Doc.
Read Doc descriptions from annotated-doc as well as typing_extensions.
Keep single-word prose in hand-written :Returns: fields.
Choose a guard's branch using the build platform and false constants, and skip guards with other conditions that cannot be determined without running code.
When typehints_formatter_pass_context is enabled, the formatter receives whether a type appears in a parameter, return, attribute or base.
Added parameters appear in signature order among documented parameters, and incremental builds reread sources when the setting changes.
Dataclass and attrs default factories render as calls in signatures and fields; lambdas, partials and nested functions retain
<factory>.Types inherited from generic bases substitute the type arguments bound by the subclass, including parameters, returns, attributes, properties, overloads and TypedDict keys.
ivar,cvarandvarfields obtain types from class-body and base-class annotations, withClassVarandFinalqualifiers removed.Napoleon attribute entries can be typed from
__init__annotations unless disabled; existing:type:documentation takes precedence.Function, class and type-alias signatures show PEP 695 parameters, including bounds, constraints and defaults; declared parameters render by name.
Documentation follows custom
__signature__values and preserves explicit directive or docstring signatures when their parameters differ from the object.Documented keyword arguments from
Unpack[TypedDict]are typed; optional keys show asNotRequired[...], and PEP 728 classes gain anExtra itemsfield.Defaults appear on their own parameter when docstrings already contain type lines, and are placed after the final plain description paragraph.
With this setting false, return types are merged into
:returns:descriptions, including existing:rtype:fields and multiline descriptions.Types retained in signatures use the same rendering as fields, including aliases, guarded imports, fully qualified names and the formatter; overloads show one typed signature per variant.
Unpacked TypeVarTuples and tuples render with the PEP 646 star syntax.
Subscripted type aliases are now supported.
Fixes and other changes 53
Overridden methods link to a documented public owner when their defining class is private and absent from the intersphinx inventory.
The setting is now honored when reading types from a function's # type: comment.
Loading the extension no longer changes html_static_path because the value stylesheet is registered through Sphinx's static-directory API.
Recognize numpydoc return types containing spaces.
Method signatures of classes defined inside functions are processed when the module exports the class under a name autodoc can import.
An unchanged incremental build no longer reports html_static_path as changed after the extension adds its stylesheet.
Inherited special methods of a generic subclass are documented without raising an error about subscripting an already-subscripted typing.Generic.
The setter's type is shown instead of failing the build when Annotated metadata raises during comparison with the getter type.
Descriptions in hand-written :Returns: fields are kept rather than interpreted as numpydoc return types.
Imports under if TYPE_CHECKING and False are skipped instead of resolving types the branch never defines.
Incremental builds reread documents when the formatter changes, updating rendered types without requiring sphinx-build -E.
With
both, constructor parameters are listed once, including those added byalways_document_param_typesorDoc().The extension loads
sphinx.ext.autodocbefore connecting to its events, avoidingUnknown event namewhen autodoc is listed later or omitted.Subscripted and union types from mocked modules render and link correctly; mocked constructors, setters and overloads no longer abort unwrapping.
Documented aliases link to their own entries and resolve according to Python name lookup, including entries read later in the build.
Return types in description mode are placed after the appropriate parameter field list, rather than before later docstring structures.
Unparseable string annotations render as written with a
forward_referencewarning instead of aborting the build; other annotations remain resolvable when one fails.Generator return annotations provide a
Yieldssection when the docstring hasReturns; yielded types are shown without replacing types already stated in the docstring.Overload entries link their types, preserve parameter markers, defaults and variadic stars, and omit
selfandclswhere appropriate.ParamSpec arguments,
P.argsandP.kwargsrender in their appropriate forms and retain links to the declared parameter specification.Sentinels render by name as
py:datareferences rather than links to a nonexistentsentinelclass.Signatures for cached functions and unbound ParamSpecs are handled correctly, including Python 3.14 annotation and generator cases.
Annotation evaluation failures no longer crash builds or drop objects, and inferred stub or type-comment annotations do not mutate
__annotations__.Stub imports, version-guarded definitions, overloads and re-exports are resolved; pages using a stub are reread when it changes.
Guarded imports and definitions resolve across supported guard forms and module relationships without replacing runtime bindings or changing module members.
Defaults are rendered consistently across docstring parameter forms, with stable representations and placement that avoids trailing lists, directives and literal blocks.
When overload documentation is disabled, the
:no-overloads:marker is removed from output.Setting this option to false hides
Annotated[None, ...]as a return type.The setting no longer causes an unpickleable-configuration warning, and documents are reread only when its function source changes.
The formatter applies consistently to signature types and data, attribute and property headers; Sphinx config is passed when formatting signatures.
The decorator's message appears as a deprecation notice below the summary.
Annotating with the TypeVar or ParamSpec class itself no longer prints its member descriptors.
A bare Literal renders without empty brackets.
Type hints are no longer printed in signatures of NamedTuple classes and classes that only define __new__, matching other classes.
Supported typing names, including ParamSpecArgs and ParamSpecKwargs on Python 3.12, link to the Python docs instead of rendering as unresolved text.
Fixes the forward-reference warning when documenting NumPy's clip by resolving generic parameters declared in stub signatures.
Resolves field types of a NamedTuple imported under TYPE_CHECKING when Sphinx documents the class before any function from its module, removing a forward-reference warning.
Dependencies imported only in TYPE_CHECKING blocks can be mocked when not installed, allowing their types to render as cross-references without a Failed guarded type import warning.
Undocumented type aliases are expanded, while documented aliases keep their names, regardless of documentation order.
Fixes a NameError crash when a PEP 695 alias defined in another module uses names imported under TYPE_CHECKING.
Annotations carrying an intersphinx external+ role no longer trigger an unknown role name warning.
A failing TYPE_CHECKING statement no longer causes comprehension and loop targets to shadow builtins such as type in rendered annotations.
Fixes an ExtensionError about _annotation_globals that occurred when documenting one object started documenting another.
Docstrings referencing another project through an intersphinx external+ role no longer produce an unknown role name warning.
Expressions rejected by the interpreter inside a TYPE_CHECKING block no longer emit guarded type import or forward-reference warnings; their names render as forward references.
Processes each top-level statement separately, preventing an unimportable name from leaving later names unbound or a missing stub from causing cascading forward-reference warnings.
Fixes a TypeError crash when a module imports TypeAliasType whose __type_params__ is not a tuple.
Python 3.15 is now supported.
Resolves self-references in recursive PEP 695 aliases defined in another module, fixing a nitpick warning.
Renders self-referential PEP 695 type aliases instead of aborting with a recursion-depth error.
The one-line summary of overloaded functions appears above the overload list.
On Python 3.13+, types module members use the py:class role to match the Python documentation.
Types of C extension properties and attributes are taken from their .pyi stub.