Metadata-Version: 2.5
Name: sphinx-autodoc-typehints
Version: 3.16.0
Summary: Type hints (PEP 484) support for the Sphinx autodoc extension
Project-URL: Changelog, https://github.com/tox-dev/sphinx-autodoc-typehints/releases
Project-URL: Documentation, https://sphinx-autodoc-typehints.readthedocs.io
Project-URL: Homepage, https://github.com/tox-dev/sphinx-autodoc-typehints
Project-URL: Source, https://github.com/tox-dev/sphinx-autodoc-typehints
Project-URL: Tracker, https://github.com/tox-dev/sphinx-autodoc-typehints/issues
Author-email: Bernát Gábor <gaborjbernat@gmail.com>
Maintainer-email: Bernát Gábor <gaborjbernat@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: autodoc,documentation,sphinx,type hints
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: sphinx>=9.1
Requires-Dist: typing-extensions>=4.16; python_version < '3.15'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tox-dev/sphinx-autodoc-typehints/main/docs/_static/logo-horizontal-dark.svg">
  <img alt="sphinx-autodoc-typehints" src="https://raw.githubusercontent.com/tox-dev/sphinx-autodoc-typehints/main/docs/_static/logo-horizontal.svg" width="480">
</picture>

# sphinx-autodoc-typehints

[![PyPI](https://img.shields.io/pypi/v/sphinx-autodoc-typehints?style=flat-square)](https://pypi.org/project/sphinx-autodoc-typehints/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinx-autodoc-typehints.svg)](https://pypi.org/project/sphinx-autodoc-typehints/)
[![Documentation status](https://readthedocs.org/projects/sphinx-autodoc-typehints/badge/?version=latest)](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/?badge=latest)
[![Downloads](https://pepy.tech/badge/sphinx-autodoc-typehints/month)](https://pepy.tech/project/sphinx-autodoc-typehints)
[![check](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml)

This [Sphinx](https://www.sphinx-doc.org/) extension reads the
[type hints](https://docs.python.org/3/library/typing.html) 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.

```bash
pip install sphinx-autodoc-typehints
```

```python
# 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"`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints)
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.

<details>
<summary>Show example code and configuration</summary>

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"`.

```python
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""
```

</details>

![This extension puts overloads in a field, types the retries and trace keywords, and turns Annotated Doc into a path description. Built-in Sphinx keeps the overloads in signatures and leaves those keyword descriptions untyped.](https://raw.githubusercontent.com/tox-dev/sphinx-autodoc-typehints/main/docs/_static/sphinx-comparison.png)

The
[live TypedDict example](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/concepts.html#keyword-arguments-from-a-typeddict)
lets you change the configuration and inspect its output. See the examples for each difference:

- [Names imported under `if TYPE_CHECKING:`](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html#type-checking-imports)
  link to their real module (`decimal.Decimal`, not a bare `Decimal`).
- [Types from `.pyi` stubs](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/how-to.html#pyi-stubs) fill in
  functions that carry no annotations, such as those of a C extension.
- [`**kwargs: Unpack[TypedDict]`](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html#kwargs-typed-with-unpack)
  gets keyword fields typed from the `TypedDict` entries.
- [`Annotated[..., Doc(...)]`](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html#doc) puts
  descriptions from annotations into the parameter fields.
- [numpydoc `Parameters` sections](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/how-to.html#use-with-numpydoc)
  get types in place, rather than in a second list.
- [`@overload` variants](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html#overload) get an
  `Overloads` field, and
  [default values](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/how-to.html#show-default-values) appear
  next to the types.
- [`@deprecated` notices](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html#deprecated),
  [`@override` links](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html#override), and
  [property setter types](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/reference.html#property-setters) add
  details beyond parameter types.

The
[full comparison](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/concepts.html#compared-with-sphinx-s-built-in-type-hints)
lists the differences, and the live examples show each module rendered both ways.

The [typing features gallery](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/typing.html) shows source and
rendered output for each construct. The [documentation](https://sphinx-autodoc-typehints.readthedocs.io/en/latest/) also
has a tutorial, how-to guides and the option reference; [CONTRIBUTING.md](https://github.com/tox-dev/sphinx-autodoc-typehints/blob/main/CONTRIBUTING.md) explains how to work on the
extension.
