Repository files navigation

This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value typesof functions. See an example of the Sphinx render at thepyproject-api docs.

This allows you to use type hints in a very natural fashion, allowing you to migrate from this:

defformat_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    """returnf"{value}{unit}"

to this:

fromtypingimportUniondefformat_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.)    """returnf"{value}{unit}"

First, use pip to download and install the extension:

pip install sphinx-autodoc-typehints

Then, add the extension to yourconf.py:

extensions= ["sphinx.ext.autodoc","sphinx_autodoc_typehints"]

The following configuration options are accepted:

• typehints_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.

• always_use_bars_union (default:False): IfTrue, display Union's using the | operator described in PEP 604.(e.gX |Y orint |None). IfFalse, Unions will display with the typing in brackets. (e.g.Union[X, Y]orOptional[int])

• typehints_document_rtype (default:True): IfFalse, never add an:rtype: directive. IfTrue, add the:rtype: directive if no existing:rtype: is found.

• typehints_document_rtype_none (default:True): IfFalse, never add an:rtype: None directive. IfTrue, add the:rtype: None.

• typehints_use_rtype (default:True): Controls behavior whentypehints_document_rtype is set toTrue. IfTrue, document return type in the:rtype: directive. IfFalse, document return type as part of the:return:directive, if present, otherwise fall back to using:rtype:. Use in conjunction withnapoleon_use_rtypeto avoid generation of duplicate or redundant return type information.

• typehints_defaults (default:None): IfNone, 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): IfTrue, optional parameters of type "Union[...]" are simplifiedas being of type Union[..., None] in the resulting documentation (e.g. Optional[Union[A, B]] -> Union[A, B,None]). IfFalse, the "Optional"-type is kept. Note: IfFalse,any Union containingNone will bedisplayed as Optional! Note: If an optional parameter has only a single type (e.g Optional[A] or Union[A, None]),it willalways be displayed as Optional!

• typehints_formatter (default:None): If set to a function, this function will be called withannotation as firstargument andsphinx.config.Config argument second. The function is expected to return a string with reStructuredTextcode orNone to fall back to the default formatter.

• typehints_use_signature (default:False): IfTrue, typehints for parameters in the signature are shown.

• typehints_use_signature_return (default:False): IfTrue, return annotations in the signature are shown.

The extension listens to theautodoc-process-signature andautodoc-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: directivesadded. The:rtype: directive is added if and only if no existing:rtype: is found.

To usesphinx.ext.napoleon with sphinx-autodoc-typehints, makesure you loadsphinx.ext.napoleon first,beforesphinx-autodoc-typehints. SeeIssue 15 on the issuetracker for more information.

Sometimes functions or classes from two different modules need to reference each other in their type annotations. Thiscreates 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 usefrom __future__ import annotations and remove the quotes.