more_autodoc.typehints

Enhanced version of sphinx-autodoc-typehints.
Copyright (c) Alex Grönholm

The changes are:

  • None is formatted as None and not None. If intersphinx is used this will now be a link to the Python documentation.

    Since agronholm/sphinx-autodoc-typehints#154 this feature is now available upstream.

  • If the signature of the object cannot be read, the signature provided by Sphinx will be used rather than raising an error.

    This usually occurs for methods of builtin types.

  • typing.TypeVars are linked to if they have been included in the documentation.

  • If a function/method argument has a module, class or function object as its default value a better representation will be shown in the signature.

    For example:

    serialise(obj, library=<module 'json'>)[source]

    Serialise an object into a JSON string.

    Parameters
    • obj (Any) – The object to serialise.

    • library – The JSON library to use.

    Return type

    str

    Returns

    The JSON string.

    Previously this would have shown the full path to the source file. Now it displays <module 'json'>.

  • The ability to hook into the process_docstring() function to edit the object’s properties before the annotations are added to the docstring.

    This is used by attr-utils to add annotations based on converter functions in attrs classes.

    To use this, in your extension’s setup function:

    def setup(app: Sphinx) -> Dict[str, Any]:
        from sphinx_toolbox.more_autodoc.typehints import docstring_hooks
        docstring_hooks.append((my_hook, 75))
        return {}
    

    my_hook is a function that takes the object being documented as its only argument and returns that object after modification. The 75 is the priority of the hook:

    • < 20 runs before fget functions are extracted from properties

    • < 90 runs before __new__ functions are extracted from NamedTuples.

    • < 100 runs before __init__ functions are extracted from classes.

  • Unresolved forward references are handled better.

  • Many of the built in types from the types module are now formatted and linked to correctly.


New in version 0.4.0.

Changed in version 0.6.0: Moved from sphinx_toolbox.autodoc_typehints.

Changed in version 0.8.0: Added support for collections.namedtuple().


Enable sphinx_toolbox.more_autodoc.typehints by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.more_autodoc.typehints',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

In addition, the following configuration value is added by this extension:
hide_none_rtype
Type: bool
Default: False

Hides return types of None.

API Reference

Classes:

ObjectAlias(name)

Used to represent a module, class, function etc in a Sphinx function/class signature.

Module(name)

Used to represent a module in a Sphinx function/class signature.

Function(name)

Used to represent a function in a Sphinx function/class signature.

Class(name)

Used to represent a class in a Sphinx function/class signature.

Functions:

process_signature(app, what, name, obj, …)

Process the signature for a function/method.

process_docstring(app, what, name, obj, …)

Process the docstring of a class, function, method etc.

format_annotation(annotation[, fully_qualified])

Format a type annotation.

get_all_type_hints(obj, name, original_obj)

Returns the resolved type hints for the given objects.

setup(app)

Setup sphinx_toolbox.more_autodoc.typehints.

Data:

docstring_hooks

List of additional hooks to run in process_docstring().

default_preprocessors

A list of 2-element tuples, comprising a function to check the default value against and a preprocessor to pass the function to if True.

Preprocessor

Type hint for default preprocessor functions.

class ObjectAlias(name)[source]

Bases: object

Used to represent a module, class, function etc in a Sphinx function/class signature.

New in version 0.9.0.

Parameters

name (str) – The name of the object being aliased.

__repr__()[source]

Returns a string representation of the ObjectAlias.

Return type

str

class Module(name)[source]

Bases: ObjectAlias

Used to represent a module in a Sphinx function/class signature.

Parameters

name (str) – The name of the module.

class Function(name)[source]

Bases: ObjectAlias

Used to represent a function in a Sphinx function/class signature.

New in version 0.9.0.

Parameters

name (str) – The name of the function.

class Class(name)[source]

Bases: ObjectAlias

Used to represent a class in a Sphinx function/class signature.

New in version 0.9.0.

Parameters

name (str) – The name of the class.

process_signature(app, what, name, obj, options, signature, return_annotation)[source]

Process the signature for a function/method.

Parameters
  • app (Sphinx) – The Sphinx application.

  • what (str)

  • name (str) – The name of the object being documented.

  • obj – The object being documented.

  • options – Mapping of autodoc options to values.

  • signature

  • return_annotation (Any)

Return type

Optional[Tuple[str, None]]

Changed in version 0.8.0: Added support for factory function default values in attrs classes.

process_docstring(app, what, name, obj, options, lines)[source]

Process the docstring of a class, function, method etc.

Parameters
  • app (Sphinx) – The Sphinx application.

  • what (str)

  • name (str) – The name of the object being documented.

  • obj (Any) – The object being documented.

  • options (Dict[str, Any]) – Mapping of autodoc options to values.

  • lines (List[str]) – List of strings representing the current contents of the docstring.

Changed in version 1.1.0: An empty :rtype: flag can be used to control the position of the return type annotation in the docstring.

format_annotation(annotation, fully_qualified=False)[source]

Format a type annotation.

Parameters
  • annotation (Any)

  • fully_qualified (bool) – Whether the fully qualified name should be shown (e.g. typing.List) or only the object name (e.g. List). Default False.

Return type

str

Changed in version 2.13.0: Added support for True and False

get_all_type_hints(obj, name, original_obj)[source]

Returns the resolved type hints for the given objects.

Parameters
  • obj (Any)

  • name (str)

  • original_obj (Any) – The original object, before the class if obj is its __init__ method.

Return type

Dict[str, Any]

Preprocessor

Type hint for default preprocessor functions.

Alias of Callable[[Type], Any]

docstring_hooks

Type:    List[Tuple[Callable[[Any], Callable], int]]

List of additional hooks to run in process_docstring().

Each entry in the list consists of:

  • a function that takes the object being documented as its only argument and returns that object after modification.

  • a number giving the priority of the hook, in ascending order.

    • < 20 runs before fget functions are extracted from properties

    • < 90 runs before __new__ functions are extracted from NamedTuples.

    • < 100 runs before __init__ functions are extracted from classes.

default_preprocessors

Type:    List[Tuple[Callable[[Type], bool], Callable[[Type], Any]]]

A list of 2-element tuples, comprising a function to check the default value against and a preprocessor to pass the function to if True.

setup(app)[source]

Setup sphinx_toolbox.more_autodoc.typehints.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata