Type hints (PEP 484) support for the Sphinx autodoc extension
Project description
This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of functions. This allows you to use type hints in a very natural fashion, allowing you to migrate from this:
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 '{} {}'.format(value, unit)to this:
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 '{} {}'.format(value, unit)Installation and setup
First, use pip to download and install the extension:
$ pip install sphinx-autodoc-typehints
Then, add the extension to your conf.py:
extensions = [
'sphinx.ext.autodoc',
'sphinx_autodoc_typehints'
]Options
The following configuration options are accepted:
set_type_checking_flag (default: True): if True, set typing.TYPE_CHECKING to True to enable “expensive” typing imports
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 with sphinx-autodoc-typehints, make sure you load sphinx.ext.napoleon first, before sphinx-autodoc-typehints. See Issue 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:
Import only the module, not the classes/functions from it
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.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx-autodoc-typehints-1.5.2.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 9f546fa18ee6bfb17f5cf937805d3c8afea48b976050db0bd14bb463eee97888 |
|
| MD5 | 6f7ea45dd7570d2eaed8645d096afe7b |
|
| BLAKE2b-256 | 6627facb64793f41c524e0aa0604b7f17d589127dda649d0778c142bf7b6d8fc |
Hashes for sphinx_autodoc_typehints-1.5.2-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | adfa4712e77c795522574ce644e084cded2f6e796a59d37e7f1cb98287687100 |
|
| MD5 | 860b602d92ae027b2b858df35894f1b3 |
|
| BLAKE2b-256 | 2fad18d763ea3e0750ede76d37e4d5dc53f00702d82f777c1964b07152cb744b |
