sat

sphinx-autodoc-typehints

Type hints support for the Sphinx autodoc extension

Showing:

Popularity

Downloads/wk

0

GitHub Stars

362

Maintenance

Last Commit

3d ago

Contributors

31

Package

Dependencies

7

License

MIT

Categories

Readme

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:

.. code-block:: 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 '{} {}'.format(value, unit)

to this:

.. code-block:: 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 '{} {}'.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:

.. code-block:: python

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

Options

The following configuration options are accepted:

  • set_type_checking_flag (default: False): if True, set typing.TYPE_CHECKING to True to enable "expensive" typing imports
  • 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.
  • typehints_document_rtype (default: True): If False, never add an :rtype: directive. If True, add the :rtype: directive if no existing :rtype: is found.
  • simplify_optional_unions (default: True): If True, optional parameters of type "Union[...]" are simplified as being of type Union[..., None] in the resulting documention (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!

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.

.. _sphinx.ext.napoleon: http://www.sphinx-doc.org/en/stable/ext/napoleon.html .. _Issue 15: https://github.com/agronholm/sphinx-autodoc-typehints/issues/15

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 typedast installed. The package extras type_comments will pull in the appropiate dependencies automatically. Then you can add type hint comments in the following manner:

.. code-block:: python

def myfunction(arg1, arg2):
    # type: (int, str) -> int
    return 42

or alternatively:

.. code-block:: python

def myfunction(
    arg1,  # type: int
    arg2  # type: str
):
    # type: (...) -> int
    return 42

.. _typed_ast: https://pypi.org/project/typed-ast/

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100