API

    ███████╗██████╗ ██╗  ██╗██╗███╗   ██╗██╗  ██╗
    ██╔════╝██╔══██╗██║  ██║██║████╗  ██║╚██╗██╔╝
    ███████╗██████╔╝███████║██║██╔██╗ ██║ ╚███╔╝
    ╚════██║██╔═══╝ ██╔══██║██║██║╚██╗██║ ██╔██╗
    ███████║██║     ██║  ██║██║██║ ╚████║██╔╝ ██╗
    ╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝

 ██████╗ ██████╗ ███╗   ██╗████████╗██████╗ ██╗██████╗
██╔════╝██╔═══██╗████╗  ██║╚══██╔══╝██╔══██╗██║██╔══██╗
██║     ██║   ██║██╔██╗ ██║   ██║   ██████╔╝██║██████╔╝
██║     ██║   ██║██║╚██╗██║   ██║   ██╔══██╗██║██╔══██╗
╚██████╗╚██████╔╝██║ ╚████║   ██║   ██║  ██║██║██████╔╝
 ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═════╝

        ███████╗███╗   ██╗██╗   ██╗███╗   ███╗
        ██╔════╝████╗  ██║██║   ██║████╗ ████║
        █████╗  ██╔██╗ ██║██║   ██║██╔████╔██║
        ██╔══╝  ██║╚██╗██║██║   ██║██║╚██╔╝██║
        ███████╗██║ ╚████║╚██████╔╝██║ ╚═╝ ██║
        ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝     ╚═╝

Sphinx directive for documenting dataclass enums in tabular format, with support for enum-properties.

sphinxcontrib_enum.Formatter

alias of Callable[[Enum, str, Any], str | nodes.Node | None]

sphinxcontrib_enum.format_value(value: Any) → str[source]

The default conversion of a cell value into display text.

  • Enum members render as ClassName.MEMBER

  • Lists, tuples and sets render as comma separated values

  • Dictionaries render as comma separated key: value pairs

  • Everything else is converted with str

sphinxcontrib_enum.default_columns(enum_cls: type[Enum]) → list[str][source]

Determine the default columns for an enumeration, in order:

  1. name

  2. dataclass fields - if the enum mixes in a dataclass or its values are dataclasses or named tuples.

  3. value - only when the values are not structured (dataclass or namedtuple), so it never appears alongside dataclass fields.

  4. enum-properties properties - a special case for enum_properties.EnumProperties classes.

Duplicate column names are dropped, keeping the first occurrence.

sphinxcontrib_enum.resolve(member: Enum, column: str) → Any[source]

Fetch the raw value of a column for the given member.

Columns may be dotted attribute paths (e.g. value.red). The first attribute is looked up on the member and then, if not found, on the member’s value.

Raises:

AttributeError – If the column cannot be resolved.

sphinxcontrib_enum.member_docstrings(enum_cls: type[Enum]) → dict[str, str][source]

Find the docstrings of an enumeration’s members, keyed by member name.

Python does not give enum members their own docstrings (member.__doc__ is the class docstring), so docstrings are found the same way autodoc finds them, in order of precedence:

  1. A __doc__ attribute set explicitly on the member instance (e.g. by the enum’s __init__).

  2. A string literal immediately after the member’s assignment, or a #: comment before it, in the enum’s source code.

Members without a docstring are not included. Docstrings are dedented and stripped but otherwise returned verbatim (they are usually reStructuredText).

sphinxcontrib_enum.column_docstrings(enum_cls: type[Enum], columns: Iterable[str]) → dict[str, str][source]

Find descriptions of an enumeration’s columns, keyed by column name.

Each column is looked up on the enum’s classes (including any dataclass mixin and its bases) and then, if the member values are dataclasses or named tuples, on the value’s classes. For each class, in order of precedence:

  1. dataclasses.field(doc=...) (Python 3.14+).

  2. A string literal immediately after the attribute, or a #: comment before it, in source. This covers dataclass fields, named tuple fields and enum-properties property annotations.

  3. The docstring of a property defined on the class.

The name and value pseudo-columns and dotted column paths have no descriptions. Columns without a description are not included.

sphinxcontrib_enum.import_enum(path: str, default_module: str | None = None) → type[Enum][source]

Import an enumeration class from an import path string.

The path may separate the module from the class qualname with a : (pkg.module:Outer.Enum) or use dots throughout (pkg.module.Outer.Enum), in which case the longest importable module prefix is used. If the path cannot be resolved absolutely and default_module is given, the path is also tried relative to that module.

Parameters:

  • path – The import path of the enumeration.

  • default_module – A module to resolve the path relative to if the path cannot be resolved on its own (e.g. the current py:module).

Raises:

  • ImportError – If the path cannot be resolved.

  • TypeError – If the path resolves to something that is not an Enum class.

class sphinxcontrib_enum.EnumTableDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Render an enumeration as a table with a row for each member and a column for the name, value and each property or dataclass field.

.. enum-table:: import.path.to.Enum
    :columns: name, mass, radius, moons
    :exclude: moons
    :members: EARTH, MARS
    :exclude-members: VENUS
    :headers: mass=Mass (kg), radius=Radius (m)
    :caption: The planets.
    :name: planet-table
    :class: my-class
    :widths: auto
    :download: csv, json
    :formatter: import.path.to.formatter
    :docs: true
    :doc-column: doc
    :legend: true