more_autodoc.autonamedtuple

A Sphinx directive for documenting NamedTuples in Python.

New in version 0.8.0.

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

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

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

Changed in version 1.5.0: __new__ methods are documented regardless of other exclusion settings if the annotations differ from the namedtuple itself.

Usage

.. autonamedtuple::

Directive to automatically document a typing.NamedTuple or collections.namedtuple().

The output is based on the autoclass directive. The list of parameters and the attributes are replaced by a list of Fields, combining the types and docstrings from the class docstring individual attributes. These will always be shown regardless of the state of the :members: option.

Otherwise the directive behaves the same as autoclass, and takes all of its arguments. See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html for further information.

New in version 0.8.0.

:namedtuple:

Role which provides a cross-reference to the documentation generated by autonamedtuple.

:namedtuple-field:

Role which provides a cross-reference to a field in the namedtuple documentation.

New in version 3.0.0.

Note

Due to limitations in docutils cross-references for all fields in a namedtuple will point to the top of the fields list, rather than the individial fields.

See also

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# Examples from
# https://docs.python.org/3/library/typing.html#typing.NamedTuple
# https://www.python.org/dev/peps/pep-0589/#totality
# https://github.com/python/typing/pull/700

# stdlib
import collections
from typing import NamedTuple

__all__ = ("Animal", "Employee", "Movie")


class Animal(NamedTuple):
    """
    An animal.

    :param name: The name of the animal.
    :param voice: The animal's voice.
    """

    name: str
    voice: str


class Employee(NamedTuple):
    """
    Represents an employee.

    :param id: The employee's ID number
    """

    #: The employee's name
    name: str

    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

    def is_executive(self) -> bool:
        """
        Returns whether the employee is an executive.

        Executives have ID numbers < 10.
        """


class Movie(NamedTuple):
    """
    Represents a movie.
    """

    #: The name of the movie.
    name: str

    #: The movie's release year.
    year: int

    based_on: str


.. automodule:: autonamedtuple_demo
    :no-autosummary:
    :exclude-members: Movie

.. autonamedtuple:: autonamedtuple_demo.Movie

This function takes a single argument, the :namedtuple:`~.Movie` to watch.
The name of the movie can be accessed with the :namedtuple-field:`~.Movie.name` attribute.
namedtuple Animal(name, voice)[source]

Bases: NamedTuple

An animal.

Fields:

  1.  name (str) – The name of the animal.

  2.  voice (str) – The animal’s voice.

__repr__()

Return a nicely formatted representation string

namedtuple Employee(name, id=3)[source]

Bases: NamedTuple

Represents an employee.

Fields:

  1.  name (str) – The employee’s name

  2.  id (int) – The employee’s ID number

__repr__()[source]

Return repr(self).

Return type:

str

is_executive()[source]

Returns whether the employee is an executive.

Executives have ID numbers < 10.

Return type:

bool

namedtuple Movie(name, year, based_on)[source]

Bases: NamedTuple

Represents a movie.

Fields:

  1.  name (str) – The name of the movie.

  2.  year (int) – The movie’s release year.

  3.  based_on (str) – Alias for field number 2

__repr__()

Return a nicely formatted representation string

This function takes a single argument, the Movie to watch. The name of the movie can be accessed with the name attribute.

API Reference

Classes:

NamedTupleDocumenter(directive, name[, indent])

Sphinx autodoc Documenter for documenting typing.NamedTuples.

Functions:

setup(app)

Setup sphinx_toolbox.more_autodoc.autonamedtuple.
class NamedTupleDocumenter(directive, name, indent='')[source]

Bases: ClassDocumenter

Sphinx autodoc Documenter for documenting typing.NamedTuples.

New in version 0.8.0.

Changed in version 0.1.0: Will no longer attempt to find attribute docstrings from other namedtuple classes.

Methods:

add_content(more_content[, no_docstring])

Add extra content (from docstrings, attribute docs etc.), but not the typing.NamedTuple's docstring.

add_directive_header(sig)

Add the directive's header, and the inheritance information if the :show-inheritance: flag set.

can_document_member(member, membername, ...)

Called to see if a member can be documented by this documenter.

filter_members(members, want_all)

Filter the list of members to always include __new__ if it has a different signature to the tuple.

sort_members(documenters, order)

Sort the typing.NamedTuple's members.
add_content(more_content, no_docstring=True)[source]

Add extra content (from docstrings, attribute docs etc.), but not the typing.NamedTuple's docstring.

Parameters:
add_directive_header(sig)[source]

Add the directive’s header, and the inheritance information if the :show-inheritance: flag set.

Parameters:

sig (str) – The NamedTuple’s signature.

classmethod can_document_member(member, membername, isattr, parent)[source]

Called to see if a member can be documented by this documenter.

Parameters:

  • member (Any) – The member being checked.

  • membername (str) – The name of the member.

  • isattr (bool)

  • parent (Any) – The parent of the member.

Return type:

bool

filter_members(members, want_all)[source]

Filter the list of members to always include __new__ if it has a different signature to the tuple.

Parameters:
Return type:

List[Tuple[str, Any, bool]]

objtype = 'namedtuple'

Type:    str

priority = 20

Type:    int

sort_members(documenters, order)[source]

Sort the typing.NamedTuple's members.

Parameters:
Return type:

List[Tuple[Documenter, bool]]

setup(app)[source]

Setup sphinx_toolbox.more_autodoc.autonamedtuple.

New in version 0.8.0.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata