Skip to main content

No project description provided

Project description

This extension allows you to use Python 3 type annotations for documenting module and class attributes and function arguments and return types. The extension also has support for cyclic imports needed due to type annotations. The extension only works for Python 3.7 and higher and requires the use of from __future__ import annotations.

Example (a_module.py):

from __future__ import annotations

import typing as t

if t.TYPE_CHECKING:
    import another_module

module_attribute: t.Optional[another_module.SomeClass] = None
'''An attribute of the module.'''

class AClass:
    '''A class.'''

    instance_attribute: int
    '''An instance attribute.'''

    class_attribute: float = 3.0
    '''A class attribute.'''

    def __init__(self, arg: t.Union[int, str]):
        pass

    def method(self) -> int:
        '''A method.'''
        pass

Example (another_module.py):

from __future__ import annotations

import typing

if typing.TYPE_CHECKING:
    import a_module

def function(arg: a_module.AClass):
    '''A function.'''
    pass

class SomeClass:
    pass

Installation and setup

First, use pip to download and install the extension:

$ pip install sphinx_autodoc_future_annotations

Then, add the extension to your conf.py:

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

How it works

Cyclic imports needed due to type annotations are supported in the following way. First, a hook is monkey-patched into sphinx.ext.autodoc to act when a module is imported. This hook first imports the module normally. Then it parses the module’s code and finds any top-level if-statements that are conditional on TYPE_CHECKING from the typing module. All statements inside such if-statements are executed in the context of te module. This makes the additional imports available to typing.get_type_hints.

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.

The :type argname: and :rtype: directives are added if and only if no existing matching directive is found. Empty :param argname: directives are added if no matching directive is found. This allows to document the type of an argument without having to add trivial documentation on its use.

This extension does not currently have any configuration options.

Some of the code is adapted from sphinx-autodoc-typehints.

Compatibility with sphinx.ext.napoleon

To use sphinx.ext.napoleon with sphinx_autodoc_future_annotations, make sure you load sphinx.ext.napoleon first, before sphinx_autodoc_future_annotations.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_future_annotations',
]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_autodoc_future_annotations-0.1.3.tar.gz (5.1 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file sphinx_autodoc_future_annotations-0.1.3.tar.gz.

File metadata

  • Download URL: sphinx_autodoc_future_annotations-0.1.3.tar.gz
  • Upload date:
  • Size: 5.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.7.0

File hashes

Hashes for sphinx_autodoc_future_annotations-0.1.3.tar.gz
Algorithm Hash digest
SHA256 18850a66bcf2a0709e17abf4588c66ea7758f01c28922eedd31d79ab4264c08e
MD5 52c72d48c609736b8da31b2deea7b829
BLAKE2b-256 d9db9f483bd2a6c7ed3e3a25cf3e19ceccfe9ca40f698ad345f9c131dc44b2f3

See more details on using hashes here.

File details

Details for the file sphinx_autodoc_future_annotations-0.1.3-py3-none-any.whl.

File metadata

  • Download URL: sphinx_autodoc_future_annotations-0.1.3-py3-none-any.whl
  • Upload date:
  • Size: 5.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.7.0

File hashes

Hashes for sphinx_autodoc_future_annotations-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 4c5c08d3bcc5a35953aa29cb233e9a0026f886caa936bf3bd05b957be21b55b8
MD5 276cad63ffccad6bc46def55014e0df7
BLAKE2b-256 13b95e8c20aeaad4d41f30373b7fb9aec73fee1cff1479c277f54c4683d4d513

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page