如何正确记录 python 枚举元素？ [复制]答案

【问题标题】：How do I properly document python enum elements? [duplicate]如何正确记录 python 枚举元素？ [复制]
【发布时间】：2018-08-28 16:47:33
【问题描述】：

我知道我可以像添加任何其他类一样将 Python 文档字符串添加到枚举类型。但是如何将文档添加到该类型的元素中？

据我所知，有三种可能：

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

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

但它们都没有真正始终如一地工作。如果我在任何变体中调用print(inspect.getdoc(MyEnum.a))，则会返回MyEnum 类型的文档字符串（“这是我的枚举类型”）。 Pycharm 可以在其快速文档预览中显示变体 3，但包含引号和超出列换行的较长 cmets 将无法正确显示。

对于如何记录 Python 枚举元素是否有首选方式或约定？

【问题讨论】：

您应该知道，三重引号字符串仍然是字符串，并且您的值后面的逗号导致它们被评估为元组。你的MyEnum.a 的值是(0,)，而MyEnum.c 的值是(2, ' variant 3 ')！
哇，谢谢帕特里克，我什至没有想到这一点，尽管现在你指出了这一点很明显。
inspect.getdoc() 返回的 is 是您的 MyEnum 类的文档字符串，因此由于它们在 Python 中的处理方式是正确的。你如何记录价值观就是你想要做的——所以没有“正确”的方法来做。
但是我不想要类型的文档字符串，我想要元素的文档字符串。
为什么不以自我记录的方式命名枚举变量本身，例如将a 替换为VARIANT_A。

标签： python python-3.x enums documentation

【解决方案1】：

如果值本身不重要，请参阅How do I put docstrings on Enums?。如果值很重要，您可以自定义该答案或使用 aenum¹ 库：

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'

导致：

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

但是，我不知道哪些 IDE 支持使用 Enum 成员文档字符串。

¹ 披露：我是Python stdlib Enum、enum34 backport 和Advanced Enumeration (aenum) 库的作者。

【讨论】：

谢谢伊桑！并感谢您标记副本。没有找到问题，当我提出问题时，它肯定没有出现在建议中。
@thrau：不用担心，很乐意提供帮助。
如果我已经定义了自定义 init 函数，这将如何工作？
将doc=None 作为__init__ 的最后一个参数，然后包含一个文档作为每个成员声明的最后一部分。答案中的链接有一个例子。