如何在字典中的枚举中添加文档字符串

Question

我在字典中使用枚举：

Parameters = {
    ONE: Enum(
        value = 'Options',
        names = [
            ('SEPARATE', 0b1),
            ('SEQUENTIAL', 0b0)
        ]
    )
}

这种风格的作品非常符合我的需要。

但是，当以不同的方式使用枚举时，我可以添加文档字符串：

class ONE(Enum):
    SEPERATE = 0b1
    """The registers associated with each port are separated into different banks"""
    SEQUENTIAL = 0b0
    """The registers are in the same bank (addresses are sequential)"""

那我的问题是：

如何在第一个示例中使用字典中的枚举时添加文档字符串？

更新测试枚举

Parameters = {
    'ONE': Enum(
        value = 'ONE',
        names = [
            ('SEPARATE', 0b1),
            ('SEQUENTIAL', 0b0)
        ]
    )
}

print(Parameters['ONE'].SEPARATE)

按预期工作

然后尝试扩展 Enum()

class NewEnum(Enum):
    def __init__(self, **kw):
        super(NewEnum, self).__init__(**kw)


Parameters = {
    'ONE': NewEnum(
        value = 'ONE',
        names = [
            ('SEPARATE', 0b1),
            ('SEQUENTIAL', 0b0)
        ]
    )
}

无效。

Answer 1

你不是在设置文档字符串，你是在写评论：

>>> from enum import Enum
>>> class ONE(Enum):
...     SEPERATE = 0b1
...     """The registers associated with each port are separated into different banks"""
...     SEQUENTIAL = 0b0
...     """The registers are in the same bank (addresses are sequential)"""
... 
>>> ONE.SEPERATE.__doc__
'An enumeration.'

所以，简单的方法就是添加真实评论：

Parameters = {
    ONE: Enum(
        value = 'Options',
        names = [
            ('SEPARATE', 0b1),   # The registers associated with each port are separated into different banks
            ('SEQUENTIAL', 0b0)  # The registers are in the same bank (addresses are sequential)
        ]
    )
}

实际上使用 type() 格式添加 __doc__ 可能有点困难 -- 我会研究一下。

好的，这是自定义枚举，EnumWithDocstring:

class EnumWithDocstring(Enum):
    #
    def __new__(cls, value, doc=None):
        member = object.__new__(cls)
        member._value_ = value
        member.__doc__ = doc
        return member

新枚举没有什么特别之处；棘手的部分是意识到传递给 Enum 构造函数的所有值都必须是 tuple，所以你的 Parameters 看起来像：

Parameters = {
    'ONE': EnumWithDocstring(
        value = 'Options',
        names = [
            ('SEPARATE', (0b1, 'test docstring')),
            ('SEQUENTIAL', 0b0)
        ]
    )
}

SEPARATE 有文档字符串，但 SEQUENTIAL 没有。

披露：我是 Python stdlib Enum, the enum34 backport, and the Advanced Enumeration (aenum) 库的作者。

如何在字典中的枚举中添加文档字符串

How to add Docstrings in Enum inside Dictionaries

python

documentation

enums