{"id":5211,"library":"enum-tools","title":"Enum Tools","description":"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.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/domdfcoding/enum_tools","tags":["enum","enumeration","utilities","documentation","sphinx","developer-tools"],"install":[{"cmd":"pip install enum-tools","lang":"bash","label":"Install stable version"},{"cmd":"pip install enum-tools[sphinx]","lang":"bash","label":"Install with Sphinx extension dependencies"}],"dependencies":[{"reason":"Required for the `enum_tools.autoenum` Sphinx extension.","package":"sphinx","optional":true},{"reason":"Required for the `enum_tools.autoenum` Sphinx extension.","package":"sphinx-jinja2-compat","optional":true},{"reason":"Required for the `enum_tools.autoenum` Sphinx extension.","package":"sphinx-toolbox","optional":true}],"imports":[{"symbol":"document_enum","correct":"from enum_tools.documentation import document_enum"},{"symbol":"StrEnum","correct":"from enum_tools.custom_enums import StrEnum"},{"note":"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.","symbol":"autoenum","correct":"from enum_tools.autoenum import autoenum"}],"quickstart":{"code":"from enum import Enum, auto\nfrom enum_tools.documentation import document_enum\nfrom enum_tools.custom_enums import StrEnum\n\n@document_enum\nclass Status(Enum):\n    NEW = auto() # doc: New item status\n    IN_PROGRESS = auto() # doc: Item is being processed\n    COMPLETED = auto() # doc: Item processing finished\n\nclass Color(StrEnum):\n    RED = auto()\n    GREEN = auto()\n    BLUE = auto()\n\nprint(f\"Status.NEW name: {Status.NEW.name}, value: {Status.NEW.value}, doc: {Status.NEW.__doc__}\")\nprint(f\"Status.IN_PROGRESS name: {Status.IN_PROGRESS.name}, value: {Status.IN_PROGRESS.value}, doc: {Status.IN_PROGRESS.__doc__}\")\nprint(f\"Color.RED: {Color.RED}, type: {type(Color.RED)}\")\nprint(f\"Color.GREEN == 'GREEN': {Color.GREEN == 'GREEN'}\")","lang":"python","description":"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."},"warnings":[{"fix":"Use a single, consistent docstring format (`# doc: Comment`) for each enum member.","message":"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.","severity":"gotcha","affected_versions":"All versions with `document_enum` (0.6.0+)"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of Python's `enum` and libraries extending it."},{"fix":"Install with `pip install enum-tools[sphinx]` if you plan to use the Sphinx extension.","message":"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`.","severity":"gotcha","affected_versions":"All versions supporting `autoenum` (0.4.0+)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}