Enum Tools

0.13.0 · active · verified Mon Apr 13

Enum Tools is a Python library that expands upon Python's standard `enum` module. It provides utilities such as a Sphinx extension (`autoenum`) for improved Enum documentation, decorators (`document_enum`) to automatically add docstrings to Enum members from source code comments, and a collection of custom Enum classes (`custom_enums`) with enhanced functionality like `StrEnum`, `AutoNumberEnum`, and `OrderedEnum`. The library is currently at version 0.13.0 and maintains an active release schedule.

Warnings

gotcha When using `document_enum`, ensure that docstrings are consistent. If more than one docstring format is found for an enum member, a `MultipleDocstringsWarning` will be emitted.
Fix: Use a single, consistent docstring format (`# doc: Comment`) for each enum member.
breaking Changing the integer values of standard enum members, even those extended by `enum-tools`, can be a breaking change if those values are persisted or relied upon by external systems. This is a general Python `enum` concern.
Fix: Avoid changing enum member values in production code once they are established. If values must change, consider migrating old data or implementing compatibility layers.
gotcha The `enum_tools.autoenum` Sphinx extension has additional dependencies (`sphinx`, `sphinx-jinja2-compat`, `sphinx-toolbox`) that are not installed by default with `pip install enum-tools`.
Fix: Install with `pip install enum-tools[sphinx]` if you plan to use the Sphinx extension.

Install

pip install enum-tools Install stable version
pip install enum-tools[sphinx] Install with Sphinx extension dependencies

Imports

document_enum

from enum_tools.documentation import document_enum

StrEnum

from enum_tools.custom_enums import StrEnum

autoenum
```
from enum_tools.autoenum import autoenum
```
This is a Sphinx extension directive, not a Python symbol for direct import into application code. Import path refers to its use in Sphinx `conf.py` extensions list.

Quickstart

This quickstart demonstrates the `document_enum` decorator to add docstrings from line comments and the `StrEnum` from `custom_enums` which allows enum members to behave like strings.

from enum import Enum, auto
from enum_tools.documentation import document_enum
from enum_tools.custom_enums import StrEnum

@document_enum
class Status(Enum):
    NEW = auto() # doc: New item status
    IN_PROGRESS = auto() # doc: Item is being processed
    COMPLETED = auto() # doc: Item processing finished

class Color(StrEnum):
    RED = auto()
    GREEN = auto()
    BLUE = auto()

print(f"Status.NEW name: {Status.NEW.name}, value: {Status.NEW.value}, doc: {Status.NEW.__doc__}")
print(f"Status.IN_PROGRESS name: {Status.IN_PROGRESS.name}, value: {Status.IN_PROGRESS.value}, doc: {Status.IN_PROGRESS.__doc__}")
print(f"Color.RED: {Color.RED}, type: {type(Color.RED)}")
print(f"Color.GREEN == 'GREEN': {Color.GREEN == 'GREEN'}")

view raw JSON →