enum_tools.documentation

Core Functionality

Decorators to add docstrings to enum members from comments.

Classes:

DocumentedEnum(value)

An enum where docstrings are automatically added to members from comments starting with doc:.

Functions:

document_enum(an_enum)

Document all members of an enum by parsing a docstring from the Python source..

document_member(enum_member)

Document a member of an enum by adding a comment to the end of the line that starts with doc:.

enum DocumentedEnum(value)[source]

Bases: enum.Enum

An enum where docstrings are automatically added to members from comments starting with doc:.

Note

This class does not (yet) support the other docstring formats @document_enum does.

@document_enum(an_enum)[source]

Document all members of an enum by parsing a docstring from the Python source..

The docstring can be added in several ways:

  1. A comment at the end the line, starting with doc::

    Running = 1  # doc: The system is running.
    
  2. A comment on the previous line, starting with #:. This is the format used by Sphinx.

    #: The system is running.
    Running = 1
    
  3. A string on the line after the attribute. This can be used for multiline docstrings.

    Running = 1
    """
    The system is running.
    
    Hello World
    """
    

If more than one docstring format is found for an enum member a MultipleDocstringsWarning is emitted.

Parameters

an_enum (enum.Enum) – An Enum subclass

Returns

The same object passed as an_enum. This allows this function to be used as a decorator.

Return type

enum.Enum

Changed in version 0.8.0: Added support for other docstring formats and multiline docstrings.

document_member(enum_member)[source]

Document a member of an enum by adding a comment to the end of the line that starts with doc:.

Parameters

enum_member (Enum) – A member of an Enum subclass

Utilities

Exceptions:

MultipleDocstringsWarning(member[, docstrings])

Warning emitted when multiple docstrings are found for a single Enum member.

Functions:

get_base_indent(base_indent, all_tokens, indent)

Determine the base level of indentation (i.e.

get_dedented_line(line)

Returns the line without indentation, and the amount of indentation.

get_tokens(line)

Returns a list ot tokens generated from the given Python code.

parse_tokens(all_tokens)

Parse the tokens representing a line of code to identify Enum members and doc: comments.

get_base_indent(base_indent, all_tokens, indent)[source]

Determine the base level of indentation (i.e. one level of indentation in from the c of class).

Parameters
  • base_indent (Optional[int]) – The current base level of indentation

  • all_tokens (Sequence[Sequence])

  • indent (int) – The current level of indentation

Return type

Optional[int]

Returns

The base level of indentation

get_dedented_line(line)[source]

Returns the line without indentation, and the amount of indentation.

Parameters

line (str) – A line of Python source code

Return type

Tuple[int, str]

get_tokens(line)[source]

Returns a list ot tokens generated from the given Python code.

Parameters

line (str) – Line of Python code to tokenise.

Return type

List[Tuple]

parse_tokens(all_tokens)[source]

Parse the tokens representing a line of code to identify Enum members and doc: comments.

Parameters

all_tokens

Returns

A list of the Enum members’ names, and the docstring for them.

Warnings

exception MultipleDocstringsWarning(member, docstrings=())[source]

Bases: UserWarning

Warning emitted when multiple docstrings are found for a single Enum member.

New in version 0.8.0.

Parameters
  • member (Enum)

  • docstrings (Iterable[str]) – The list of docstrings found for the member. Default ().

__str__()[source]

Return str(self).

Return type

str

docstrings

Type:    Iterable[str]

The list of docstrings found for the member.

member

Type:    Enum

The member with multiple docstrings.