enum-tools

library0.13.0pypypi✓ verified 23d ago

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.

serialization

pip install enum-tools

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · ENUM-TOOLS

enum-tools

serializationpythonv0.13.0

Install

5.1s avg

Import

377ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.13.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.384s · 26.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.1s · import 0.369s · 27MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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'}")

Debug

Known issues

gotchaWhen 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.

affects: All versions with `document_enum` (0.6.0+)

breakingChanging 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.

affects: All versions of Python's `enum` and libraries extending it.

gotchaThe `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.

affects: All versions supporting `autoenum` (0.4.0+)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'enum_tools'

The 'enum-tools' library is not installed in the current Python environment.

fix

pip install enum-tools

ImportError: cannot import name 'StrEnum' from 'enum'

Users are attempting to import 'StrEnum' from Python's standard 'enum' module, which is only available in Python 3.11+. The 'enum-tools' library provides its own 'StrEnum' for compatibility across various Python versions.

fix

from enum_tools.custom_enums import StrEnum

Extension error: Could not import extension enum_tools.autoenum (exception: No module named 'sphinx_toolbox')

The 'enum_tools.autoenum' Sphinx extension requires additional dependencies like 'sphinx-toolbox' that are not installed by default with a basic 'enum-tools' installation.

fix

pip install enum-tools[sphinx]

MultipleDocstringsWarning: Multiple docstring formats found for enum member 'MEMBER_NAME'

When using the `@document_enum` decorator, the same enum member has its docstring defined using more than one supported format (e.g., an end-of-line comment and a string literal after assignment), leading to ambiguity.

fix

Ensure each enum member has its docstring defined using only one consistent format, for example, a single '# doc: Your docstring' comment per member.

Upgrade

Version history

0.13.0latest on PyPI · released Apr 17, 2025

Audit

Dependencies

sphinxoptionalRequired for the `enum_tools.autoenum` Sphinx extension.

sphinx-jinja2-compatoptionalRequired for the `enum_tools.autoenum` Sphinx extension.

sphinx-toolboxoptionalRequired for the `enum_tools.autoenum` Sphinx extension.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/domdfcoding/enum_tools ↗

packagehttps://pypi.org/project/enum-tools/ ↗

homepagehttps://enum-tools.readthedocs.io ↗

docshttps://enum-tools.readthedocs.io/en/latest ↗