sphinx-autodoc-typehints
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:False): ifTrue, settyping.TYPE_CHECKINGtoTrueto enable "expensive" typing importstypehints_fully_qualified(default:False): ifTrue, class names are always fully qualified (e.g.module.for.Class). IfFalse, just the class name displays (e.g.Class)always_document_param_types(default:False): IfFalse, do not add type info for undocumented parameters. IfTrue, add stub documentation for undocumented parameters to be able to add type info.typehints_document_rtype(default:True): IfFalse, never add an:rtype:directive. IfTrue, add the:rtype:directive if no existing:rtype:is found.
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.
Using type hint comments
If you're documenting code that needs to stay compatible with Python 2.7, you cannot use regular type annotations. Instead, you must either be using Python 3.8 or later or have typed_ast installed. The package extras type_comments will pull in the appropiate dependencies automatically. Then you can add type hint comments in the following manner:
def myfunction(arg1, arg2):
# type: (int, str) -> int
return 42
or alternatively:
def myfunction(
arg1, # type: int
arg2 # type: str
):
# type: (...) -> int
return 42
11 Nov 25, 2022
166 Dec 29, 2022
5.1k Jan 2, 2023
831 Dec 27, 2022
4.3k Dec 31, 2022
234 Dec 26, 2022
643 Dec 31, 2022
440 Jan 6, 2023
144 Jan 6, 2023
584 Nov 16, 2022
118 Dec 31, 2022
71 Dec 26, 2022
2 Dec 26, 2022
8 Dec 15, 2022
4 Nov 22, 2022
6 Dec 22, 2022
506 Jan 3, 2023