sphinx-autodoc-typehints


Namesphinx-autodoc-typehints JSON
Version 2.5.0 PyPI version JSON
download
home_pageNone
SummaryType hints (PEP 484) support for the Sphinx autodoc extension
upload_time2024-10-09 01:42:59
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseNone
keywords environments isolated testing virtual
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # sphinx-autodoc-typehints

[![PyPI](https://img.shields.io/pypi/v/sphinx-autodoc-typehints?style=flat-square)](https://pypi.org/project/sphinx-autodoc-typehints/)
[![Supported Python
versions](https://img.shields.io/pypi/pyversions/sphinx-autodoc-typehints.svg)](https://pypi.org/project/sphinx-autodoc-typehints/)
[![Downloads](https://pepy.tech/badge/sphinx-autodoc-typehints/month)](https://pepy.tech/project/sphinx-autodoc-typehints)
[![check](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml/badge.svg)](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[![PyPI](https://img.shields.io/pypi/v/sphinx-autodoc-typehints?style=flat-square)](https://pypi.org/project/sphinx-autodoc-typehints/)\n[![Supported Python\nversions](https://img.shields.io/pypi/pyversions/sphinx-autodoc-typehints.svg)](https://pypi.org/project/sphinx-autodoc-typehints/)\n[![Downloads](https://pepy.tech/badge/sphinx-autodoc-typehints/month)](https://pepy.tech/project/sphinx-autodoc-typehints)\n[![check](https://github.com/tox-dev/sphinx-autodoc-typehints/actions/workflows/check.yaml/badge.svg)](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"
}
        
Elapsed time: 0.40255s