# sphinx-autodoc-typehints
[](https://pypi.org/project/sphinx-autodoc-typehints/)
[](https://pypi.org/project/sphinx-autodoc-typehints/)
[](https://pepy.tech/project/sphinx-autodoc-typehints)
[](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml)
This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types
of functions. See an example of the Sphinx render at the
[pyproject-api docs](https://pyproject-api.readthedocs.io/latest/api.html).
This allows you to use type hints in a very natural fashion, allowing you to migrate from this:
```python
def format_unit(value, unit):
"""
Formats the given value as a human readable string using the given units.
:param float|int value: a numeric value
:param str unit: the unit for the value (kg, m, etc.)
:rtype: str
"""
return f"{value} {unit}"
```
to this:
```python
from typing import Union
def format_unit(value: Union[float, int], unit: str) -> str:
"""
Formats the given value as a human readable string using the given units.
:param value: a numeric value
:param unit: the unit for the value (kg, m, etc.)
"""
return f"{value} {unit}"
```
## Installation and setup
First, use pip to download and install the extension:
```bash
pip install sphinx-autodoc-typehints
```
Then, add the extension to your `conf.py`:
```python
extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]
```
## Options
The following configuration options are accepted:
- `typehints_fully_qualified` (default: `False`): if `True`, class names are always fully qualified (e.g.
`module.for.Class`). If `False`, just the class name displays (e.g. `Class`)
- `always_document_param_types` (default: `False`): If `False`, do not add type info for undocumented parameters. If
`True`, add stub documentation for undocumented parameters to be able to add type info.
- `always_use_bars_union ` (default: `False`): If `True`, display Union's using the | operator described in PEP 604.
(e.g `X` | `Y` or `int` | `None`). If `False`, Unions will display with the typing in brackets. (e.g. `Union[X, Y]`
or `Optional[int]`)
- `typehints_document_rtype` (default: `True`): If `False`, never add an `:rtype:` directive. If `True`, add the
`:rtype:` directive if no existing `:rtype:` is found.
- `typehints_use_rtype` (default: `True`): Controls behavior when `typehints_document_rtype` is set to `True`. If
`True`, document return type in the `:rtype:` directive. If `False`, document return type as part of the `:return:`
directive, if present, otherwise fall back to using `:rtype:`. Use in conjunction with
[napoleon_use_rtype](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_use_rtype)
to avoid generation of duplicate or redundant return type information.
- `typehints_defaults` (default: `None`): If `None`, defaults are not added. Otherwise, adds a default annotation:
- `'comma'` adds it after the type, changing Sphinx’ default look to “**param** (_int_, default: `1`) -- text”.
- `'braces'` adds `(default: ...)` after the type (useful for numpydoc like styles).
- `'braces-after'` adds `(default: ...)` at the end of the parameter documentation text instead.
- `simplify_optional_unions` (default: `True`): If `True`, optional parameters of type \"Union\[\...\]\" are simplified
as being of type Union\[\..., None\] in the resulting documentation (e.g. Optional\[Union\[A, B\]\] -\> Union\[A, B,
None\]). If `False`, the \"Optional\"-type is kept. Note: If `False`, **any** Union containing `None` will be
displayed as Optional! Note: If an optional parameter has only a single type (e.g Optional\[A\] or Union\[A, None\]),
it will **always** be displayed as Optional!
- `typehints_formatter` (default: `None`): If set to a function, this function will be called with `annotation` as first
argument and `sphinx.config.Config` argument second. The function is expected to return a string with reStructuredText
code or `None` to fall back to the default formatter.
- `typehints_use_signature` (default: `False`): If `True`, typehints for parameters in the signature are shown.
- `typehints_use_signature_return` (default: `False`): If `True`, return annotations in the signature are shown.
## How it works
The extension listens to the `autodoc-process-signature` and `autodoc-process-docstring` Sphinx events. In the former,
it strips the annotations from the function signature. In the latter, it injects the appropriate `:type argname:` and
`:rtype:` directives into the docstring.
Only arguments that have an existing `:param:` directive in the docstring get their respective `:type:` directives
added. The `:rtype:` directive is added if and only if no existing `:rtype:` is found.
## Compatibility with sphinx.ext.napoleon
To use [sphinx.ext.napoleon](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) with sphinx-autodoc-typehints, make
sure you load [sphinx.ext.napoleon](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) first, **before**
sphinx-autodoc-typehints. See [Issue 15](https://github.com/tox-dev/sphinx-autodoc-typehints/issues/15) on the issue
tracker for more information.
## Dealing with circular imports
Sometimes functions or classes from two different modules need to reference each other in their type annotations. This
creates a circular import problem. The solution to this is the following:
1. Import only the module, not the classes/functions from it
2. Use forward references in the type annotations (e.g. `def methodname(self, param1: 'othermodule.OtherClass'):`)
On Python 3.7, you can even use `from __future__ import annotations` and remove the quotes.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-autodoc-typehints",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Bern\u00e1t G\u00e1bor <gaborjbernat@gmail.com>",
"keywords": "environments, isolated, testing, virtual",
"author": null,
"author_email": "Bern\u00e1t G\u00e1bor <gaborjbernat@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2e/a0/4f17d564c86aa269749d99dd498a5c94abe0915d2ff349187f8ff8c75994/sphinx_autodoc_typehints-2.5.0.tar.gz",
"platform": null,
"description": "# sphinx-autodoc-typehints\n\n[](https://pypi.org/project/sphinx-autodoc-typehints/)\n[](https://pypi.org/project/sphinx-autodoc-typehints/)\n[](https://pepy.tech/project/sphinx-autodoc-typehints)\n[](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml)\n\nThis extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types\nof functions. See an example of the Sphinx render at the\n[pyproject-api docs](https://pyproject-api.readthedocs.io/latest/api.html).\n\nThis allows you to use type hints in a very natural fashion, allowing you to migrate from this:\n\n```python\ndef format_unit(value, unit):\n \"\"\"\n Formats the given value as a human readable string using the given units.\n\n :param float|int value: a numeric value\n :param str unit: the unit for the value (kg, m, etc.)\n :rtype: str\n \"\"\"\n return f\"{value} {unit}\"\n```\n\nto this:\n\n```python\nfrom typing import Union\n\n\ndef format_unit(value: Union[float, int], unit: str) -> str:\n \"\"\"\n Formats the given value as a human readable string using the given units.\n\n :param value: a numeric value\n :param unit: the unit for the value (kg, m, etc.)\n \"\"\"\n return f\"{value} {unit}\"\n```\n\n## Installation and setup\n\nFirst, use pip to download and install the extension:\n\n```bash\npip install sphinx-autodoc-typehints\n```\n\nThen, add the extension to your `conf.py`:\n\n```python\nextensions = [\"sphinx.ext.autodoc\", \"sphinx_autodoc_typehints\"]\n```\n\n## Options\n\nThe following configuration options are accepted:\n\n- `typehints_fully_qualified` (default: `False`): if `True`, class names are always fully qualified (e.g.\n `module.for.Class`). If `False`, just the class name displays (e.g. `Class`)\n- `always_document_param_types` (default: `False`): If `False`, do not add type info for undocumented parameters. If\n `True`, add stub documentation for undocumented parameters to be able to add type info.\n- `always_use_bars_union ` (default: `False`): If `True`, display Union's using the | operator described in PEP 604.\n (e.g `X` | `Y` or `int` | `None`). If `False`, Unions will display with the typing in brackets. (e.g. `Union[X, Y]`\n or `Optional[int]`)\n- `typehints_document_rtype` (default: `True`): If `False`, never add an `:rtype:` directive. If `True`, add the\n `:rtype:` directive if no existing `:rtype:` is found.\n- `typehints_use_rtype` (default: `True`): Controls behavior when `typehints_document_rtype` is set to `True`. If\n `True`, document return type in the `:rtype:` directive. If `False`, document return type as part of the `:return:`\n directive, if present, otherwise fall back to using `:rtype:`. Use in conjunction with\n [napoleon_use_rtype](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_use_rtype)\n to avoid generation of duplicate or redundant return type information.\n- `typehints_defaults` (default: `None`): If `None`, defaults are not added. Otherwise, adds a default annotation:\n\n - `'comma'` adds it after the type, changing Sphinx\u2019 default look to \u201c**param** (_int_, default: `1`) -- text\u201d.\n - `'braces'` adds `(default: ...)` after the type (useful for numpydoc like styles).\n - `'braces-after'` adds `(default: ...)` at the end of the parameter documentation text instead.\n\n- `simplify_optional_unions` (default: `True`): If `True`, optional parameters of type \\\"Union\\[\\...\\]\\\" are simplified\n as being of type Union\\[\\..., None\\] in the resulting documentation (e.g. Optional\\[Union\\[A, B\\]\\] -\\> Union\\[A, B,\n None\\]). If `False`, the \\\"Optional\\\"-type is kept. Note: If `False`, **any** Union containing `None` will be\n displayed as Optional! Note: If an optional parameter has only a single type (e.g Optional\\[A\\] or Union\\[A, None\\]),\n it will **always** be displayed as Optional!\n- `typehints_formatter` (default: `None`): If set to a function, this function will be called with `annotation` as first\n argument and `sphinx.config.Config` argument second. The function is expected to return a string with reStructuredText\n code or `None` to fall back to the default formatter.\n- `typehints_use_signature` (default: `False`): If `True`, typehints for parameters in the signature are shown.\n- `typehints_use_signature_return` (default: `False`): If `True`, return annotations in the signature are shown.\n\n## How it works\n\nThe extension listens to the `autodoc-process-signature` and `autodoc-process-docstring` Sphinx events. In the former,\nit strips the annotations from the function signature. In the latter, it injects the appropriate `:type argname:` and\n`:rtype:` directives into the docstring.\n\nOnly arguments that have an existing `:param:` directive in the docstring get their respective `:type:` directives\nadded. The `:rtype:` directive is added if and only if no existing `:rtype:` is found.\n\n## Compatibility with sphinx.ext.napoleon\n\nTo use [sphinx.ext.napoleon](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) with sphinx-autodoc-typehints, make\nsure you load [sphinx.ext.napoleon](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) first, **before**\nsphinx-autodoc-typehints. See [Issue 15](https://github.com/tox-dev/sphinx-autodoc-typehints/issues/15) on the issue\ntracker for more information.\n\n## Dealing with circular imports\n\nSometimes functions or classes from two different modules need to reference each other in their type annotations. This\ncreates a circular import problem. The solution to this is the following:\n\n1. Import only the module, not the classes/functions from it\n2. Use forward references in the type annotations (e.g. `def methodname(self, param1: 'othermodule.OtherClass'):`)\n\nOn Python 3.7, you can even use `from __future__ import annotations` and remove the quotes.\n",
"bugtrack_url": null,
"license": null,
"summary": "Type hints (PEP 484) support for the Sphinx autodoc extension",
"version": "2.5.0",
"project_urls": {
"Changelog": "https://github.com/tox-dev/sphinx-autodoc-typehints/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/tox-dev/sphinx-autodoc-typehints",
"Source": "https://github.com/tox-dev/sphinx-autodoc-typehints",
"Tracker": "https://github.com/tox-dev/sphinx-autodoc-typehints/issues"
},
"split_keywords": [
"environments",
" isolated",
" testing",
" virtual"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "faae322d05bec884977b89eced3af811c228652a9e25f9646ee6236890987214",
"md5": "e7c093b4f0a31fc8a8ee81d8b104ec4a",
"sha256": "53def4753239683835b19bfa8b68c021388bd48a096efcb02cdab508ece27363"
},
"downloads": -1,
"filename": "sphinx_autodoc_typehints-2.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7c093b4f0a31fc8a8ee81d8b104ec4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20104,
"upload_time": "2024-10-09T01:42:57",
"upload_time_iso_8601": "2024-10-09T01:42:57.945538Z",
"url": "https://files.pythonhosted.org/packages/fa/ae/322d05bec884977b89eced3af811c228652a9e25f9646ee6236890987214/sphinx_autodoc_typehints-2.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ea04f17d564c86aa269749d99dd498a5c94abe0915d2ff349187f8ff8c75994",
"md5": "e11698413b4269989f708b643fc6991a",
"sha256": "259e1026b218d563d72743f417fcc25906a9614897fe37f91bd8d7d58f748c3b"
},
"downloads": -1,
"filename": "sphinx_autodoc_typehints-2.5.0.tar.gz",
"has_sig": false,
"md5_digest": "e11698413b4269989f708b643fc6991a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40822,
"upload_time": "2024-10-09T01:42:59",
"upload_time_iso_8601": "2024-10-09T01:42:59.452592Z",
"url": "https://files.pythonhosted.org/packages/2e/a0/4f17d564c86aa269749d99dd498a5c94abe0915d2ff349187f8ff8c75994/sphinx_autodoc_typehints-2.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 01:42:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tox-dev",
"github_project": "sphinx-autodoc-typehints",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx-autodoc-typehints"
}
JSON
