Pythonenum枚举类型支持

允许的枚举成员和属性¶

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

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

>>> classMood(Enum):
... FUNKY=1
... HAPPY=3
...
... defdescribe(self):
... # self is the member here
... returnself.name,self.value
...
... def__str__(self):
... return'my custom str! {0}'.format(self.value)
...
... @classmethod
... deffavorite_mood(cls):
... # cls here is the enumeration
... returncls.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。

受限的 Enum 子类化¶

一个新的 Enum 类必须基于一个 Enum 类，至多一个实体数据类型以及出于实际需要的任意多个基于 object 的 mixin 类。 这些基类的顺序为:

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

另外，仅当一个枚举未定义任何成员时才允许子类化该枚举。 因此禁止以下写法:

>>> classMoreColor(Color):
... PINK=17
...
Traceback (most recent call last):
...
TypeError: Cannot extend enumerations

但是允许这样的写法:

>>> classFoo(Enum):
... defsome_behavior(self):
... pass
...
>>> classBar(Foo):
... HAPPY=1
... SAD=2
...

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

封存¶

枚举可以被封存与解封:

>>> fromtest.test_enumimportFruit
>>> frompickleimportdumps,loads
>>> Fruit.TOMATOisloads(dumps(Fruit.TOMATO))
True

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

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

可用 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 的赋值就等价于:

>>> classAnimal(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__)

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

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

完整的签名为:

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

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

派生的枚举¶

>>> fromenumimportIntEnum
>>> classShape(IntEnum):
... CIRCLE=1
... SQUARE=2
...
>>> classRequest(IntEnum):
... POST=1
... GET=2
...
>>> Shape==1
False
>>> Shape.CIRCLE==1
True
>>> Shape.CIRCLE==Request.POST
True

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

>>> int(Shape.CIRCLE)
1
>>> ['a','b','c'][Shape.CIRCLE]
'b'
>>> [iforiinrange(Shape.SQUARE)]
[0, 1]

>>> fromenumimportIntFlag
>>> classPerm(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.RinRW
True

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

>>> fromenumimportFlag,auto
>>> classColor(Flag):
... RED=auto()
... BLUE=auto()
... GREEN=auto()
...
>>> Color.RED&Color.GREEN
<Color.0: 0>
>>> bool(Color.RED&Color.GREEN)
False

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

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

classIntEnum(int,Enum):
pass

>>> classNoValue(Enum):
... def__repr__(self):
... return'<%s.%s>'%(self.__class__.__name__,self.name)
...

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

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

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

>>> classAutoNumber(NoValue):
... def__new__(cls):
... value=len(cls.__members__)+1
... obj=object.__new__(cls)
... obj._value_=value
... returnobj
...
>>> classColor(AutoNumber):
... RED=()
... GREEN=()
... BLUE=()
...
>>> Color.GREEN
<Color.GREEN>
>>> Color.GREEN.value
2

>>> classOrderedEnum(Enum):
... def__ge__(self,other):
... ifself.__class__isother.__class__:
... returnself.value>=other.value
... returnNotImplemented
... def__gt__(self,other):
... ifself.__class__isother.__class__:
... returnself.value>other.value
... returnNotImplemented
... def__le__(self,other):
... ifself.__class__isother.__class__:
... returnself.value<=other.value
... returnNotImplemented
... def__lt__(self,other):
... ifself.__class__isother.__class__:
... returnself.value<other.value
... returnNotImplemented
...
>>> classGrade(OrderedEnum):
... A=5
... B=4
... C=3
... D=2
... F=1
...
>>> Grade.C<Grade.A
True

>>> classDuplicateFreeEnum(Enum):
... def__init__(self,*args):
... cls=self.__class__
... ifany(self.value==e.valueforeincls):
... a=self.name
... e=cls(self.value).name
... raiseValueError(
... "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
... %(a,e))
...
>>> classColor(DuplicateFreeEnum):
... RED=1
... GREEN=2
... BLUE=3
... GRENE=2
...
Traceback (most recent call last):
...
ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'

>>> classPlanet(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
... defsurface_gravity(self):
... # universal gravitational constant  (m3 kg-1 s-2)
... G=6.67300E-11
... returnG*self.mass/(self.radius*self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129

>>> fromdatetimeimporttimedelta
>>> classPeriod(timedelta,Enum):
... "different lengths of time"
... _ignore_='Period i'
... Period=vars()
... foriinrange(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)>]

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

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

def__bool__(self):
returnbool(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']

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