枚举 HOWTO

一个 Enum 是一组绑定到唯一值的符号名称。它们类似于全局变量，但它们提供了更实用的 repr()、分组、类型安全以及其他一些功能。

当您有一个可以取有限选择值的变量时，它们最有用。例如，一周中的几天

>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7

或者可能是 RGB 原色

>>> from enum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

如您所见，创建 Enum 就像编写一个从 Enum 本身继承的类一样简单。

注意

Enum 成员的大小写

由于 Enum 用于表示常量，并且为了帮助避免混合类方法/属性和枚举名称之间的名称冲突问题，我们强烈建议对成员使用 UPPER_CASE 名称，并且将在我们的示例中使用这种风格。

根据枚举的性质，成员的值可能重要也可能不重要，但无论哪种情况，都可以使用该值来获取相应的成员

>>> Weekday(3)
<Weekday.WEDNESDAY: 3>

如您所见，成员的 repr() 显示了枚举名称、成员名称和值。成员的 str() 仅显示枚举名称和成员名称

>>> print(Weekday.THURSDAY)
Weekday.THURSDAY

枚举成员的类型是它所属的枚举

>>> type(Weekday.MONDAY)
<enum 'Weekday'>
>>> isinstance(Weekday.FRIDAY, Weekday)
True

枚举成员有一个属性，其中只包含它们的 name

>>> print(Weekday.TUESDAY.name)
TUESDAY

同样，它们也有一个属性用于它们的 value

>>> Weekday.WEDNESDAY.value
3

与许多将枚举视为单纯的名称/值对的语言不同，Python 枚举可以添加行为。例如，datetime.date 有两种方法可以返回星期几：weekday() 和 isoweekday()。区别在于其中一个从 0-6 计数，另一个从 1-7 计数。与其自己跟踪这些，不如在 Weekday 枚举中添加一个方法来从 date 实例中提取日期，并返回匹配的枚举成员

@classmethod
def from_date(cls, date):
    return cls(date.isoweekday())

完整的 Weekday 枚举现在看起来像这样

>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     #
...     @classmethod
...     def from_date(cls, date):
...         return cls(date.isoweekday())

现在我们可以找出今天是星期几！观察

>>> from datetime import date
>>> Weekday.from_date(date.today())     
<Weekday.TUESDAY: 2>

当然，如果你在其他日子阅读本文，你将看到那一天。

这个 Weekday 枚举非常适合我们的变量只需要一天的情况，但如果我们需要几天呢？也许我们正在编写一个函数来绘制一周内的家务，并且不想使用 list - 我们可以使用另一种类型的 Enum

>>> from enum import Flag
>>> class Weekday(Flag):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 4
...     THURSDAY = 8
...     FRIDAY = 16
...     SATURDAY = 32
...     SUNDAY = 64

我们改变了两件事：我们继承自 Flag，并且值都是 2 的幂。

就像上面的原始 Weekday 枚举一样，我们可以进行单一选择

>>> first_week_day = Weekday.MONDAY
>>> first_week_day
<Weekday.MONDAY: 1>

但是 Flag 也允许我们将多个成员组合到一个变量中

>>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
>>> weekend
<Weekday.SATURDAY|SUNDAY: 96>

你甚至可以遍历 Flag 变量

>>> for day in weekend:
...     print(day)
Weekday.SATURDAY
Weekday.SUNDAY

好的，让我们设置一些家务

>>> chores_for_ethan = {
...     'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday.FRIDAY,
...     'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,
...     'answer SO questions': Weekday.SATURDAY,
...     }

以及一个函数来显示特定日期的家务

>>> def show_chores(chores, day):
...     for chore, days in chores.items():
...         if day in days:
...             print(chore)
...
>>> show_chores(chores_for_ethan, Weekday.SATURDAY)
answer SO questions

在成员的实际值无关紧要的情况下，你可以节省一些工作并使用 auto() 作为值

>>> from enum import auto
>>> class Weekday(Flag):
...     MONDAY = auto()
...     TUESDAY = auto()
...     WEDNESDAY = auto()
...     THURSDAY = auto()
...     FRIDAY = auto()
...     SATURDAY = auto()
...     SUNDAY = auto()
...     WEEKEND = SATURDAY | SUNDAY

以编程方式访问枚举成员及其属性

有时以编程方式访问枚举成员非常有用（即 Color.RED 不起作用的情况，因为确切的颜色在编写程序时未知）。Enum 允许这种访问

>>> Color(1)
<Color.RED: 1>
>>> Color(3)
<Color.BLUE: 3>

如果你想按名称访问枚举成员，请使用项目访问

>>> Color['RED']
<Color.RED: 1>
>>> Color['GREEN']
<Color.GREEN: 2>

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

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

复制枚举成员和值

有两个枚举成员具有相同的名称是无效的

>>> class Shape(Enum):
...     SQUARE = 2
...     SQUARE = 3
...
Traceback (most recent call last):
...
TypeError: 'SQUARE' already defined as 2

但是，枚举成员可以与其他名称相关联。给定两个具有相同值的条目 A 和 B（并且 A 首先定义），B 是成员 A 的别名。按值查找 A 的值将返回成员 A。按名称查找 A 将返回成员 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>

注意

尝试创建与已定义属性（另一个成员、方法等）同名的成员，或尝试创建与成员同名的属性是不允许的。

确保枚举值唯一

默认情况下，枚举允许使用多个名称作为同一值的别名。当不需要这种行为时，可以使用 unique() 装饰器

>>> 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

使用自动值

如果确切的值不重要，可以使用 auto

>>> from enum import Enum, auto
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> [member.value for member in Color]
[1, 2, 3]

值由 _generate_next_value_() 选择，该方法可以被覆盖

>>> class AutoName(Enum):
...     @staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return name
...
>>> class Ordinal(AutoName):
...     NORTH = auto()
...     SOUTH = auto()
...     EAST = auto()
...     WEST = auto()
...
>>> [member.value for member in Ordinal]
['NORTH', 'SOUTH', 'EAST', 'WEST']

注意

必须在任何成员之前定义 _generate_next_value_() 方法。

迭代

迭代枚举的成员不会提供别名

>>> list(Shape)
[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
>>> list(Weekday)
[<Weekday.MONDAY: 1>, <Weekday.TUESDAY: 2>, <Weekday.WEDNESDAY: 4>, <Weekday.THURSDAY: 8>, <Weekday.FRIDAY: 16>, <Weekday.SATURDAY: 32>, <Weekday.SUNDAY: 64>]

请注意，别名 Shape.ALIAS_FOR_SQUARE 和 Weekday.WEEKEND 没有显示。

特殊属性 __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']

注意

标志的别名包括设置了多个标志的值，例如 3，以及没有设置标志的值，即 0。

比较

枚举成员通过身份进行比较

>>> Color.RED is Color.RED
True
>>> Color.RED is Color.BLUE
False
>>> Color.RED is not Color.BLUE
True

不支持枚举值之间的有序比较。枚举成员不是整数（但请参见下面的 IntEnum）

>>> Color.RED < Color.BLUE
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'Color' and 'Color'

但定义了相等比较

>>> Color.BLUE == Color.RED
False
>>> Color.BLUE != Color.RED
True
>>> Color.BLUE == Color.BLUE
True

与非枚举值的比较将始终比较不相等（同样，IntEnum 被明确设计为表现不同，请参见下文）

>>> Color.BLUE == 2
False

警告

可以重新加载模块 - 如果重新加载的模块包含枚举，它们将被重新创建，并且新成员可能与原始成员不相同/相等。

枚举的允许成员和属性

上面大多数示例使用整数作为枚举值。使用整数简短方便（并且由 函数式 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'

允许的规则如下：以单个下划线开头和结尾的名称由枚举保留，不能使用；枚举中定义的所有其他属性都将成为此枚举的成员，特殊方法（__str__()，__add__() 等）、描述符（方法也是描述符）和 _ignore_ 中列出的变量名除外。

注意：如果枚举定义了 __new__() 和/或 __init__()，则传递给枚举成员的任何值都将传递给这些方法。有关示例，请参见 Planet。

注意

如果定义了 __new__() 方法，则在创建枚举成员期间使用它；然后它被 Enum 的 __new__() 替换，该方法在类创建后用于查找现有成员。有关更多详细信息，请参见 何时使用 __new__() 与 __init__()。

受限枚举子类化

新的 Enum 类必须有一个基枚举类，最多一个具体数据类型，以及尽可能多的 object 基 mixin 类。这些基类的顺序是

class EnumName([mix-in, ...,] [data-type,] base-enum):
    pass

此外，只有当枚举没有定义任何成员时才允许子类化枚举。因此，这是禁止的

>>> class MoreColor(Color):
...     PINK = 17
...
Traceback (most recent call last):
...
TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'>

但这是允许的

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

允许子类化定义成员的枚举会导致违反类型和实例的一些重要不变式。另一方面，允许在枚举组之间共享一些通用行为是有意义的。（有关示例，请参见 OrderedEnum。）

数据类支持

从 dataclass 继承时，__repr__() 会省略继承类的名称。例如

>>> from dataclasses import dataclass, field
>>> @dataclass
... class CreatureDataMixin:
...     size: str
...     legs: int
...     tail: bool = field(repr=False, default=True)
...
>>> class Creature(CreatureDataMixin, Enum):
...     BEETLE = 'small', 6
...     DOG = 'medium', 4
...
>>> Creature.DOG
<Creature.DOG: size='medium', legs=4>

使用 dataclass() 参数 repr=False 来使用标准 repr()。

在版本 3.12 中更改： 仅在值区域显示数据类字段，而不是数据类名称。

腌制

枚举可以被腌制和解腌制

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

腌制的通常限制适用：可腌制的枚举必须在模块的顶层定义，因为解腌制需要它们能够从该模块导入。

注意

使用 pickle 协议版本 4，可以轻松腌制嵌套在其他类中的枚举。

可以通过在枚举类中定义 __reduce_ex__() 来修改枚举成员的腌制/解腌制方式。默认方法是按值，但具有复杂值的枚举可能希望使用按名称

>>> import enum
>>> class MyEnum(enum.Enum):
...     __reduce_ex__ = enum.pickle_by_enum_name

注意

不建议对标志使用按名称，因为未命名的别名将无法解腌制。

函数式 API

Enum 类是可调用的，提供以下函数式 API

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 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,
    )

• value：新枚举类将记录为其名称的内容。

• names：枚举成员。这可以是一个空格或逗号分隔的字符串（值将从 1 开始，除非另有指定）

  'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
  

  或名称的迭代器

  ['RED', 'GREEN', 'BLUE']
  

  或 (name, value) 对的迭代器

  [('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
  

  或映射

  {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
  

• module：可以找到新枚举类的模块名称。

• qualname：在模块中可以找到新枚举类的位置。

• type：要混合到新枚举类中的类型。

• start：如果只传递名称，则从该数字开始计数。

版本 3.5 中的变更： 添加了 start 参数。

派生枚举

IntEnum

提供的 Enum 的第一个变体也是 int 的子类。 IntEnum 的成员可以与整数进行比较；扩展而言，不同类型的整数枚举也可以相互比较。

>>> 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]

StrEnum

提供的 Enum 的第二个变体也是 str 的子类。 StrEnum 的成员可以与字符串进行比较；扩展而言，不同类型的字符串枚举也可以相互比较。

在版本 3.11 中添加。

IntFlag

接下来提供的 Enum 的变体，IntFlag，也是基于 int。不同之处在于 IntFlag 成员可以使用按位运算符 (&, |, ^, ~) 进行组合，如果可能，结果仍然是 IntFlag 成员。与 IntEnum 一样，IntFlag 成员也是整数，可以在任何使用 int 的地方使用。

注意

对 IntFlag 成员进行的任何操作，除了按位运算，都会失去 IntFlag 成员资格。

导致无效 IntFlag 值的按位运算将失去 IntFlag 成员资格。有关详细信息，请参见 FlagBoundary。

在版本 3.6 中添加。

在版本 3.11 中更改。

示例 IntFlag 类

>>> from enum import IntFlag
>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...
>>> Perm.R | Perm.W
<Perm.R|W: 6>
>>> Perm.R + Perm.W
6
>>> RW = Perm.R | Perm.W
>>> Perm.R in RW
True

也可以命名组合

>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...     RWX = 7
...
>>> Perm.RWX
<Perm.RWX: 7>
>>> ~Perm.RWX
<Perm: 0>
>>> Perm(7)
<Perm.RWX: 7>

注意

命名组合被视为别名。别名在迭代期间不会显示，但可以通过按值查找返回。

在版本 3.11 中更改。

IntFlag 和 Enum 之间的另一个重要区别是，如果未设置任何标志（值为 0），则其布尔值评估为 False

>>> Perm.R & Perm.X
<Perm: 0>
>>> bool(Perm.R & Perm.X)
False

因为 IntFlag 成员也是 int 的子类，所以它们可以与它们组合（但可能会失去 IntFlag 成员资格）

>>> Perm.X | 4
<Perm.R|X: 5>

>>> Perm.X + 8
9

注意

否定运算符 ~ 始终返回一个具有正值的 IntFlag 成员

>>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
True

IntFlag 成员也可以进行迭代

>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]

在版本 3.11 中添加。

标志

最后一个变体是 Flag。与 IntFlag 类似，Flag 成员可以使用按位运算符（&，|，^，~）进行组合。与 IntFlag 不同，它们不能与任何其他 Flag 枚举或 int 组合或进行比较。虽然可以指定直接的值，但建议使用 auto 作为值，并让 Flag 选择一个合适的值。

在版本 3.6 中添加。

与 IntFlag 类似，如果 Flag 成员的组合导致没有设置任何标志，则布尔值评估为 False

>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.RED & Color.GREEN
<Color: 0>
>>> bool(Color.RED & Color.GREEN)
False

单个标志的值应为 2 的幂（1、2、4、8、…），而标志组合的值则不会

>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...     WHITE = RED | BLUE | GREEN
...
>>> Color.WHITE
<Color.WHITE: 7>

为“未设置任何标志”条件命名不会改变其布尔值

>>> class Color(Flag):
...     BLACK = 0
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> bool(Color.BLACK)
False

Flag 成员也可以进行迭代

>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]

在版本 3.11 中添加。

注意

对于大多数新代码，强烈建议使用 Enum 和 Flag，因为 IntEnum 和 IntFlag 违反了枚举的一些语义承诺（通过与整数进行比较，从而通过传递性与其他不相关的枚举进行比较）。IntEnum 和 IntFlag 应该只在 Enum 和 Flag 不起作用的情况下使用；例如，当整数常量被枚举替换时，或为了与其他系统进行互操作。

其他

虽然 IntEnum 是 enum 模块的一部分，但独立实现它非常简单

class IntEnum(int, Enum):
    pass

这演示了如何定义类似的派生枚举；例如，一个 FloatEnum，它混合了 float 而不是 int。

一些规则

1. 当子类化 Enum 时，混合类型必须出现在 Enum 本身之前，在基类序列中，如上面的 IntEnum 示例所示。

2. 混合类型必须是可子类化的。例如，bool 和 range 不可子类化，如果用作混合类型，将在枚举创建期间抛出错误。

3. 虽然 Enum 可以拥有任何类型的成员，但一旦你混合了额外的类型，所有成员都必须具有该类型的值，例如上面的 int。此限制不适用于仅添加方法而不指定其他类型的混合类型。

4. 当混合了另一个数据类型时，value 属性 *不等于* 枚举成员本身，尽管它等效并且将比较相等。

5. 一个 data type 是一个混合类型，它定义了 __new__()，或一个 dataclass

6. %-style 格式化：%s 和 %r 分别调用 Enum 类的 __str__() 和 __repr__()；其他代码（例如 %i 或 %h 用于 IntEnum）将枚举成员视为其混合类型。

7. 格式化字符串字面量、str.format() 和 format() 将使用枚举的 __str__() 方法。

注意

因为 IntEnum、IntFlag 和 StrEnum 被设计为现有常量的直接替换，它们的 __str__() 方法已被重置为其数据类型的 __str__() 方法。

何时使用 __new__() 与 __init__()

__new__() 必须在您想要自定义 Enum 成员的实际值时使用。任何其他修改都可以放在 __new__() 或 __init__() 中，建议使用 __init__()。

例如，如果您想将多个项目传递给构造函数，但只希望其中一个作为值

>>> class Coordinate(bytes, Enum):
...     """
...     Coordinate with binary codes that can be indexed by the int code.
...     """
...     def __new__(cls, value, label, unit):
...         obj = bytes.__new__(cls, [value])
...         obj._value_ = value
...         obj.label = label
...         obj.unit = unit
...         return obj
...     PX = (0, 'P.X', 'km')
...     PY = (1, 'P.Y', 'km')
...     VX = (2, 'V.X', 'km/s')
...     VY = (3, 'V.Y', 'km/s')
...

>>> print(Coordinate['PY'])
Coordinate.PY

>>> print(Coordinate(3))
Coordinate.VY

警告

不要调用 super().__new__()，因为只有查找的 __new__ 会被找到；相反，直接使用数据类型。

更细致的要点

支持的 __dunder__ 名称

__members__ 是一个只读的有序映射，包含 member_name:member 项目。它只在类上可用。

__new__()，如果指定，必须创建并返回枚举成员；设置成员的 _value_ 也是一个非常好的做法。一旦所有成员都被创建，它就不再被使用。

支持的 _sunder_ 名称

• _name_ – 成员的名称

• _value_ – 成员的值；可以在 __new__ 中设置/修改

• _missing_ – 当找不到值时使用的查找函数；可以被覆盖

• _ignore_ – 一个名称列表，可以是 list 或 str，这些名称不会被转换为成员，并将从最终类中删除

• _order_ – 在 Python 2/3 代码中使用，以确保成员顺序一致（类属性，在类创建期间被移除）

• _generate_next_value_ – 由 函数式 API 和 auto 使用，以获取枚举成员的适当值；可以被覆盖

注意

对于标准的 Enum 类，选择的下一个值是最后一个看到的增量值加一。

对于 Flag 类，选择的下一个值将是下一个最高的 2 的幂，无论最后一个看到的增量值是多少。

在版本 3.6 中添加: _missing_, _order_, _generate_next_value_

在版本 3.7 中添加: _ignore_

为了帮助保持 Python 2 / Python 3 代码同步，可以提供一个 _order_ 属性。它将与枚举的实际顺序进行检查，如果两者不匹配，则会引发错误

>>> class Color(Enum):
...     _order_ = 'RED GREEN BLUE'
...     RED = 1
...     BLUE = 3
...     GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
  ['RED', 'BLUE', 'GREEN']
  ['RED', 'GREEN', 'BLUE']

注意

在 Python 2 代码中，_order_ 属性是必要的，因为定义顺序在记录之前就丢失了。

_私有__名称

私有名称 不会转换为枚举成员，而是保持为普通属性。

在版本 3.11 中更改。

Enum 成员类型

枚举成员是其枚举类的实例，通常以 EnumClass.member 的形式访问。在某些情况下，例如编写自定义枚举行为，能够从另一个成员直接访问一个成员很有用，并且是支持的；但是，为了避免成员名称与混合类中的属性/方法之间的名称冲突，强烈建议使用大写名称。

在版本 3.5 中更改。

创建与其他数据类型混合的成员

当使用 Enum 子类化其他数据类型（例如 int 或 str）时，= 后的所有值都将传递给该数据类型的构造函数。例如

>>> class MyEnum(IntEnum):      # help(int) -> int(x, base=10) -> integer
...     example = '11', 16      # so x='11' and base=16
...
>>> MyEnum.example.value        # and hex(11) is...
17

Enum 类和成员的布尔值

与非 Enum 类型（例如 int、str 等）混合的枚举类将根据混合类型的规则进行评估；否则，所有成员都将评估为 True。要使您自己的枚举的布尔值评估取决于成员的值，请将以下内容添加到您的类中

def __bool__(self):
    return bool(self.value)

普通 Enum 类始终评估为 True。

Enum 类与方法

如果您为枚举子类提供额外的​​方法，例如下面的 Planet 类，这些方法将显示在成员的 dir() 中，但不会显示在类的 dir() 中

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

组合 Flag 的成员

迭代 Flag 成员的组合将只返回由单个位组成的成员

>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...     MAGENTA = RED | BLUE
...     YELLOW = RED | GREEN
...     CYAN = GREEN | BLUE
...
>>> Color(3)  # named combination
<Color.YELLOW: 3>
>>> Color(7)      # not named combination
<Color.RED|GREEN|BLUE: 7>

Flag 和 IntFlag 的细节

使用以下代码段作为我们的示例

>>> class Color(IntFlag):
...     BLACK = 0
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     PURPLE = RED | BLUE
...     WHITE = RED | GREEN | BLUE
...

以下是正确的

• 单比特标志是规范的

• 多比特和零比特标志是别名

• 迭代期间只返回规范标志

  >>> list(Color.WHITE)
  [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
  

• 对标志或标志集取反会返回一个具有相应正整数值的新标志/标志集

  >>> Color.BLUE
  <Color.BLUE: 4>
  
  >>> ~Color.BLUE
  <Color.RED|GREEN: 3>
  

• 伪标志的名称由其成员的名称构成

  >>> (Color.RED | Color.GREEN).name
  'RED|GREEN'
  
  >>> class Perm(IntFlag):
  ...     R = 4
  ...     W = 2
  ...     X = 1
  ...
  >>> (Perm.R & Perm.W).name is None  # effectively Perm(0)
  True
  

• 多位标志，也称为别名，可以从操作中返回

  >>> Color.RED | Color.BLUE
  <Color.PURPLE: 5>
  
  >>> Color(7)  # or Color(-1)
  <Color.WHITE: 7>
  
  >>> Color(0)
  <Color.BLACK: 0>
  

• 成员资格/包含检查：零值标志始终被视为包含

  >>> Color.BLACK in Color.WHITE
  True
  

  否则，只有当一个标志的所有位都在另一个标志中时，才会返回 True

  >>> Color.PURPLE in Color.WHITE
  True
  
  >>> Color.GREEN in Color.PURPLE
  False
  

存在一种新的边界机制来控制如何处理超出范围/无效位：STRICT、CONFORM、EJECT 和 KEEP

• STRICT -> 当遇到无效值时引发异常

• CONFORM -> 丢弃任何无效位

• EJECT -> 失去 Flag 状态并成为具有给定值的普通 int

• KEEP -> 保留额外的位

  • 保留 Flag 状态和额外的位

  • 额外的位不会出现在迭代中

  • 额外的位会出现在 repr() 和 str() 中

Flag 的默认值为 STRICT，IntFlag 的默认值为 EJECT，_convert_ 的默认值为 KEEP（有关 KEEP 必要的示例，请参见 ssl.Options）。

枚举和标志有什么区别？

枚举有一个自定义元类，它影响派生 Enum 类及其实例（成员）的许多方面。

枚举类

EnumType 元类负责提供 __contains__()、__dir__()、__iter__() 和其他方法，这些方法允许人们对 Enum 类执行一些操作，这些操作在典型的类上会失败，例如 list(Color) 或 some_enum_var in Color。 EnumType 负责确保最终 Enum 类上的各种其他方法是正确的（例如 __new__()、__getnewargs__()、__str__() 和 __repr__()）。

标志类

标志对别名有扩展的视图：要成为规范的，标志的值需要是 2 的幂值，而不是重复的名称。因此，除了 Enum 对别名的定义之外，没有值（也称为 0）或具有多个 2 的幂值的标志（例如 3）被认为是别名。

枚举成员（也称为实例）

枚举成员最有趣的地方在于它们是单例。 EnumType 在创建枚举类本身时创建它们，然后放置一个自定义的 __new__() 来确保通过仅返回现有的成员实例来永远不会实例化新的成员。

标志成员

标志成员可以像 Flag 类一样进行迭代，并且只会返回规范的成员。例如

>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]

(请注意，BLACK、PURPLE 和 WHITE 不会显示。)

反转标志成员会返回相应的正值，而不是负值，例如

>>> ~Color.RED
<Color.GREEN|BLUE: 6>

标志成员的长度对应于它们包含的 2 的幂值的个数。例如

>>> len(Color.PURPLE)
2

枚举食谱

虽然 Enum、IntEnum、StrEnum、Flag 和 IntFlag 预计涵盖大多数用例，但它们无法涵盖所有用例。以下是一些不同类型枚举的食谱，可以直接使用，也可以作为创建自己枚举的示例。

省略值

在许多用例中，人们并不关心枚举的实际值。有几种方法可以定义这种类型的简单枚举

• 使用 auto 的实例作为值

• 使用 object 的实例作为值

• 使用描述性字符串作为值

• 使用元组作为值，并使用自定义的 __new__() 将元组替换为 int 值

使用任何这些方法都向用户表明这些值并不重要，并且还允许在不重新编号剩余成员的情况下添加、删除或重新排序成员。

使用 auto

使用 auto 将如下所示

>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN: 3>

使用 object

使用 object 将如下所示

>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN                         
<Color.GREEN: <object object at 0x...>>

这也是为什么你可能想要编写自己的 __repr__() 的一个很好的例子。

>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...     def __repr__(self):
...         return "<%s.%s>" % (self.__class__.__name__, self._name_)
...
>>> Color.GREEN
<Color.GREEN>

使用描述性字符串

使用字符串作为值将如下所示

>>> class Color(Enum):
...     RED = 'stop'
...     GREEN = 'go'
...     BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN: 'go'>

使用自定义的 __new__()

使用自动编号的 __new__() 将如下所示

>>> 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
<Color.GREEN: 2>

要创建一个更通用的 AutoNumber，请在签名中添加 *args

>>> class AutoNumber(Enum):
...     def __new__(cls, *args):      # this is the only change from above
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...

然后，当你从 AutoNumber 继承时，你可以编写自己的 __init__ 来处理任何额外的参数

>>> class Swatch(AutoNumber):
...     def __init__(self, pantone='unknown'):
...         self.pantone = pantone
...     AUBURN = '3497'
...     SEA_GREEN = '1246'
...     BLEACHED_CORAL = () # New color, no Pantone code yet!
...
>>> Swatch.SEA_GREEN
<Swatch.SEA_GREEN: 2>
>>> Swatch.SEA_GREEN.pantone
'1246'
>>> Swatch.BLEACHED_CORAL.pantone
'unknown'

注意

如果定义了 __new__() 方法，它将在创建枚举成员时使用；然后它将被 Enum 的 __new__() 替换，后者在类创建后用于查找现有成员。

警告

不要调用 super().__new__()，因为找到的是仅用于查找的 __new__；相反，直接使用数据类型，例如

obj = int.__new__(cls, value)

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

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() 装饰器。

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

TimePeriod

一个示例，展示了 _ignore_ 属性的使用。

>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
...     "different lengths of time"
...     _ignore_ = 'Period i'
...     Period = vars()
...     for i in range(367):
...         Period['day_%d' % i] = i
...
>>> list(Period)[:2]
[<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
>>> list(Period)[-2:]
[<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]

对 EnumType 进行子类化

虽然大多数枚举需求可以通过自定义 Enum 子类来满足，无论是使用类装饰器还是自定义函数，都可以对 EnumType 进行子类化以提供不同的 Enum 体验。