8.13. enum — 枚举类型支持

3.4 版新加入.

源代码： Lib/enum.py

---

枚举是一组符号名称（枚举成员）的集合，枚举成员应该是唯一的、不可变的。在枚举中，可以对成员进行恒等比较，并且枚举本身是可迭代的。

8.13.1. 模块内容

This module defines two enumeration classes that can be used to define unique sets of names and values: Enum and IntEnum. It also defines one decorator, unique().

class enum.Enum

用于创建枚举型常数的基类。 请参阅 Functional API 小节了解另一种替代性的构建语法。

class enum.IntEnum

用于创建同时也是 int 的子类的枚举型常数的基类。

enum.unique()

此 Enum 类装饰器可确保只将一个名称绑定到任意一个值。

8.13.2. 创建一个 Enum

枚举是使用 class 语法来创建的，这使得它们易于读写。 另一种替代创建方法的描述见 Functional API。 要定义一个枚举，可以对 Enum 进行如下的子类化:

>>> from enum import Enum
>>> class Color(Enum):
...     red = 1
...     green = 2
...     blue = 3
...

備註

命名法

• 类 Color 是一个 enumeration (或称 enum)
• The attributes Color.red, Color.green, etc., are enumeration members (or enum members).
• The enum members have names and values (the name of Color.red is red, the value of Color.blue is 3, etc.)

備註

虽然我们使用 class 语法来创建 Enum，但 Enum 并不是普通的 Python 类。 更多细节请参阅 How are Enums different?。

枚举成员具有适合人类阅读的表示形式:

>>> print(Color.red)
Color.red

…而它们的 repr 包含更多信息:

>>> print(repr(Color.red))
<Color.red: 1>

一个枚举成员的 type 就是它所从属的枚举:

>>> type(Color.red)
<enum 'Color'>
>>> isinstance(Color.green, Color)
True
>>>

Enum 的成员还有一个包含其条目名称的特征属性:

>>> print(Color.red.name)
red

枚举支持按照定义顺序进行迭代:

>>> class Shake(Enum):
...     vanilla = 7
...     chocolate = 4
...     cookies = 9
...     mint = 3
...
>>> for shake in Shake:
...     print(shake)
...
Shake.vanilla
Shake.chocolate
Shake.cookies
Shake.mint

枚举成员是可哈希的，因此它们可在字典和集合中可用:

>>> apples = {}
>>> apples[Color.red] = 'red delicious'
>>> apples[Color.green] = 'granny smith'
>>> apples == {Color.red: 'red delicious', Color.green: 'granny smith'}
True

8.13.3. 对枚举成员及其属性的程序化访问

Sometimes it’s useful to access members in enumerations programmatically (i.e. situations where Color.red won’t do because the exact color is not known at program-writing time). Enum allows such access:

>>> Color(1)
<Color.red: 1>
>>> Color(3)
<Color.blue: 3>

如果你希望通过 name 来访问枚举成员，可使用条目访问:

>>> Color['red']
<Color.red: 1>
>>> Color['green']
<Color.green: 2>

如果你有一个枚举成员并且需要它的 name 或 value:

>>> member = Color.red
>>> member.name
'red'
>>> member.value
1

8.13.4. 复制枚举成员和值

不允许有同名的枚举成员:

>>> class Shape(Enum):
...     square = 2
...     square = 3
...
Traceback (most recent call last):
...
TypeError: Attempted to reuse key: 'square'

但是，允许两个枚举成员有相同的值。 假定两个成员 A 和 B 有相同的值（且 A 先被定义），则 B 就是 A 的一个别名。 按值查找 A 和 B 的值将返回 A。 按名称查找 B 也将返回 A:

>>> class Shape(Enum):
...     square = 2
...     diamond = 1
...     circle = 3
...     alias_for_square = 2
...
>>> Shape.square
<Shape.square: 2>
>>> Shape.alias_for_square
<Shape.square: 2>
>>> Shape(2)
<Shape.square: 2>

備註

试图创建具有与某个已定义的属性（另一个成员或方法等）相同名称的成员或者试图创建具有相同名称的属性也是不允许的。

8.13.5. 确保唯一的枚举值

默认情况下，枚举允许有多个名称作为某个相同值的别名。 如果不想要这样的行为，可以使用以下装饰器来确保每个值在枚举中只被使用一次:

@enum.unique

专用于枚举的 class 装饰器。 它会搜索一个枚举的 __members__ 并收集所找到的任何别名；只要找到任何别名就会引发 ValueError 并附带相关细节信息:

>>> from enum import Enum, unique
>>> @unique
... class Mistake(Enum):
...     one = 1
...     two = 2
...     three = 3
...     four = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: four -> three

8.13.6. 迭代

对枚举成员的迭代不会给出别名:

>>> list(Shape)
[<Shape.square: 2>, <Shape.diamond: 1>, <Shape.circle: 3>]

特殊属性 __members__ 是一个将名称映射到成员的有序字典。 它包含枚举中定义的所有名称，包括别名:

>>> for name, member in Shape.__members__.items():
...     name, member
...
('square', <Shape.square: 2>)
('diamond', <Shape.diamond: 1>)
('circle', <Shape.circle: 3>)
('alias_for_square', <Shape.square: 2>)

__members__ 属性可被用于对枚举成员进行详细的程序化访问。 例如，找出所有别名:

>>> [name for name, member in Shape.__members__.items() if member.name != name]
['alias_for_square']

8.13.7. 比较运算

枚举成员是按标识号进行比较的:

>>> Color.red is Color.red
True
>>> Color.red is Color.blue
False
>>> Color.red is not Color.blue
True

枚举值之间的排序比较 不被 支持。 Enum 成员不属于整数 (另请参阅下文的 IntEnum):

>>> Color.red < Color.blue
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unorderable types: Color() < Color()

相等比较的定义如下:

>>> Color.blue == Color.red
False
>>> Color.blue != Color.red
True
>>> Color.blue == Color.blue
True

与非枚举值的比较将总是不相等（同样地，IntEnum 被显式设计成不同的行为，参见下文）:

>>> Color.blue == 2
False

8.13.8. 允许的枚举成员和属性

以上示例使用整数作为枚举值。 使用整数相当简洁方便（并由 Functional API 默认提供），但并不强制要求使用。 在大部分用例中，开发者都关心枚举的实际值是什么。 但如果值 确实 重要，则枚举可以使用任意的值。

枚举属于 Python 的类，并可具有普通方法和特殊方法。 如果我们有这样一个枚举:

>>> class Mood(Enum):
...     funky = 1
...     happy = 3
...
...     def describe(self):
...         # self is the member here
...         return self.name, self.value
...
...     def __str__(self):
...         return 'my custom str! {0}'.format(self.value)
...
...     @classmethod
...     def favorite_mood(cls):
...         # cls here is the enumeration
...         return cls.happy
...

那么:

>>> Mood.favorite_mood()
<Mood.happy: 3>
>>> Mood.happy.describe()
('happy', 3)
>>> str(Mood.funky)
'my custom str! 1'

The rules for what is allowed are as follows: names that start and end with a single underscore are reserved by enum and cannot be used; all other attributes defined within an enumeration will become members of this enumeration, with the exception of special methods (__str__(), __add__(), etc.) and descriptors (methods are also descriptors).

注意：如果你的枚举定义了 __new__() 和/或 __init__() 那么指定给枚举成员的任何值都会被传入这些方法。 请参阅示例 Planet。

8.13.9. Restricted subclassing of enumerations

Subclassing an enumeration is allowed only if the enumeration does not define any members. So this is forbidden:

>>> class MoreColor(Color):
...     pink = 17
...
Traceback (most recent call last):
...
TypeError: Cannot extend enumerations

但是允许这样的写法:

>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     happy = 1
...     sad = 2
...

允许子类化定义了成员的枚举将会导致违反类型与实例的某些重要的不可变规则。 在另一方面，允许在一组枚举之间共享某些通用行为也是有意义的。 （请参阅示例 OrderedEnum 。）

8.13.10. 封存

枚举可以被封存与解封:

>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.tomato is loads(dumps(Fruit.tomato))
True

封存的常规限制同样适用：可封存枚举必须在模块的最高层级中定义，因为解封操作要求它们可以从该模块导入。

備註

使用 pickle 协议版本 4 可以方便地封存嵌套在其他类中的枚举。

通过在枚举类中定义 __reduce_ex__() 可以对 Enum 成员的封存/解封方式进行修改。

8.13.11. 可用 API

Enum 类属于可调用对象，它提供了以下可用的 API:

>>> Animal = Enum('Animal', 'ant bee cat dog')
>>> Animal
<enum 'Animal'>
>>> Animal.ant
<Animal.ant: 1>
>>> Animal.ant.value
1
>>> list(Animal)
[<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>]

该 API 的主义类似于 namedtuple。 调用 Enum 的第一个参数是枚举的名称。

第二个参数是枚举成员名称的 来源。 它可以是一个用空格分隔的名称字符串、名称序列、键/值对 2 元组的序列，或者名称到值的映射（例如字典）。 最后两种选项使得可以为枚举任意赋值；其他选项会自动以从 1 开始递增的整数赋值（使用 start 形参可指定不同的起始值）。 返回值是一个派生自 Enum 的新类。 换句话说，以上对 Animal 的赋值就等价于:

>>> class Animal(Enum):
...     ant = 1
...     bee = 2
...     cat = 3
...     dog = 4
...

默认以 1 而以 0 作为起始数值的原因在于 0 的布尔值为 False，但所有枚举成员都应被求值为 True。

封存通过功能性 API 创建的枚举可能会有点麻烦，因为要使用帧堆栈的实现细节来尝试并找出枚举是在哪个模块中创建的（例如，当你使用不同模块的工具函数时可能会失败，在 IronPython 或 Jython 上也可能会没有效果）。 解决办法是显式地指定模块名称，如下所示:

>>> Animal = Enum('Animal', 'ant bee cat dog', module=__name__)

警告

如果未提供 module，且 Enum 无法确定是哪个模块，新的 Enum 成员将不可被解封；为了让错误尽量靠近源头，封存将被禁用。

新的 pickle 协议版本 4 在某些情况下同样依赖于 __qualname__ 被设为特定位置以便 pickle 能够找到相应的类。 例如，类是否存在于全局作用域的 SomeData 类中:

>>> Animal = Enum('Animal', 'ant bee cat dog', qualname='SomeData.Animal')

完整的签名为:

Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)

值:

将被新 Enum 类将记录为其名称的数据。

names:

Enum 的成员。 这可以是一个空格或逗号分隔的字符串 (起始值将为 1，除非另行指定):

'red green blue' | 'red,green,blue' | 'red, green, blue'

或是一个名称的迭代器:

['red', 'green', 'blue']

或是一个 (名称, 值) 对的迭代器:

[('cyan', 4), ('magenta', 5), ('yellow', 6)]

或是一个映射:

{'chartreuse': 7, 'sea_green': 11, 'rosemary': 42}

module:

新 Enum 类所在模块的名称。

qualname:

新 Enum 类在模块中的具体位置。

type:

要加入新 Enum 类的类型。

start:

当只传入名称时要使用的起始数值。

3.5 版更變: 增加了 start 形参。

8.13.12. 派生的枚举

8.13.12.1. IntEnum

A variation of Enum is provided which is also a subclass of int. Members of an IntEnum can be compared to integers; by extension, integer enumerations of different types can also be compared to each other:

>>> from enum import IntEnum
>>> class Shape(IntEnum):
...     circle = 1
...     square = 2
...
>>> class Request(IntEnum):
...     post = 1
...     get = 2
...
>>> Shape == 1
False
>>> Shape.circle == 1
True
>>> Shape.circle == Request.post
True

不过，它们仍然不可与标准 Enum 枚举进行比较:

>>> class Shape(IntEnum):
...     circle = 1
...     square = 2
...
>>> class Color(Enum):
...     red = 1
...     green = 2
...
>>> Shape.circle == Color.red
False

IntEnum 值在其他方面的行为都如你预期的一样类似于整数:

>>> int(Shape.circle)
1
>>> ['a', 'b', 'c'][Shape.circle]
'b'
>>> [i for i in range(Shape.square)]
[0, 1]

For the vast majority of code, Enum is strongly recommended, since IntEnum breaks some semantic promises of an enumeration (by being comparable to integers, and thus by transitivity to other unrelated enumerations). It should be used only in special cases where there’s no other choice; for example, when integer constants are replaced with enumerations and backwards compatibility is required with code that still expects integers.

8.13.12.2. 其他事项

虽然 IntEnum 是 enum 模块的一部分，但要独立实现也应该相当容易:

class IntEnum(int, Enum):
    pass

这里演示了如何定义类似的派生枚举；例如一个混合了 str 而不是 int 的 StrEnum。

几条规则：

1. 当子类化 Enum 时，在基类序列中的混合类型必须出现于 Enum 本身之前，如以上 IntEnum 的例子所示。
2. 虽然 Enum 可以拥有任意类型的成员，不过一旦你混合了附加类型，则所有成员必须为相应类型的值，如在上面的例子中即为 int。 此限制不适用于仅添加方法而未指定另一数据类型如 int 或 str 的混合类。
3. 当混合了另一数据类型时，value 属性会 不同于 枚举成员自身，但它们仍保持等价且比较结果也相等。
4. %-style formatting: %s 和 %r 会分别调用 Enum 类的 __str__() 和 __repr__()；其他代码 (例如表示 IntEnum 的 %i 或 %h) 会将枚举成员视为对应的混合类型。
5. str.format() (or format()) will use the mixed-in type’s __format__(). If the Enum class’s str() or repr() is desired, use the !s or !r format codes.

8.13.13. 有趣的示例

While Enum and IntEnum are expected to cover the majority of use-cases, they cannot cover them all. Here are recipes for some different types of enumerations that can be used directly, or as examples for creating one’s own.

8.13.13.1. AutoNumber

Avoids having to specify the value for each enumeration member:

>>> class AutoNumber(Enum):
...     def __new__(cls):
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...
>>> class Color(AutoNumber):
...     red = ()
...     green = ()
...     blue = ()
...
>>> Color.green.value == 2
True

備註

如果定义了 __new__() 则它会在创建 Enum 成员期间被使用；随后它将被 Enum 的 __new__() 所替换，该方法会在类创建后被用来查找现有成员。

8.13.13.2. OrderedEnum

一个有序枚举，它不是基于 IntEnum，因此保持了正常的 Enum 不变特性（例如不可与其他枚举进行比较）:

>>> class OrderedEnum(Enum):
...     def __ge__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value >= other.value
...         return NotImplemented
...     def __gt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value > other.value
...         return NotImplemented
...     def __le__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value <= other.value
...         return NotImplemented
...     def __lt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value < other.value
...         return NotImplemented
...
>>> class Grade(OrderedEnum):
...     A = 5
...     B = 4
...     C = 3
...     D = 2
...     F = 1
...
>>> Grade.C < Grade.A
True

8.13.13.3. DuplicateFreeEnum

如果发现重复的成员名称则将引发错误而不是创建别名:

>>> class DuplicateFreeEnum(Enum):
...     def __init__(self, *args):
...         cls = self.__class__
...         if any(self.value == e.value for e in cls):
...             a = self.name
...             e = cls(self.value).name
...             raise ValueError(
...                 "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
...                 % (a, e))
...
>>> class Color(DuplicateFreeEnum):
...     red = 1
...     green = 2
...     blue = 3
...     grene = 2
...
Traceback (most recent call last):
...
ValueError: aliases not allowed in DuplicateFreeEnum:  'grene' --> 'green'

備註

这个例子适用于子类化 Enum 来添加或改变禁用别名以及其他行为。 如果需要的改变只是禁用别名，也可以选择使用 unique() 装饰器。

8.13.13.4. Planet

如果定义了 __new__() 或 __init__() 则枚举成员的值将被传给这些方法:

>>> class Planet(Enum):
...     MERCURY = (3.303e+23, 2.4397e6)
...     VENUS   = (4.869e+24, 6.0518e6)
...     EARTH   = (5.976e+24, 6.37814e6)
...     MARS    = (6.421e+23, 3.3972e6)
...     JUPITER = (1.9e+27,   7.1492e7)
...     SATURN  = (5.688e+26, 6.0268e7)
...     URANUS  = (8.686e+25, 2.5559e7)
...     NEPTUNE = (1.024e+26, 2.4746e7)
...     def __init__(self, mass, radius):
...         self.mass = mass       # in kilograms
...         self.radius = radius   # in meters
...     @property
...     def surface_gravity(self):
...         # universal gravitational constant  (m3 kg-1 s-2)
...         G = 6.67300E-11
...         return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129

8.13.14. 各种枚举有何区别？

枚举具有自定义的元类，它会影响所派生枚举类及其实例（成员）的各个方面。

8.13.14.1. 枚举类

The EnumMeta metaclass is responsible for providing the __contains__(), __dir__(), __iter__() and other methods that allow one to do things with an Enum class that fail on a typical class, such as list(Color) or some_var in Color. EnumMeta is responsible for ensuring that various other methods on the final Enum class are correct (such as __new__(), __getnewargs__(), __str__() and __repr__()).

8.13.14.2. 枚举成员（即实例）

有关枚举成员最有趣的特点是它们都是单例对象。 EnumMeta 会在创建 Enum 类本身时将它们全部创建完成，然后准备好一个自定义的 __new__()，通过只返回现有的成员实例来确保不会再实例化新的对象。

8.13.14.3. 细节要点

Enum members are instances of an Enum class, and even though they are accessible as EnumClass.member, they should not be accessed directly from the member as that lookup may fail or, worse, return something besides the Enum member you looking for:

>>> class FieldTypes(Enum):
...     name = 0
...     value = 1
...     size = 2
...
>>> FieldTypes.value.size
<FieldTypes.size: 2>
>>> FieldTypes.size.value
2

3.5 版更變.

The __members__ attribute is only available on the class.

如果你为你的 Enum 子类添加了额外的方法，如同上述的 Planet 类一样，这些方法将在对成员执行 dir() 时显示出来，但对类执行时则不会显示:

>>> dir(Planet)
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
>>> dir(Planet.EARTH)
['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']

The __new__() method will only be used for the creation of the Enum members – after that it is replaced. Any custom __new__() method must create the object and set the _value_ attribute appropriately.

If you wish to change how Enum members are looked up you should either write a helper function or a classmethod() for the Enum subclass.