Add docstrings to Python Enum members
Recently I learned that Python Enum members don't "support" docstrings natively which is quite annoying.
I had to manage a list of feature flags and provide a good description for each of them through FastAPI:
from enum import StrEnum, auto
class FeatureFlag(StrEnum):
"""Holds a list of available feature toggles"""
ENABLE_CHAT_GPT = auto()
"""Requested by a few customers to enable Chat GPT within the app"""
DARK_MODE = auto()
"""Fixes your color schema"""
Python Enum member docstring limitation
To my surprise when I extracted each member's __doc__ (which should contain the docstring) I got the FeatureFlag class docstring instead.
print(FeatureFlag.ENABLE_CHAT_GPT.__doc__) # ❌ output: Holds a list of available feature toggles
print(FeatureFlag.DARK_MODE.__doc__) # ❌ output: Holds a list of available feature togglesThis is definitively not what we expect. We want the enum member's docstring.
How to add docstring to enum members?
The best solution I could come up with is to override the __new__ method and require members to take two string values:
from enum import StrEnum, auto
import typing as t
class FeatureFlag(StrEnum):
"""Holds a list of available feature toggles"""
# 👇 Magic method needed to enforce members to take docstrings
def __new__(cls, value: str, docstr: str) -> t.Self:
member = str.__new__(cls, value)
member._value_ = value
member.__doc__ = docstr.strip() # 🪄 Magic
return member
ENABLE_CHAT_GPT = (auto(), """Requested by a few customers to enable Chat GPT within the app""")
DARK_MODE = (auto(), """Fixes your color schema""")
print(FeatureFlag.ENABLE_CHAT_GPT.__doc__) # ✅ output: Requested by a few customers to enable Chat GPT within the app
print(FeatureFlag.DARK_MODE.__doc__) # ✅ output: Fixes your color schemaThis might not be the cleanest, but it works and it's simple to maintain.
Now I can iterate over the enum members and take each "docstring":
flags = [dict(key=flag.value, description=flag.__doc__) for flag in FeatureFlags]
print(flags)
# outputs:
# [
# {'key': 'enable_chat_gpt', 'description': 'Requested by a few customers to enable Chat GPT within the app'},
# {'key': 'dark_mode', 'description': 'Fixes your color schema'}
#]