more_autodoc.autotypeddict

A Sphinx directive for documenting TypedDicts in Python.

Only supports typing_extensions's TypedDict until python/typing#700 is implemented in CPython.

New in version 0.5.0.

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

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

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

Changed in version 0.6.0: Moved from sphinx_toolbox.autotypeddict.

Usage

.. autotypeddict::

Directive to automatically document a typing.TypedDict.

The output is based on the autoclass directive, but with a few differences:

  • Private and Special members are always excluded.

  • Undocumented members are always included.

  • The default sort order is bysource.

The following options are available:

:noindex: (flag)

Do not generate index entries for the documented object (and all autodocumented members).

:alphabetical: (flag)

Sort the keys alphabetically. By default the keys are listed in the order they were defined.

:show-inheritance: (flag)

Inserts a list of base classes just below the TypedDict’s signature.

See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html for further information.

:typeddict:

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

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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
# Examples from
# https://www.python.org/dev/peps/pep-0589/#totality
# https://github.com/python/typing/pull/700
"""
Demo of ``.. autotypeddict::``
"""

# 3rd party
from typing_extensions import TypedDict

__all__ = ["Movie", "Animal", "OldStyleAnimal", "Cat", "Bird", "AquaticBird"]


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

    #: The name of the movie.
    name: str

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

    based_on: str


class _Animal(TypedDict):
    """
    Keys required by all animals.
    """

    #: The name of the animal
    name: str


class Animal(_Animal, total=False):
    """
    Optional keys common to all animals.
    """

    #: The animal's voice.
    voice: str


#: Old style TypedDict for Python 2 and where keys aren't valid Python identifiers.
OldStyleAnimal = TypedDict(
        "OldStyleAnimal", {
                "animal-name": str,
                "animal-voice": str,
                }, total=False
        )


class Cat(Animal):
    """
    A cat.
    """

    #: The colour of the cat's fur.
    fur_color: str


class Bird(Animal):
    """
    A bird.
    """

    #: The size of the bird's egg, in mm.
    egg_size: float


class AquaticBird(Bird):

    #: The bird's habitat (e.g. lake, sea)
    habitat: float

.. automodule:: autotypeddict_demo
    :no-autosummary:
    :exclude-members: Movie,AquaticBird,OldStyleAnimal

.. autotypeddict:: autotypeddict_demo.Movie

This function takes a single argument, the :typeddict:`~.Movie` to watch.

Demo of .. autotypeddict::

typeddict Animal[source]

Bases: dict

Optional keys common to all animals.

Required Keys
  • name (str) – The name of the animal

Optional Keys
  • voice (str) – The animal’s voice.

typeddict Bird[source]

Bases: dict

A bird.

Required Keys
  • egg_size (float) – The size of the bird’s egg, in mm.

  • name (str) – The name of the animal

Optional Keys
  • voice (str) – The animal’s voice.

typeddict Cat[source]

Bases: dict

A cat.

Required Keys
  • fur_color (str) – The colour of the cat’s fur.

  • name (str) – The name of the animal

Optional Keys
  • voice (str) – The animal’s voice.

typeddict Movie[source]

Bases: dict

Represents a movie.

Required Keys
  • name (str) – The name of the animal

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

  • based_on (str)

This function takes a single argument, the Movie to watch.

API Reference

Classes:

TypedDictDocumenter(*args)

Sphinx autodoc Documenter for documenting typing.TypedDicts.

Functions:

setup(app)

Setup sphinx_toolbox.more_autodoc.autotypeddict.

class TypedDictDocumenter(*args)[source]

Bases: ClassDocumenter

Sphinx autodoc Documenter for documenting typing.TypedDicts.

Methods:

add_content(more_content[, no_docstring])

Add the autodocumenter content.

can_document_member(member, membername, …)

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

document_keys(keys, types, docstrings)

Document keys in a typing.TypedDict.

document_members([all_members])

Generate reST for member documentation.

filter_members(members, want_all)

Filter the given member list.

format_signature(**kwargs)

Typed Dicts do not have a signature.

sort_members(documenters, order)

Sort the TypedDict’s members.

add_content(more_content, no_docstring=False)[source]

Add the autodocumenter content.

Parameters
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

document_keys(keys, types, docstrings)[source]

Document keys in a typing.TypedDict.

Parameters
  • keys (List[str]) – List of key names to document.

  • types (Dict[str, Type]) – Mapping of key names to types.

  • docstrings (Dict[str, List[str]]) – Mapping of key names to docstrings.

document_members(all_members=False)[source]

Generate reST for member documentation. All members are always documented.

filter_members(members, want_all)[source]

Filter the given member list.

Parameters
Return type

List[Tuple[str, Any, bool]]

format_signature(**kwargs)[source]

Typed Dicts do not have a signature.

Return type

str

sort_members(documenters, order)[source]

Sort the TypedDict’s members.

Parameters
Return type

List[Tuple[Documenter, bool]]

setup(app)[source]

Setup sphinx_toolbox.more_autodoc.autotypeddict.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata