NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #2732 most downloaded on PyPI
Render Python type hints in Sphinx autodoc documentation
Latest stable
3.17.5
Last release 18 days ago
04 Nov 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
11 years old
147 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
🐍 PyPI release 📜 Full Changelog
Link each name in the type after an attribute, data or property name with the role its docstring field uses, so a type alias an inventory lists as dat
<a name="release-3-17-4-fixed"></a>
type alias an inventory lists as data, such as numpy.typing.NDArray, resolves through intersphinx (#1105) by @gaborbernat.Your coding agent can read these notes before it upgrades. Set up the MCP server →
Link each name in the type after an attribute, data or property name with the role its docstring field uses, so a type alias an inventory lists as data, such as numpy.typing.NDArray, resolves through intersphinx (1105) by gaborbernat.
Publish categorized GitHub Release notes with PyPI and version-comparison links (#1094) by @gaborbernat.
<a name="release-3-17-3-packaging"></a>
Publish categorized GitHub Release notes with PyPI and version-comparison links (1094) by gaborbernat.
Link an overridden method to a documented public owner when its defining class is private and absent from the intersphinx inventory. #1090 by @gaborbe
<a name="release-3-17-2-fixed"></a>
Link an overridden method to a documented public owner when its defining class is private and absent from the intersphinx inventory. 1090 - by gaborbernat.
Describe the package as rendering Python type hints in Sphinx autodoc documentation. #1089 by @gaborbernat.
<a name="release-3-17-1-packaging"></a>
Describe the package as rendering Python type hints in Sphinx autodoc documentation. 1089 - by gaborbernat.
Add typehints_modernize_annotations to render legacy typing aliases with current Python spelling. #1085 by @gaborbernat.
<a name="release-3-17-0-added"></a>
typehints_modernize_annotations to render legacy typing aliases with current Python spelling. #1085 by @gaborbernat."optional" default style that marks parameters callers may omit without printing their default values. #1086 by @gaborbernat.Annotated metadata classes other than Doc. #1088 by @gaborbernat.<a name="release-3-17-0-documentation"></a>
autodoc_preserve_defaults applies to default values in parameter descriptions. #1087 by @gaborbernat.Add typehints_modernize_annotations to render legacy typing aliases with current Python spelling. 1085 - by gaborbernat.
Add an "optional" default style that marks parameters callers may omit without printing their default values. 1086 - by gaborbernat.
Allow a callback to read descriptions from Annotated metadata classes other than Doc. 1088 - by gaborbernat.
Explain how Sphinx's autodoc_preserve_defaults applies to default values in parameter descriptions. 1087 - by gaborbernat.
Read Doc descriptions from annotated-doc as well as typing_extensions. #1083 by @gaborbernat.
<a name="release-3-16-0-added"></a>
Doc descriptions from annotated-doc as well as typing_extensions. #1083 by @gaborbernat.<a name="release-3-16-0-fixed"></a>
html_static_path. #1079 by @gaborbernat.autodoc_use_type_comments = False when reading types from a function's # type: comment. #1080 by @gaborbernat.TYPE_CHECKING guard's branch; skip guards whose other conditions cannot be determined without running code. #1081 by @gaborbernat.:Returns: fields, and recognize numpydoc return types containing spaces. #1082 by @gaborbernat.<a name="release-3-16-0-documentation"></a>
NamedTuple references in both modes. #1084 by @gaborbernat.Read Doc descriptions from annotated-doc as well as typing_extensions. 1083 - by gaborbernat.
Register the value stylesheet through Sphinx's static-directory API, so loading the extension does not change html_static_path. 1079 - by gaborbernat.
Honor autodoc_use_type_comments = False when reading types from a function's # type: comment. 1080 - by gaborbernat.
Use the build platform and false constants when choosing a TYPE_CHECKING guard's branch; skip guards whose other conditions cannot be determined without running code. 1081 - by gaborbernat.
Keep single-word prose in hand-written :Returns: fields, and recognize numpydoc return types containing spaces. 1082 - by gaborbernat.
Document support for both Sphinx autodoc implementations and cover re-exported types and NamedTuple references in both modes. 1084 - by gaborbernat.
Allow projects to show selected Annotated metadata in rendered types with typehints_annotated_metadata. #1071 by @gaborbernat.
<a name="release-3-15-0-added"></a>
Annotated metadata in rendered types with typehints_annotated_metadata. #1071 by @gaborbernat.typehints_formatter receive whether a type appears in a parameter, return, attribute or base when typehints_formatter_pass_context is enabled. #1073 by @gaborbernat.<a name="release-3-15-0-fixed"></a>
typehints_formatter changes in an incremental build, so their rendered types update without sphinx-build -E. #1069 by @gaborbernat.html_static_path as changed after the extension adds its stylesheet. #1070 by @gaborbernat.Cannot subscript already-subscripted typing.Generic. #1074 #1075 by @gaborbernat.Annotated metadata raises during comparison with the getter type, instead of failing the build. #1076 by @gaborbernat.:Returns: field instead of interpreting it as a numpydoc return type. #1077 by @gaborbernat.if TYPE_CHECKING and False instead of resolving types the branch never defines. #1078 by @gaborbernat.<a name="release-3-15-0-packaging"></a>
Allow projects to show selected Annotated metadata in rendered types with typehints_annotated_metadata. 1071 - by gaborbernat.
Process method signatures of classes defined inside functions when the module exports the class under a name autodoc can import. 1072 - by gaborbernat.
Let typehints_formatter receive whether a type appears in a parameter, return, attribute or base when typehints_formatter_pass_context is enabled. 1073 - by gaborbernat.
Reread documents when typehints_formatter changes in an incremental build, so their rendered types update without sphinx-build -E. 1069 - by gaborbernat.
Stop an unchanged incremental build from reporting html_static_path as changed after the extension adds its stylesheet. 1070 - by gaborbernat.
Document inherited special methods of a generic subclass without raising Cannot subscript already-subscripted typing.Generic. 1074 1075 - by gaborbernat.
Show a property setter's type when Annotated metadata raises during comparison with the getter type, instead of failing the build. 1076 - by gaborbernat.
Keep the description in a hand-written :Returns: field instead of interpreting it as a numpydoc return type. 1077 - by gaborbernat.
Skip imports under if TYPE_CHECKING and False instead of resolving types the branch never defines. 1078 - by gaborbernat.
Advertise Sphinx, autodoc and type hints in the PyPI keywords instead of unrelated virtual environment terms, and add classifiers for documentation, OS independence and the package's type annotations. 1068 - by gaborbernat.
Show the @warnings.deprecated message as a deprecation notice below the summary. #874 by @gaborbernat.
<a name="release-3-14-0-added"></a>
Generic[T] subclasses in their signature, such as bounded[T: int](value) and class Stack[T], with bounds, constraints and defaults. #867 by @gaborbernat.**kwargs: Unpack[TypedDict] documented as keyword arguments. #869 by @gaborbernat.Overrides field linking the base class member a @typing.override method replaces. #871 by @gaborbernat.TypedDict keys a caller may omit as NotRequired[...], and add an Extra items field for PEP 728 extra_items and closed classes. #873 by @gaborbernat.@warnings.deprecated message as a deprecation notice below the summary. #874 by @gaborbernat.T instead of TypeVar(T, bound=int), and P.args and P.kwargs of a declared **P as written. #888 by @gaborbernat.Yields section when its docstring has a Returns section and the third argument of its Generator annotation is not None. #889 by @gaborbernat.typehints_use_signature, render the types kept in the signature the same way as the fields, so stubs, guarded imports, documented aliases, typehints_fixup_module_name, typehints_fully_qualified and typehints_formatter apply to both. #895 by @gaborbernat.sentinel builtin and typing_extensions.Sentinel, by their name as a py:data reference instead of linking a nonexistent sentinel class. #912 by @gaborbernat.:ivar:, :cvar: and :var: fields from class-body and base class annotations, dropping ClassVar and Final qualifiers. #916 by @gaborbernat.Yields entry of a generator, keeping a type the docstring already states. #917 by @gaborbernat.napoleon_use_ivar = False, type .. attribute:: entries from self.x: T annotations in __init__ unless napoleon_attr_annotations = False; a :type: already in the docstring wins. #918 by @gaborbernat.Setter accepts field to a property whose setter annotation differs from the getter's return type. #919 by @gaborbernat.int for T under class IntStore(Store[int]), in what it inherits from a generic base, covering parameter and return fields, overloads, attribute and property headers, :vartype: fields and TypedDict keys. #921, #926, #938 by @gaborbernat.list(), in the signature and fields instead of <factory> or NOTHING; lambdas, partials and nested functions keep <factory>. #922 by @gaborbernat.typehints_fully_qualified, typehints_formatter and typehints_fixup_module_name apply there and the header drops Annotated metadata. #923 by @gaborbernat.typehints_use_signature = True, show one typed signature line per @overload instead of the untyped implementation signature and an Overloads field. #927 by @gaborbernat.TypeVar, ParamSpec or TypeVarTuple in docstring fields by its name, as a PEP 695 type parameter renders, instead of as a TypeVar(B, bound=Sized) call, and P.args as written instead of ParamSpecArgs(P); the name links to the variable's own entry, which shows its bound or constraints, when the docs document it. #1044 by @gaborbernat.'fill' in Literal["fill", 1, None], now take the colors of the project's Pygments style in light and dark mode, the way a code block does. #1046 by @gaborbernat.TypeVarTuple or tuple with the PEP 646 star, *Ts and *tuple[int, ...], instead of Unpack[Ts]; Unpack[TypedDict] for **kwargs keeps its spelling. #1047 by @gaborbernat.typing.ContextManager[None] renders as ContextManager[None] instead of ContextManager[None, bool | None] on Python 3.13 and later; a written typing.Generator[int, None, None] renders as Generator[int]. #1054 by @gaborbernat.Bases: line of a class documented with :show-inheritance: as a docstring field renders a type, so a generic base such as Mapping[str, int] follows typehints_fully_qualified, typehints_fixup_module_name and typehints_formatter, and a PEP 695 base such as Stack[T] keeps its argument where Sphinx left it off. #1058 by @gaborbernat.<a name="release-3-14-0-fixed"></a>
"a positive float", as written with a forward_reference warning instead of aborting the build. #789 by @gaborbernat.sphinx.ext.autodoc before connecting to its events, so listing this extension first or omitting autodoc no longer fails with Unknown event name. #790 by @gaborbernat.QuerySet[...] without django-stubs-ext, also for a function re-exported with a rewritten __module__, instead of showing them all as plain text. #791, #901 by @gaborbernat.__new__ from __new__, as inspect.signature does, and take a __new__-only class's parameter types from __new__ rather than the class body. #792 by @gaborbernat.x, y : int, and single Yields entries. #793 by @gaborbernat.typehints_defaults = "braces-after" defaults on their own parameter when the docstring already has :type: lines or napoleon types. #794 by @gaborbernat.:returns: with typehints_use_rtype = False when the docstring also has :rtype: or its :returns: text starts on the next line. #795 by @gaborbernat.Attributes entries from the class, __init__ and module annotations, linked and rendered like other fields with typehints_fully_qualified, type aliases and typehints_formatter applied, unless napoleon_attr_annotations is False. #796, #966 by @gaborbernat.staticmethod(func) and of name-mangled private static methods. #797 by @gaborbernat.Overloads list, leave out self and cls, and show constructor overloads. #798 by @gaborbernat.always_document_param_types changes, so incremental builds pick up the new setting. #799 by @gaborbernat.:no-overloads: marker from the output when typehints_document_overloads is False. #800 by @gaborbernat.typehints_use_signature_return = True. #801 by @gaborbernat.strip_signature_backslash is on. #802 by @gaborbernat.sphinx.ext.doctest failures on the line the example starts on instead of one line late. #804 by @gaborbernat.Callable parameterized by a ParamSpec or Concatenate as Callable[P, int] instead of Callable[[P], int]. #805 by @gaborbernat.P.args and P.kwargs as ParamSpecArgs(P) and ParamSpecKwargs(P), naming the ParamSpec they belong to. #806 by @gaborbernat.TypeVar or ParamSpec after its bound, as in TypeVar(T, bound=int, default=bool). #807 by @gaborbernat.ParamSpec argument list of a generic as a list, Box[[int, str]], instead of a tuple. #808 by @gaborbernat.TypeVarTuple as TypeVarTuple(Ts) linking to typing.TypeVarTuple, instead of a broken reference that loses its name. #809 by @gaborbernat.Optional[Union[...]] with simplify_optional_unions = False on Python before 3.14. #810 by @gaborbernat.typing_extensions.TypeAliasType like type statement aliases instead of as the TypeAliasType class. #811 by @gaborbernat.TYPE_CHECKING guards written through a module alias, on one line, with a comment at column zero, or at the end of the file. #813 by @gaborbernat.from __future__ import annotations. #814, #941 by @gaborbernat.TYPE_CHECKING regardless of which class Sphinx documents first. #815 by @gaborbernat.Keyword Args section, and stop always_document_param_types listing them again under Parameters. #816 by @gaborbernat.autoclass_content = "both", list each constructor parameter once, including those added through always_document_param_types or Doc(). #817, #925 by @gaborbernat.sys.version_info and sys.platform blocks, merge all overload variants of a stub function, and check re-exports. #818 by @gaborbernat.types classes, so references resolve against docs.python.org/3 when building on Python 3.12. #820 by @gaborbernat.TYPE_CHECKING in attrs class fields, fixing a NameError crash on Python 3.14 and a forward-reference warning on older versions. #822 by @gaborbernat.AttributeError building man pages for projects that document a function taking a type alias. #823 by @gaborbernat.typehints_formatter when rendering signatures with typehints_use_signature or typehints_use_signature_return. #824 by @gaborbernat."* weird" annotation stays inline instead of producing a list or crashing. #825 by @gaborbernat.forward_reference when an annotation names a missing module attribute, such as typing.TypeIs on Python 3.12. #826 by @gaborbernat..pyi stub refers to through import pkg.sub or from . import sub, so their types are no longer dropped. #827 by @gaborbernat.__module__ find their TYPE_CHECKING imports. #828 by @gaborbernat... py:type:: by name only where the annotation writes that name, whatever order Sphinx reads the entries in, so int parameters no longer render as an alias of int. #829, #920 by @gaborbernat.type alias to its own entry, not to a different documented alias with the same name. #831 by @gaborbernat.TYPE_CHECKING guards written as if not TYPE_CHECKING: ... else: or combined with and/or, so their imports resolve. #833 by @gaborbernat.self.x: T annotations nested in if, try, with, loop and match blocks of __init__, and handle a positional-only self. #834 by @gaborbernat.functools.cache and functools.lru_cache decorated functions on Python 3.14. #835 by @gaborbernat.napoleon_use_param = False or napoleon_use_keyword = False, type the entries of napoleon's combined parameter field, add their defaults, and list the parameters the extension adds there instead of in a second list. #836, #886 by @gaborbernat.typehints_defaults, show the default of a parameter typed only in its docstring, whether through a :type: line, a :param str c: field or napoleon's combined parameter field. #837, #884 by @gaborbernat.functools.singledispatch implementations, so each registered implementation shows the type it dispatches on. #838 by @gaborbernat.typehints_defaults, render defaults the way the signature does, without memory addresses, with enum members by name and with sets in a stable order. #839 by @gaborbernat.Literal values, so Literal["\n"] renders as written instead of Literal['n']. #840 by @gaborbernat.tuple[()] and Tuple[()] as the empty tuple instead of a bare tuple. #841 by @gaborbernat.type alias passed to itself, such as Pair[Pair[int]], instead of dropping the inner arguments. #842 by @gaborbernat.Literal member, as Literal[Color.RED, Light.RED] instead of Literal[RED, RED]. #843 by @gaborbernat.autodoc_mock_imports modules, such as NDArray[float64], instead of a garbled name. #844 by @gaborbernat.Literal string values that contain backticks without breaking the surrounding markup. #845 by @gaborbernat.| of a union around an autodoc_type_aliases name on Python 3.12 and 3.13 instead of rendering Optional or Union. #846 by @gaborbernat.typehints_defaults = "braces-after", put the default at the end of the last plain paragraph of the description instead of inside a trailing list, directive or literal block. #847 by @gaborbernat... placeholder as no description, so entries without one render as x (int) instead of x (int) -- ... #848 by @gaborbernat.Returns description of a function without parameters instead of adding a second one from the return annotation's Doc(). #849 by @gaborbernat.Returns section that only describes the value. #850 by @gaborbernat.:rtype: as a whole instead of leaving its continuation lines behind. #851 by @gaborbernat.typehints_use_rtype = False, add the return type to a :returns: description that contains --. #852 by @gaborbernat.always_document_param_types or Doc() in signature order among the documented ones instead of in a second list at the end of the docstring. #853 by @gaborbernat.versionadded, deprecated and seealso, as before docutils directives like note. #854 by @gaborbernat.autodoc_type_aliases targets documented as module data or in a document read later. #855 by @gaborbernat.type alias even when the docs have no entry for its arguments, instead of expanding it. #856 by @gaborbernat.typing_extensions provides on the running Python, such as TypeIs on 3.12 and Doc, to typing_extensions instead of a missing typing target. #857 by @gaborbernat.@overload signatures from other Sphinx apps in the same process that do not load the extension. #858 by @gaborbernat... include::. #859 by @gaborbernat.typehints_defaults or typehints_formatter value as a configuration error instead of an extension crash with a traceback. #860 by @gaborbernat.Unparsable type hint comment for a lambda assigned with a variable type comment. #861 by @gaborbernat.Returns entry, rendering ratio (float) -- The ratio.. #862 by @gaborbernat.undoc-members. #863 by @gaborbernat.Other Parameters section under its own heading instead of merging it into Parameters. #864 by @gaborbernat.*tuple[...], rendering it as Unpack[tuple[...]]. #865 by @gaborbernat.TypeVar(T, bound=int) without a gap after the =. #866 by @gaborbernat.InitVar[...] instead of rendering a bare InitVar. #875 by @gaborbernat.:param:, :returns: and :yields: lines inside literal blocks and directives alone instead of treating them as the object's fields. #876 by @gaborbernat.functools.partial objects, partialmethod and callable instances from the function they call, moving the annotations from the signature into the fields. #877 by @gaborbernat.type alias whose value raises, as written instead of crashing the build or dropping the object. #878, #897 by @gaborbernat.list assignment index out of range. #879 by @gaborbernat.cls from the signature of a @classmethod stacked on another decorator such as functools.cache. #880 by @gaborbernat.cannot cache unpickleable configuration value warning for typehints_fixup_module_name, and re-read the documents only when that function's source changes instead of on every build. #881, #937 by @gaborbernat.__signature__, such as a pydantic model, by that signature with its fields typed. #883 by @gaborbernat.typehints_use_rtype = False, keep the inline return type when the docstring had an :rtype: field. #885 by @gaborbernat.__init__ that dataclasses and attrs generate, instead of pointing at a nonexistent <string>.rst. #887 by @gaborbernat.autodoc_typehints_format = "fully-qualified": typehints_fully_qualified defaults to it, so fields, signatures and type parameters show full paths. An explicit typehints_fully_qualified still wins. #891 by @gaborbernat.Gen[int] | None under autodoc_mock_imports, which rendered as unlinked text on Python 3.14 or with from __future__ import annotations. #892 by @gaborbernat..pyi stub imports with a plain import but that is not installed, so types like npt.NDArray render as cross-references instead of raising a forward_reference warning. #893 by @gaborbernat... autofunction:: mod.f(x, y=3), or read from the docstring through autodoc_docstring_signature, when it names other parameters than the object takes, instead of replacing it with the object's own. One made of *args and **kwargs alone still gets the object's parameters (#903). #896 by @gaborbernat.type aliases that parameter types use, fixing broken cross-references. #902 by @gaborbernat..pyi stub when the stub changes, so an incremental build picks up the edit. #905 by @gaborbernat.Overloads list after a literal block that the summary introduces with ::, instead of inside it. #907 by @gaborbernat./ and keyword-only * markers, defaults and the stars of *args and **kwargs in Overloads entries. #910 by @gaborbernat.bound="None" on an unbound ParamSpec on Python 3.12 and early 3.13 releases. #911 by @gaborbernat.typehints_defaults mode. #913 by @gaborbernat.Explicit markup ends without a blank line warning when numpydoc processes a docstring without a Parameters section and the extension adds parameter types. #914 by @gaborbernat.Annotated[Iterator[int], {"unit": "m"}], when its docstring has a Yields section. #928 by @gaborbernat.__signature__ a decorator sets on its wrapper, so the signature and the parameter fields list the parameters callers pass instead of those of the wrapped function; the signature shows types only under typehints_use_signature. #931, #946 by @gaborbernat.Annotated return annotation before checking it, so an Annotated generator types its Yields entry instead of getting a return type, and typehints_document_rtype_none = False hides Annotated[None, ...]. #939 by @gaborbernat.if TYPE_CHECKING: block without writing to the module, so the names it defines, such as @overload stubs or Protocol classes, no longer replace runtime bindings or show up as module members. #960, #984 by @gaborbernat.__class_getitem__ returns the class itself, such as SQLAlchemy's TypeEngine[Any], in headers, parameter and return fields, signatures, overloads and :ivar: types. #963 by @gaborbernat.if TYPE_CHECKING: blocks import from each other to their guarded types, whichever module Sphinx documents first. #969 by @gaborbernat.:Parameters: definition lists, alone instead of converting them as numpydoc output into empty :param : fields. #979 by @gaborbernat.TYPE_CHECKING, such as _t.UriType in requests, instead of dropping the type. #985 by @gaborbernat..pyi stub defines to the module the stub describes, such as ext.Config, instead of rendering it as an unresolved bare Config when the function is documented through a re-export. #1011 by @gaborbernat.typing.NewType class or typing.Annotated form; the field names it as a reference, as the signature does. #1013 by @gaborbernat... autofunction:: no longer list self and -> None, and overloads of a function documented with .. autoclass:: keep their first parameter and return types. #1014 by @gaborbernat.type no longer links to an unrelated documented attribute such as Event.type. #1017 by @gaborbernat.py:class and a py:data name to the class entry on every build, instead of a name that changed with PYTHONHASHSEED. #1018 by @gaborbernat.NamedTuple's __new__ on its own, with automethod or :special-members: __new__, no longer warns that names its fields use, such as Path or int, are not defined. #1019 by @gaborbernat.__init__ now shows the type a subclass binds, such as int for class Child(Base[int]), in that subclass's :ivar: fields instead of the bare type parameter. #1020 by @gaborbernat.autodoc_mock_imports without aborting the build with wrapper loop when unwrapping. #1022 by @gaborbernat.__annotations__, so the object reads the same after a build as before it. #1025 by @gaborbernat.typehints_formatter that returns an empty string now hides the type instead of showing raw :sphinx_autodoc_typehints_type: text in docstring fields or an empty annotation such as attr: = 1 in headers and signatures, and drops the Return type, Extra items and Setter accepts fields it empties. #1026 by @gaborbernat.type statement or a module-level Count = int, used by an automodule member when its py:type comes later on the page, instead of expanding it to its value. #1027 by @gaborbernat.TYPE_CHECKING block of each module again in every build, so a module edited and imported again between builds renders its new types. #1030 by @gaborbernat.Literal to its enum when the member has no entry of its own, such as a member without a docstring under :members:, instead of rendering it unlinked with a nitpicky warning. #1035 by @gaborbernat.None, True and False inside Literal[...] to the Python docs, the same way None links outside it, instead of rendering them as plain text. #1038 by @gaborbernat.__module__ is None now renders as its bare name instead of a broken cross-reference to None.ClassName. #1039 by @gaborbernat.typehints_formatter writes between bare backticks inside an expanded type alias now use the document's default_role, as they do outside an alias, instead of rendering as italic text. #1040 by @gaborbernat.napoleon_attr_annotations off for napoleon in its own project only, so the first build after upgrading re-reads every document once. #1048 by @gaborbernat.SphinxTransform.app when choosing between an alias and its value, so builds that run Python with -W error::PendingDeprecationWarning no longer fail, and the extension keeps working on Sphinx 11. #1051 by @gaborbernat.sphinx_autodoc_typehints in extensions; the order the two are listed in no longer matters. #1052 by @gaborbernat.:rtype: or :return: now goes where Sphinx puts the types it adds with autodoc_typehints = "description": after the last field of the first list with parameters, else of the last field list, else in a new list at the end of the docstring. It no longer sits before a definition list, a doctest block, a rubric or a section, nor below a table that follows the parameters, and a warning from a docstring reports its own line rather than one counting the lines added above it. #1060 by @gaborbernat.Callable parameter list. #1064 by @gaborbernat.napoleon_attr_annotations at its configured boolean value for other Sphinx extensions. #1067 by @gaborbernat.<a name="release-3-14-0-documentation"></a>
typing with the extension, with controls in each example's conf.py tab that switch the options it renders with. #1029 by @gaborbernat.<a name="release-3-14-0-packaging"></a>
typing-extensions>=4.16 on Python versions before 3.15. #986 by @gaborbernat.Link typing.Self, Never, LiteralString, Final, TypeAlias, TypeGuard, TypeIs, Required, NotRequired, ReadOnly, Unpack, Concatenate and TypeForm to the
<a name="release-3-13-10-fixed"></a>
typing.Self, Never, LiteralString, Final, TypeAlias, TypeGuard, TypeIs, Required, NotRequired, ReadOnly, Unpack, Concatenate and TypeForm to the Python docs instead of rendering them as unresolved text, as well as ParamSpecArgs and ParamSpecKwargs on Python 3.12. #786 by @gaborbernat.Literal without empty brackets. #788 by @gaborbernat.TypeVar or ParamSpec class itself no longer prints its member descriptors. #787 by @gaborbernat.NamedTuple classes and classes that only define __new__, like other classes. #784 by @PDGGK and @gaborbernat.Link typing.Self, Never, LiteralString, Final, TypeAlias, TypeGuard, TypeIs, Required, NotRequired, ReadOnly, Unpack, Concatenate and TypeForm to the Python docs instead of rendering them as unresolved text, as well as ParamSpecArgs and ParamSpecKwargs on Python 3.12. 786 - by gaborbernat.
Render a bare Literal without empty brackets. 788 - by gaborbernat.
Annotating with the TypeVar or ParamSpec class itself no longer prints its member descriptors. 787 - by gaborbernat.
Drop the type hints from the signatures of NamedTuple classes and classes that only define __new__, like other classes. 784 - by PDGGK and gaborbernat.
Fix the forward-reference warning when documenting NumPy's clip by resolving generic parameters declared in stub signatures. #780 by @gaborbernat.
<a name="release-3-13-9-fixed"></a>
clip by resolving generic parameters declared in stub signatures. #780 by @gaborbernat.Fix the forward-reference warning when documenting NumPy's clip by resolving generic parameters declared in stub signatures. 780 - by gaborbernat.
Resolve field types of a NamedTuple imported under TYPE_CHECKING when Sphinx documents the class before any function from its module, removing a forwa
<a name="release-3-13-8-fixed"></a>
NamedTuple imported under TYPE_CHECKING when Sphinx documents the class before any function from its module, removing a forward-reference warning. #775 by @gaborbernat.Resolve 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. 775 - by gaborbernat.
Mock a dependency that a TYPE_CHECKING block imports but that is not installed, so its types still render as cross-references instead of raising a Fai
<a name="release-3-13-7-fixed"></a>
TYPE_CHECKING block imports but that is not installed, so its types still render as cross-references instead of raising a Failed guarded type import warning. Entries added to autodoc_mock_imports only to silence that warning can go. #770 by @gaborbernat.Mock a dependency that a TYPE_CHECKING block imports but that is not installed, so its types still render as cross-references instead of raising a Failed guarded type import warning. Entries added to autodoc_mock_imports only to silence that warning can go. 770 - by gaborbernat.
Expand a type alias when it is not documented and keep its name when it is, regardless of the order objects are documented in. #766 by @flying-sheep.
<a name="release-3-13-6-fixed"></a>
Expand a type alias when it is not documented and keep its name when it is, regardless of the order objects are documented in. 766 - by flying-sheep.
Fix a NameError crash for a PEP 695 alias defined in another module whose value uses names imported under TYPE_CHECKING. #765 by @gaborbernat.
<a name="release-3-13-5-fixed"></a>
NameError crash for a PEP 695 alias defined in another module whose value uses names imported under TYPE_CHECKING. #765 by @gaborbernat.Fix a NameError crash for a PEP 695 alias defined in another module whose value uses names imported under TYPE_CHECKING. 765 - by gaborbernat.
Stop warning unknown role name for annotations that carry an intersphinx external+ role. #761 by @gaborbernat.
<a name="release-3-13-4-fixed"></a>
unknown role name for annotations that carry an intersphinx external+ role. #761 by @gaborbernat.TYPE_CHECKING statement binds only the names it defines, so comprehension and loop targets no longer shadow builtins such as type in rendered annotations. #760 by @gaborbernat.Stop warning unknown role name for annotations that carry an intersphinx external+ role. 761 - by gaborbernat.
A failing TYPE_CHECKING statement binds only the names it defines, so comprehension and loop targets no longer shadow builtins such as type in rendered annotations. 760 - by gaborbernat.
Stop warning unknown role name for docstrings that reference another project through an intersphinx external+ role. #756 by @gaborbernat.
<a name="release-3-13-3-fixed"></a>
unknown role name for docstrings that reference another project through an intersphinx external+ role. #756 by @gaborbernat.TYPE_CHECKING block holding expressions the interpreter rejects no longer emits Failed guarded type import and forward-reference warnings; its names render as forward references. #757 by @gaborbernat.ExtensionError about _annotation_globals when documenting one object starts documenting another. #758 by @gaborbernat.Stop warning unknown role name for docstrings that reference another project through an intersphinx external+ role. 756 - by gaborbernat.
A TYPE_CHECKING block holding expressions the interpreter rejects no longer emits Failed guarded type import and forward-reference warnings; its names render as forward references. 757 - by gaborbernat.
Fix an ExtensionError about _annotation_globals when documenting one object starts documenting another. 758 - by gaborbernat.
Support subscripted type aliases. #745 by @flying-sheep and @gaborbernat.
<a name="release-3-13-2-added"></a>
Support subscripted type aliases. 745 - by flying-sheep and gaborbernat.
Fix a TypeError crash for a module that imports TypeAliasType, whose __type_params__ is not a tuple. #742 by @gaborbernat.
<a name="release-3-13-1-fixed"></a>
TypeError crash for a module that imports TypeAliasType, whose __type_params__ is not a tuple. #742 by @gaborbernat.TYPE_CHECKING block separately, so one unimportable name no longer leaves the names after it unbound, and keep a missing stub from cascading into forward-reference warnings. #743 by @gaborbernat.Fix a TypeError crash for a module that imports TypeAliasType, whose __type_params__ is not a tuple. 742 - by gaborbernat.
Run each top-level statement of a TYPE_CHECKING block separately, so one unimportable name no longer leaves the names after it unbound, and keep a missing stub from cascading into forward-reference warnings. 743 - by gaborbernat.
Declare Python 3.15 support. #735 by @gaborbernat.
Declare Python 3.15 support. 735 - by gaborbernat.
Resolve the self-reference of a recursive PEP 695 alias defined in another module, fixing a nitpick warning. #724 by @gaborbernat.
<a name="release-3-12-1-fixed"></a>
Resolve the self-reference of a recursive PEP 695 alias defined in another module, fixing a nitpick warning. 724 - by gaborbernat.
Render self-referential PEP 695 type aliases such as type RecType = int | list[RecType] instead of aborting with maximum recursion depth exceeded. #72
<a name="release-3-12-0-fixed"></a>
type RecType = int | list[RecType] instead of aborting with maximum recursion depth exceeded. #721 by @gaborbernat.Render self-referential PEP 695 type aliases such as type RecType = int | list[RecType] instead of aborting with maximum recursion depth exceeded. 721 - by gaborbernat.
Use the py:class role for types module members on Python 3.13+, matching the Python docs. #732 by @gaborbernat.
<a name="release-3-11-1-fixed"></a>
py:class role for types module members on Python 3.13+, matching the Python docs. #732 by @gaborbernat.Use the py:class role for types module members on Python 3.13+, matching the Python docs. 732 - by gaborbernat.
Keep the autosummary one-line summary of overloaded functions above the overload list. 731 - by gaborbernat.
Type properties and attributes of C extensions (getset and member descriptors) from their .pyi stub. #716 by @gaborbernat.
<a name="release-3-11-0-added"></a>
.pyi stub. #716 by @gaborbernat.Type properties and attributes of C extensions (getset and member descriptors) from their .pyi stub. 716 - by gaborbernat.
Keep the type and default of parameters with a trailing underscore, such as lambda_, when documented through napoleon. #714 by @gaborbernat.
<a name="release-3-10-6-fixed"></a>
lambda_, when documented through napoleon. #714 by @gaborbernat.Keep the type and default of parameters with a trailing underscore, such as lambda_, when documented through napoleon. 714 - by gaborbernat.
Survive errors raised when Python 3.14 lazily evaluates annotations, such as a non-subscriptable generic. 713 - by gaborbernat.
Keep the first parameter of methods bound on class instances. #705 by @ilia-kats.
<a name="release-3-10-5-fixed"></a>
py:class role for Ellipsis and NotImplementedType on Python 3.13+, matching the Python docs. #707 by @gaborbernat.Keep the first parameter of methods bound on class instances. 705 - by ilia-kats.
Use the py:class role for Ellipsis and NotImplementedType on Python 3.13+, matching the Python docs. 707 - by gaborbernat.
Fix a NameError crash on Python 3.14 for annotations that use names imported only under TYPE_CHECKING. #704 by @gaborbernat.
<a name="release-3-10-4-fixed"></a>
NameError crash on Python 3.14 for annotations that use names imported only under TYPE_CHECKING. #704 by @gaborbernat.Fix a NameError crash on Python 3.14 for annotations that use names imported only under TYPE_CHECKING. 704 - by gaborbernat.
Report the extension version in Sphinx error tracebacks. #687 by @kdeldycke.
<a name="release-3-10-3-added"></a>
type statement and TypeAliasType on Python 3.12+. #691 by @lochhh.<a name="release-3-10-3-fixed"></a>
typehints_formatter is set. #696 by @RazerM.Report the extension version in Sphinx error tracebacks. 687 - by kdeldycke.
Support the PEP 695 type statement and TypeAliasType on Python 3.12+. 691 - by lochhh.
Fix a cache warning when typehints_formatter is set. 696 - by RazerM.
Resolve type hints for PyO3, pybind11 and nanobind native submodules from their stubs. 702 - by gaborbernat.
Tolerate malformed :ivar fields, such as a bare :ivar :, instead of crashing. #684 by @gaborbernat.
<a name="release-3-10-2-fixed"></a>
:ivar fields, such as a bare :ivar :, instead of crashing. #684 by @gaborbernat.Tolerate malformed :ivar fields, such as a bare :ivar :, instead of crashing. 684 - by gaborbernat.
Show the annotations of functions decorated with @typing.no_type_check. #681 by @gaborbernat.
<a name="release-3-10-1-fixed"></a>
@typing.no_type_check. #681 by @gaborbernat.Show the annotations of functions decorated with @typing.no_type_check. 681 - by gaborbernat.
Fill :vartype: for instance variables documented with :ivar: and annotated in __init__ as self.name: T = .... #678 by @gaborbernat.
<a name="release-3-10-0-added"></a>
:vartype: for instance variables documented with :ivar: and annotated in __init__ as self.name: T = .... #678 by @gaborbernat.<a name="release-3-10-0-fixed"></a>
X | Y annotation. #679 by @gaborbernat.Fill :vartype: for instance variables documented with :ivar: and annotated in __init__ as self.name: T = .... 678 - by gaborbernat.
Stop documented union aliases from an intersphinx inventory replacing every X | Y annotation. 679 - by gaborbernat.
Resolve imports inside if blocks of .pyi stubs. #670 by @gaborbernat.
<a name="release-3-9-11-fixed"></a>
if blocks of .pyi stubs. #670 by @gaborbernat.TypeVar and TypedDict when resolving annotations. #671 by @gaborbernat.Resolve imports inside if blocks of .pyi stubs. 670 - by gaborbernat.
Evaluate stub-only definitions such as TypeVar and TypedDict when resolving annotations. 671 - by gaborbernat.
Use the __new__ parameter annotations from stubs instead of class variables. #667 by @gaborbernat.
<a name="release-3-9-10-fixed"></a>
__new__ parameter annotations from stubs instead of class variables. #667 by @gaborbernat.Use the __new__ parameter annotations from stubs instead of class variables. 667 - by gaborbernat.
Fix spurious forward-reference warnings when the same stubbed object is documented through several import paths. 668 - by gaborbernat.
Resolve relative imports in .pyi stubs. #663 by @gaborbernat.
<a name="release-3-9-9-fixed"></a>
.pyi stubs. #663 by @gaborbernat.Resolve relative imports in .pyi stubs. 663 - by gaborbernat.
Keep the blank line after a field list when replacing napoleon :type: fields, fixing a Field list ends without a blank line warning. #659 by @gaborber
<a name="release-3-9-8-fixed"></a>
:type: fields, fixing a Field list ends without a blank line warning. #659 by @gaborbernat.Keep the blank line after a field list when replacing napoleon :type: fields, fixing a Field list ends without a blank line warning. 659 - by gaborbernat.
Resolve NamedTuple field annotations from the class, fixing forward-reference warnings with from __future__ import annotations. #657 by @gaborbernat.
<a name="release-3-9-7-fixed"></a>
NamedTuple field annotations from the class, fixing forward-reference warnings with from __future__ import annotations. #657 by @gaborbernat.Resolve NamedTuple field annotations from the class, fixing forward-reference warnings with from __future__ import annotations. 657 - by gaborbernat.
Find stubs at the parent package level for C and Rust extension functions it re-exports. #655 by @gaborbernat.
<a name="release-3-9-6-fixed"></a>
Find stubs at the parent package level for C and Rust extension functions it re-exports. 655 - by gaborbernat.
Resolve names imported only in .pyi stubs, so stub types render as cross-references. #654 by @gaborbernat.
<a name="release-3-9-5-fixed"></a>
.pyi stubs, so stub types render as cross-references. #654 by @gaborbernat.Resolve names imported only in .pyi stubs, so stub types render as cross-references. 654 - by gaborbernat.
Find the stub of extension modules with platform-tagged filenames. #652 by @gaborbernat.
<a name="release-3-9-4-fixed"></a>
Find the stub of extension modules with platform-tagged filenames. 652 - by gaborbernat.
Stop builtin types like dict from resolving to an intersphinx alias such as wsgiref.types.WSGIEnvironment. #650 by @gaborbernat.
<a name="release-3-9-3-fixed"></a>
dict from resolving to an intersphinx alias such as wsgiref.types.WSGIEnvironment. #650 by @gaborbernat.Stop builtin types like dict from resolving to an intersphinx alias such as wsgiref.types.WSGIEnvironment. 650 - by gaborbernat.
Fix an AttributeError for intersphinx objects without __qualname__. #648 by @gaborbernat.
<a name="release-3-9-2-fixed"></a>
AttributeError for intersphinx objects without __qualname__. #648 by @gaborbernat.Fix an AttributeError for intersphinx objects without __qualname__. 648 - by gaborbernat.
Fix an AttributeError reading the intersphinx inventory on Sphinx 9.1. #647 by @gaborbernat.
<a name="release-3-9-1-fixed"></a>
AttributeError reading the intersphinx inventory on Sphinx 9.1. #647 by @gaborbernat.Fix an AttributeError reading the intersphinx inventory on Sphinx 9.1. 647 - by gaborbernat.
Remap classes whose __module__ points to a private module, such as threading.local, to their documented path using intersphinx inventories. #644 by @g
<a name="release-3-9-0-added"></a>
__module__ points to a private module, such as threading.local, to their documented path using intersphinx inventories. #644 by @gaborbernat.typehints_document_overloads option and a :no-overloads: docstring marker to turn off overload rendering. #645 by @gaborbernat.<a name="release-3-9-0-fixed"></a>
Remap classes whose __module__ points to a private module, such as threading.local, to their documented path using intersphinx inventories. 644 - by gaborbernat.
Add the typehints_document_overloads option and a :no-overloads: docstring marker to turn off overload rendering. 645 - by gaborbernat.
Resolve forward references in nested attrs classes. 646 - by gaborbernat.
Render @overload variants in the docstring. #625 by @gaborbernat.
<a name="release-3-8-0-added"></a>
@overload variants in the docstring. #625 by @gaborbernat... py:type:: instead of expanding them. #626 by @gaborbernat.annotationlib on Python 3.14+ to partially resolve forward references. #627 by @gaborbernat..pyi stub files for C extensions and other compiled modules. #630 by @gaborbernat.Annotated[T, Doc(...)] metadata as the parameter description. #631 by @gaborbernat.@attr.s classes from attr.ib(type=...). #633 by @gaborbernat.<a name="release-3-8-0-documentation"></a>
Render @overload variants in the docstring. 625 - by gaborbernat.
Keep type aliases documented with .. py:type:: instead of expanding them. 626 - by gaborbernat.
Use annotationlib on Python 3.14+ to partially resolve forward references. 627 - by gaborbernat.
Add the source location to warnings. 629 - by gaborbernat.
Resolve type hints from .pyi stub files for C extensions and other compiled modules. 630 - by gaborbernat.
Use Annotated[T, Doc(...)] metadata as the parameter description. 631 - by gaborbernat.
Read attribute types of classic @attr.s classes from attr.ib(type=...). 633 - by gaborbernat.
Rewrite the README following the Diataxis framework. 634 - by gaborbernat.
Resolve PEP 695 type parameters in annotations with from __future__ import annotations. #614 by @gaborbernat.
<a name="release-3-7-0-fixed"></a>
from __future__ import annotations. #614 by @gaborbernat.:rtype: from the preceding paragraph. #615 by @lweyrich1.Yields section. #616 by @gaborbernat.ImportError from TYPE_CHECKING blocks of third-party packages. #617 by @gaborbernat.KeyError for methods missing from the parent class __dict__. #620 by @gaborbernat.NewType as its name followed by its supertype. #622 by @gaborbernat.Literal types. #623 by @gaborbernat.:rtype: insertion point, fixing duplicate IDs with extensions such as sphinx-needs. #624 by @gaborbernat.<a name="release-3-7-0-removed"></a>
docs and testing extras; development dependencies moved to dependency groups. #612 by @gaborbernat.Resolve PEP 695 type parameters in annotations with from __future__ import annotations. 614 - by gaborbernat.
Separate an injected :rtype: from the preceding paragraph. 615 - by lweyrich1.
Skip the return type for generators whose docstring has a Yields section. 616 - by gaborbernat.
Stop warning on ImportError from TYPE_CHECKING blocks of third-party packages. 617 - by gaborbernat.
Fix a KeyError for methods missing from the parent class __dict__. 620 - by gaborbernat.
Render NewType as its name followed by its supertype. 622 - by gaborbernat.
Link enum members in Literal types. 623 - by gaborbernat.
Stop directives from running twice while locating the :rtype: insertion point, fixing duplicate IDs with extensions such as sphinx-needs. 624 - by gaborbernat.
Remove the docs and testing extras; development dependencies moved to dependency groups. 612 - by gaborbernat.
Remove the extra () after NewType in rendered output. #608 by @worksbyfriday and @gaborbernat.
<a name="release-3-6-3-fixed"></a>
() after NewType in rendered output. #608 by @worksbyfriday and @gaborbernat.ValueError for objects with circular __wrapped__ chains. #607 by @worksbyfriday and @claude.IndexError with always_document_param_types and typehints_defaults = "braces-after". #605 by @worksbyfriday and @claude.__new__ of NamedTuple subclasses. #606 by @worksbyfriday and @claude.Remove the extra () after NewType in rendered output. 608 - by worksbyfriday and gaborbernat.
Fix a ValueError for objects with circular __wrapped__ chains. 607 - by worksbyfriday and claude.
Fix an IndexError with always_document_param_types and typehints_defaults = "braces-after". 605 - by worksbyfriday and claude.
Fix a warning when documenting __new__ of NamedTuple subclasses. 606 - by worksbyfriday and claude.
Require Sphinx 9.1 and Python 3.12 or later. #595 by @gaborbernat.
<a name="release-3-6-2-added"></a>
<a name="release-3-6-2-fixed"></a>
Require Sphinx 9.1 and Python 3.12 or later. 595 - by gaborbernat.
Fix compatibility with Sphinx 9.1. 595 - by gaborbernat.
Keep Annotated metadata and Required, NotRequired and ReadOnly qualifiers in type hints. #594 by @AllanChain.
<a name="release-3-6-1-fixed"></a>
Annotated metadata and Required, NotRequired and ReadOnly qualifiers in type hints. #594 by @AllanChain.Keep Annotated metadata and Required, NotRequired and ReadOnly qualifiers in type hints. 594 - by AllanChain.
Use the Sphinx 9 class interface; require Sphinx 9.0.4 or later. #589 by @gaborbernat.
<a name="release-3-6-0-added"></a>
Use the Sphinx 9 class interface; require Sphinx 9.0.4 or later. 589 - by gaborbernat.
Keep the docstring type of a parameter without annotation that has a default value. #576 by @christianaguilera-foundry.
<a name="release-3-5-2-fixed"></a>
Keep the docstring type of a parameter without annotation that has a default value. 576 - by christianaguilera-foundry.
Declare Python 3.14 support. #571 by @gaborbernat.
Declare Python 3.14 support. 571 - by gaborbernat.
Support the Union type on its own. #570 by @gaborbernat.
<a name="release-3-5-0-added"></a>
Union type on its own. #570 by @gaborbernat.Support the Union type on its own. 570 - by gaborbernat.
Support Python 3.14. #569 by @gaborbernat.
Add types and subtypes to warnings so suppress_warnings can silence them. #562 by @fajpunk and @aeisenbarth.
<a name="release-3-3-0-added"></a>
suppress_warnings can silence them. #562 by @fajpunk and @aeisenbarth.Add types and subtypes to warnings so suppress_warnings can silence them. 562 - by fajpunk and aeisenbarth.
Fix missing links for a union with an unevaluated type alias. #533 by @nineteendo.
<a name="release-3-2-0-fixed"></a>
:rtype: None. #538 by @grayjk.:rtype: after a directive. #537 by @grayjk.<a name="release-3-2-0-documentation"></a>
Fix missing links for a union with an unevaluated type alias. 533 - by nineteendo.
Stop adding :rtype: None. 538 - by grayjk.
Place :rtype: after a directive. 537 - by grayjk.
Fix a broken changelog link. 530 - by agronholm.
Support Sphinx 8.2. #525 by @b-kamphorst and @gaborbernat.
<a name="release-3-1-0-added"></a>
Support Sphinx 8.2. 525 - by b-kamphorst and gaborbernat.
Drop Python 3.10 support, following Sphinx. 525 - by b-kamphorst and gaborbernat.
Fix the roles emitted for types module members. #516 by @flying-sheep.
<a name="release-3-0-1-fixed"></a>
types module members. #516 by @flying-sheep.Fix the roles emitted for types module members. 516 - by flying-sheep.
Drop support for nptyping. #514 by @gaborbernat.
<a name="release-3-0-0-removed"></a>
Drop support for nptyping. 514 - by gaborbernat.
Apply typehints_formatter to the signature. #494 by @Priyansh121096.
<a name="release-2-5-0-added"></a>
typehints_formatter to the signature. #494 by @Priyansh121096.Apply typehints_formatter to the signature. 494 - by Priyansh121096.
Fix a broken link in the README.
<a name="release-2-4-4-documentation"></a>
One column per quarter.