How do I properly document python enum elements?

user_804840 0
Viewed 11552

I understand that I can add a Python docstring to an enum type as I would any other class. But how do I add documentation to an element of that type?

As far as I can see there are three possibilities:

class MyEnum(Enum):
    """
    This is my enum type.
    """

    """
    Variant 1
    """
    a = 0,  
    b = 1, # variant 2
    c = 2, """ variant 3 """

But none of them really work consistently. If I call print(inspect.getdoc(MyEnum.a)) in any of the variants, the docstring of the MyEnum type is returned ('This is my enum type'). Pycharm can show variant 3 in its Quick Documentation preview, but includes the quotes and longer comments that exceed the column wrap will not be shown correctly.

Is there a preferred way or convention on how to document Python enum elements?

documentation enums python-3.x python
1 Answers

If the values themselves are not important, see How do I put docstrings on Enums?. If the values are important you can either customize that answer or use the aenum1 library:

from aenum import Enum

class MyEnum(Enum):
    _init_ = 'value __doc__'
    a = 0, 'docstring for a'
    b = 1, 'another for b'
    c = 2, 'and one for c as well'

which results in:

>>> MyEnum.b.value
1
>>> MyEnum.b.__doc__
'another for b'

However, I do not know which, if any, IDEs support using Enum member doc strings.

1 Disclosure: I am the author of the Python stdlib Enum, the enum34 backport, and the Advanced Enumeration (aenum) library.

user_2088800
Related