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.

:typeddict:

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

See also

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

Examples:

# 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

Bases: TypedDict

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

Bases: Animal

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

Bases: Animal

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

Bases: TypedDict

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)

Bases: ClassDocumenter

Sphinx autodoc Documenter for documenting typing.TypedDicts.

Methods:

add_content(more_content[, no_docstring])	Add the autodocumenter content.
add_directive_header(sig)	Add the directive's header and options to the generated 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)

Add the autodocumenter content.

Parameters:

• more_content (Any)

• no_docstring (bool) – Default False.

add_directive_header(sig)

Add the directive’s header and options to the generated content.

Parameters:

sig (str) – The function/class signature.

classmethod can_document_member(member, membername, isattr, parent)

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)

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)

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

filter_members(members, want_all)

Filter the given member list.

Parameters:

• members (List[Tuple[str, Any]])

• want_all (bool)

Return type:

List[Tuple[str, Any, bool]]

format_signature(**kwargs)

Typed Dicts do not have a signature.

Return type:

str

objtype = 'typeddict'

Type:    str

priority = 20

Type:    int

sort_members(documenters, order)

Sort the TypedDict’s members.

Parameters:

• documenters (List[Tuple[Documenter, bool]])

• order (str)

Return type:

List[Tuple[Documenter, bool]]

setup(app)

Setup sphinx_toolbox.more_autodoc.autotypeddict.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata