enum模块支持枚举的详解(42)Python语言(必读进阶学习教程)(参考资料)

模块内容

该模块定义了可以用于定义名称和值的独特的套4枚举类：Enum，IntEnum，Flag，和 IntFlag。它还定义了一个装饰器unique()和一个辅助器auto。

类enum.Enum

用于创建枚举常量的基类。有关替代构造语法，请参阅功能API一节 。

类enum.IntEnum

用于创建枚举常量的基类，它们也是子类int。

类enum.IntFlag

用于创建枚举常量的基类，可以使用按位运算符进行组合而不会丢失其IntFlag成员资格。 IntFlag成员也是子类int。

类enum.Flag

用于创建枚举常量的基类，可以使用按位运算组合而不会丢失其Flag成员资格。

enum.unique（）

枚举类装饰器，确保只有一个名称绑定到任何一个值。

类enum.auto

实例将替换为Enum成员的适当值。

创建枚举

枚举是使用class语法创建的，这使它们易于读写。Functional API中描述了另一种创建方法 。要定义枚举，子类Enum如下：

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

枚举成员具有人类可读的字符串表示形式：

>>>
>>> print(Color.RED)
Color.RED

……虽然他们repr有更多的信息：

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

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

>>>
>>> type(Color.RED)
<enum 'Color'>
>>> isinstance(Color.GREEN, Color)
True
>>>

枚举成员还有一个只包含其项目名称的属性：

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

对枚举成员及其属性的编程访问

有时，以编程方式访问枚举中的成员是有用的（即，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: 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>

确保唯一的枚举值

默认情况下，枚举允许多个名称作为同一值的别名。如果不需要此行为，可以使用以下装饰器来确保每个值在枚举中只使用一次：

@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

使用自动值

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

>>>
>>> from enum import Enum, auto
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

选择的值_generate_next_value_()可以被覆盖：

>>>
>>> class AutoName(Enum):
...     def _generate_next_value_(name, start, count, last_values):
...         return name
...
>>> class Ordinal(AutoName):
...     NORTH = auto()
...     SOUTH = auto()
...     EAST = auto()
...     WEST = auto()
...
>>> list(Ordinal)
[<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]

迭代

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

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

比较

枚举成员按身份进行比较：

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

允许的成员和枚举属性

上面的示例使用整数来表示枚举值。使用整数简短而方便（并且由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'

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

注意：如果您的枚举定义__new__()和/或__init__()然后给予枚举成员的任何值将被传递到这些方法中。有关示例，请参阅Planet。

受限制的枚举子类

新Enum类必须具有一个基本枚举类，最多一个具体数据类型，以及object根据需要具有多个基础的mixin类。这些基类的顺序是：

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

此外，仅当枚举未定义任何成员时，才允许子类化枚举。所以这是禁止的：

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

酸洗

可以对枚举进行pickle和unpickled：

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

酸洗的通常限制适用：必须在模块的顶层定义可选择的枚举，因为unpickling要求它们可以从该模块导入。

可以通过__reduce_ex__()在枚举类中定义来修改Enum成员的pickle / unpickled方式 。

功能

的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__)

在某些情况下，新的泡菜协议4依赖于 __qualname__设置到泡菜能够找到该类的位置。例如，如果该类在全局范围内的类SomeData中可用：

>>>
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')

完整的签名是：

Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=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}

派生枚举

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

>>>
>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...
>>> Shape.CIRCLE == Color.RED
False

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

>>>
>>> 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.-8: -8>

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

>>>
>>> Perm.X | 8
<Perm.8|X: 9>

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

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

class IntEnum(int, Enum):
    pass

有趣的例子

虽然Enum，IntEnum，IntFlag，并Flag预计将覆盖大部分的使用情况，他们不能涵盖所有。以下是可以直接使用的一些不同类型的枚举的配方，或者作为创建自己的枚举的示例。

>>>
>>> class NoValue(Enum):
...     def __repr__(self):
...         return '<%s.%s>' % (self.__class__.__name__, self.name)
...

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

>>>
>>> class Color(NoValue):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN
<Color.GREEN>

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

>>>
>>> class AutoNumber(NoValue):
...     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>
>>> Color.GREEN.value
2

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

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

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

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

Enum与众不同？

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

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

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

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

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

>>>
>>> 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.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>