sphinx-autodoc-typehints
This Sphinx extension reads the
type hints of the code autodoc documents and writes them into the
parameter and return fields, so you state each type once, in the code. It links every part of a type to its
documentation, and resolves names your code imports only for type checkers (inside an if TYPE_CHECKING: block) or
declares in .pyi stub files. It also documents @overload variants and default values, and types Google and NumPy
style docstrings written for napoleon or numpydoc.
pip install sphinx-autodoc-typehints
# conf.py: load autodoc first, then this extension
extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]
Why not Sphinx's built-in autodoc_typehints?
Sphinx's
autodoc_typehints = "description"
already moves annotations into the parameter and return fields, links them, and works with napoleon docstrings and type
comments. If your annotations resolve at runtime and you use Sphinx fields or napoleon, that setting may be enough.
Show example code and configuration
The same demo.py below renders differently with each option. It uses typing-extensions for Doc. Both builds use
.. automodule:: demo with :members:. The left adds typehints_defaults = "braces" and
always_document_param_types = True to the configuration above; the right loads only sphinx.ext.autodoc with
autodoc_typehints = "description".
from __future__ import annotations
from typing import Annotated, Literal, NotRequired, TypedDict, Unpack, overload
from typing_extensions import Doc
class Options(TypedDict):
"""Optional controls for a request."""
retries: NotRequired[int]
trace: NotRequired[bool]
@overload
def fetch(path: str, *, mode: Literal["text"], **options: Unpack[Options]) -> str: ...
@overload
def fetch(path: str, *, mode: Literal["bytes"], **options: Unpack[Options]) -> bytes: ...
def fetch(
path: Annotated[str, Doc("resource path")],
*,
mode: Literal["text", "bytes"] = "text",
**options: Unpack[Options],
) -> str | bytes:
"""Fetch a resource.
:keyword retries: attempts after a failure
:keyword trace: log each request
"""
return "" if mode == "text" else b""
The live TypedDict example lets you change the configuration and inspect its output. See the examples for each difference:
- Names imported under
if TYPE_CHECKING:link to their real module (decimal.Decimal, not a bareDecimal). - Types from
.pyistubs fill in functions that carry no annotations, such as those of a C extension. **kwargs: Unpack[TypedDict]gets keyword fields typed from theTypedDictentries.Annotated[..., Doc(...)]puts descriptions from annotations into the parameter fields.- numpydoc
Parameterssections get types in place, rather than in a second list. @overloadvariants get anOverloadsfield, and default values appear next to the types.@deprecatednotices,@overridelinks, and property setter types add details beyond parameter types.
The full comparison lists the differences, and the live examples show each module rendered both ways.
The typing features gallery shows source and rendered output for each construct. The documentation also has a tutorial, how-to guides and the option reference; CONTRIBUTING.md explains how to work on the extension.
2 maintainers
Metadata
2 maintainers
Release files for sphinx-autodoc-typehints 3.17.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sphinx_autodoc_typehints-3.17.1.tar.gz | 569.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinx_autodoc_typehints-3.17.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 709.8 kB
Release files / sphinx_autodoc_typehints-3.17.1.tar.gz
| Download URL | sphinx_autodoc_typehints-3.17.1.tar.gz |
|---|---|
| Size | 569.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1921a9c2418b4ccd2d06c5aee4215af622455575f7a969d31cfdb96fa5db6e01
|
|
BLAKE2b-256 checksum How to use checksums |
30d5b1778a086a2b3df8b7f6f2abcb35e83919b3d5b5d076c3b6fd54a74f37d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / sphinx_autodoc_typehints-3.17.1-py3-none-any.whl
| Download URL | sphinx_autodoc_typehints-3.17.1-py3-none-any.whl |
|---|---|
| Size | 140.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
85781f33f7e4fad8fe3df8fccfb3d8858644ecc9c872c2e15542807cda3d564b
|
|
BLAKE2b-256 checksum How to use checksums |
4bd6d986d8040df3ab18d88344cd4b48cb29998aedfcdbd9158c30c38d7f0acd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency log
