Python

您所在的位置：网站首页 › 枚举成员是常量 › Python

Python

2024-07-16 22:53| 来源: 网络整理| 查看: 265

enum — 支持枚举

3.4 版本中的新功能。

Source code:Lib/enum.py

Important

此页面包含 API 参考信息。有关教程信息和更高级主题的讨论，请参阅

Basic Tutorial Advanced Tutorial Enum Cookbook

An enumeration:

是一组绑定到唯一值的符号名称（成员）可以迭代以按定义顺序返回其规范（即非别名）成员使用调用语法按值返回成员使用索引语法按名称返回成员

枚举可以使用 class 语法或函数调用语法创建：

>>> from enum import Enum >>> # 类语法 >>> class Color(Enum): ... RED = 1 ... GREEN = 2 ... BLUE = 3 >>> # 函数语法 >>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])

尽管我们可以使用 class 语法来创建枚举，但枚举不是普通的 Python 类。有关详细信息，请参阅 How are Enums different? 。

Note

Nomenclature

Color 类是一个枚举（或 enum）属性 Color.RED 、 Color.GREEN 等是枚举成员（或成员），并且是功能常量。枚举成员具有名称和值（ Color.RED 的名称是 RED ， Color.BLUE 的值是 3 等） Module Contents

EnumType

用于 Enum 及其子类的 type 。

Enum

用于创建枚举常量的基类。

IntEnum

用于创建枚举常量的基类，也是 int 的子类。( Notes )

StrEnum

用于创建枚举常量的基类，也是 str 的子类。( Notes )

Flag

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

IntFlag

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

ReprEnum

由 IntEnum 、 StrEnum 和 IntFlag 使用，以保持混合型的 str() 。

EnumCheck

具有值 CONTINUOUS 、 NAMED_FLAGS 和 UNIQUE 的枚举，与 verify() 一起使用以确保给定枚举满足各种约束。

FlagBoundary

具有值 STRICT 、 CONFORM 、 EJECT 和 KEEP 的枚举，允许对枚举中无效值的处理方式进行更细粒度的控制。

auto

实例被替换为 Enum 成员的适当值。 StrEnum 默认为成员名称的小写版本，而其他枚举默认为 1 并从该值开始增加。

property()

允许 Enum 成员拥有属性而不与成员名称冲突。 value 和 name 属性就是通过这种方式实现的。

unique()

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

verify()

枚举类装饰器，用于检查枚举上用户可选择的约束。

member()

使 obj 成为会员。可以用作装饰器。

nonmember()

不要让 obj 成为会员。可以用作装饰器。

global_enum()

修改枚举的 str() 和 repr() ，以将其成员显示为属于模块而不是属于其类，并将枚举成员导出到全局命名空间。

show_flag_values()

返回标志中包含的所有二次幂整数的列表。

3.6版本新增： Flag 、 IntFlag 、 auto

3.11版本新增： StrEnum 、 EnumCheck 、 ReprEnum 、 FlagBoundary 、 property 、 member 、 nonmember 、 global_enum 、 show_flag_values

Data Types class enum.EnumType

EnumType 是用于 enum 枚举的 metaclass 。可以对 EnumType 进行子类化 - 有关详细信息，请参阅 Subclassing EnumType 。

EnumType 负责在最终枚举上设置正确的 __repr__() 、 __str__() 、 __format__() 和 __reduce__() 方法，以及创建枚举成员、正确处理重复项、提供枚举类的迭代等。

__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)

该方法有两种不同的调用方式：

查找现有成员：

cls

被调用的枚举类。

value

要查找的值。

使用 cls 枚举创建新枚举（仅当现有枚举没有任何成员时）：

cls

被调用的枚举类。

value

要创建的新枚举的名称。

names

新枚举的成员的名称/值。

module

在其中创建新枚举的模块的名称。

qualname

模块中可以找到此枚举的实际位置。

type

新枚举的混合类型。

start

Enum 的第一个整数值（由 auto 使用）。

boundary

如何处理位操作中超出范围的值（仅限 Flag ）。

__contains__(cls, member)

如果成员属于 cls ，则返回 True ：

>>> some_var = Color.RED >>> some_var in Color True >>> Color.RED.value in Color True

版本 3.12 中的更改：在 Python 3.12 之前，如果在包含检查中使用非 Enum 成员，则会引发 TypeError 。

__dir__(cls)

返回 ['__class__', '__doc__', '__members__', '__module__'] 和 cls 中的成员名称：

>>> dir(Color) ['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__'] __getitem__(cls, name)

返回 cls 中与名称匹配的 Enum 成员，或引发 KeyError ：

>>> Color['BLUE'] __iter__(cls)

按定义顺序返回 cls 中的每个成员：

>>> list(Color) [, , ] __len__(cls)

返回 cls 中的成员数：

>>> len(Color) 3 __reversed__(cls)

以相反的定义顺序返回 cls 中的每个成员：

>>> list(reversed(Color)) [, , ]

3.11版本新增：3.11之前 enum 使用 EnumMeta 类型，保留为别名。

class enum.Enum

Enum 是所有 enum 枚举的基类。

name

用于定义 Enum 成员的名称：

>>> Color.BLUE.name 'BLUE' value

赋予 Enum 成员的值：

>>> Color.RED.value 1

Note

枚举成员值

成员值可以是任何值： int 、 str 等。如果确切的值不重要，您可以使用 auto 实例，系统会为您选择合适的值。有关详细信息，请参阅 auto 。

_ignore_

_ignore_ 仅在创建期间使用，创建完成后将从枚举中删除。

_ignore_ 是不会成为成员的姓名列表，其姓名也将从完成的枚举中删除。有关示例，请参阅 TimePeriod 。

__dir__(self)

返回在 self.__class__ 上定义的 ['__class__', '__doc__', '__module__', 'name', 'value'] 和任何 public 方法：

>>> from datetime import date >>> class Weekday(Enum): ... MONDAY = 1 ... TUESDAY = 2 ... WEDNESDAY = 3 ... THURSDAY = 4 ... FRIDAY = 5 ... SATURDAY = 6 ... SUNDAY = 7 ... @classmethod ... def today(cls): ... print('today is %s' % cls(date.today().isoweekday()).name) ... >>> dir(Weekday.SATURDAY) ['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value'] _generate_next_value_(name, start, count, last_values) name

正在定义的成员的名称（例如“RED”）。

start

枚举的起始值；默认值为 1。

count

当前定义的成员数量，不包括这一成员。

last_values

先前值的列表。

用于确定 auto 返回的下一个值的静态方法：

>>> from enum import auto >>> class PowersOfThree(Enum): ... @staticmethod ... def _generate_next_value_(name, start, count, last_values): ... return 3 ** (count + 1) ... FIRST = auto() ... SECOND = auto() ... >>> PowersOfThree.SECOND.value 9 __init_subclass__(cls, \**kwds)

用于进一步配置后续子类的类方法。默认情况下，不执行任何操作。

_missing_(cls, value)

用于查找 cls 中未找到的值的类方法。默认情况下它不执行任何操作，但可以重写以实现自定义搜索行为：

>>> from enum import StrEnum >>> class Build(StrEnum): ... DEBUG = auto() ... OPTIMIZED = auto() ... @classmethod ... def _missing_(cls, value): ... value = value.lower() ... for member in cls: ... if member.value == value: ... return member ... return None ... >>> Build.DEBUG.value 'debug' >>> Build('deBUG') __repr__(self)

返回用于 repr() 调用的字符串。默认情况下，返回枚举名称、成员名称和值，但可以覆盖：

>>> class OtherStyle(Enum): ... ALTERNATE = auto() ... OTHER = auto() ... SOMETHING_ELSE = auto() ... def __repr__(self): ... cls_name = self.__class__.__name__ ... return f'{cls_name}.{self.name}' ... >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" (OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE') __str__(self)

返回用于 str() 调用的字符串。默认情况下，返回枚举名称和成员名称，但可以覆盖：

>>> class OtherStyle(Enum): ... ALTERNATE = auto() ... OTHER = auto() ... SOMETHING_ELSE = auto() ... def __str__(self): ... return f'{self.name}' ... >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" (, 'ALTERNATE', 'ALTERNATE') __format__(self)

返回用于 format() 和 f 字符串调用的字符串。默认情况下，返回 __str__() 返回值，但可以被覆盖：

>>> class OtherStyle(Enum): ... ALTERNATE = auto() ... OTHER = auto() ... SOMETHING_ELSE = auto() ... def __format__(self, spec): ... return f'{self.name}' ... >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" (, 'OtherStyle.ALTERNATE', 'ALTERNATE')

Note

将 auto 与 Enum 一起使用会产生从 1 开始的递增值的整数。

版本 3.12 中更改：添加了 Dataclass support

class enum.IntEnum

IntEnum 与 Enum 相同，但它的成员也是整数，并且可以在任何可以使用整数的地方使用。如果对 IntEnum 成员执行任何整数运算，则结果值将失去其枚举状态。

>>> from enum import IntEnum >>> class Number(IntEnum): ... ONE = 1 ... TWO = 2 ... THREE = 3 ... >>> Number.THREE >>> Number.ONE + Number.TWO 3 >>> Number.THREE + 5 8 >>> Number.THREE == 3 True

Note

将 auto 与 IntEnum 一起使用会产生从 1 开始的递增值的整数。

版本 3.11 中进行了更改： __str__() 现在为 int.__str__() ，以更好地支持替换现有常量用例。由于同样的原因， __format__() 已经成为 int.__format__() 。

class enum.StrEnum

StrEnum 与 Enum 相同，但它的成员也是字符串，并且可以在大多数可以使用字符串的地方使用。对 StrEnum 成员执行或使用 StrEnum 成员执行的任何字符串操作的结果不是枚举的一部分。

Note

stdlib 中的某些位置会检查确切的 str 而不是 str 子类（即 type(unknown) == str 而不是 isinstance(unknown, str) ），并且在这些位置您将需要使用 str(StrEnum.member) 。

Note

将 auto 与 StrEnum 一起使用会产生小写的成员名称作为值。

Note

__str__() 是 str.__str__() 更好地支持替换现有常量的用例。出于同样的原因， __format__() 同样是 str.__format__() 。

3.11 版本中的新功能。

class enum.Flag

标志成员支持按位运算符 & (AND)、 | (OR)、 ^ (XOR) 和 ~ (INVERT)；这些运算符的结果是枚举的成员。

__contains__(self, value)

如果值在 self 中，则返回 True ：

>>> from enum import Flag, auto >>> class Color(Flag): ... RED = auto() ... GREEN = auto() ... BLUE = auto() ... >>> purple = Color.RED | Color.BLUE >>> white = Color.RED | Color.GREEN | Color.BLUE >>> Color.GREEN in purple False >>> Color.GREEN in white True >>> purple in white True >>> white in purple False __iter__(self):

返回所有包含的非别名成员：

>>> list(Color.RED) [] >>> list(purple) [, ]

版本 3.11 中的更改：迭代期间不再返回别名。

__len__(self):

返回标志中的成员数量：

>>> len(Color.GREEN) 1 >>> len(white) 3 __bool__(self):

如果标志中有任何成员，则返回 True ，否则返回 False ：

>>> bool(Color.GREEN) True >>> bool(white) True >>> black = Color(0) >>> bool(black) False __or__(self, other)

返回当前标志二进制或与其他标志：

>>> Color.RED | Color.GREEN __and__(self, other)

返回当前标志二进制文件并与其他二进制文件相结合：

>>> purple & white >>> purple & Color.GREEN __xor__(self, other)

返回当前标志与其他二进制异或：

>>> purple ^ white >>> purple ^ Color.GREEN __invert__(self):

返回 type(self) 中不属于 self 的所有标志：

>>> ~white >>> ~purple >>> ~Color.RED _numeric_repr_()

用于格式化任何剩余未命名数值的函数。默认值是值的代表；常见的选择是 hex() 和 oct() 。

Note

将 auto 与 Flag 一起使用会产生以 1 开头的 2 的幂的整数。

版本 3.11 中的更改：零值标志的 repr() 已更改。就是现在：：

>>> Color(0) class enum.IntFlag

IntFlag与Flag相同，但它的成员也是整数，并且可以在任何可以使用整数的地方使用。

>>> from enum import IntFlag, auto >>> class Color(IntFlag): ... RED = auto() ... GREEN = auto() ... BLUE = auto() ... >>> Color.RED & 2 >>> Color.RED | 2

如果使用 IntFlag 成员执行任何整数运算，则结果不是 IntFlag：

>>> Color.RED + 2 3

如果使用 IntFlag 成员执行 Flag 操作并且：

结果是一个有效的 IntFlag：返回一个 IntFlag 结果不是有效的 IntFlag：结果取决于 FlagBoundary 设置

未命名零值标志的 repr() 已更改。就是现在：

>>> Color(0)

Note

将 auto 与 IntFlag 一起使用会产生以 1 开头的 2 的幂的整数。

版本 3.11 中进行了更改： __str__() 现在为 int.__str__() ，以更好地支持替换现有常量用例。由于同样的原因， __format__() 已经成为 int.__format__() 。

IntFlag 的反转现在返回一个正值，该值是不在给定标志中的所有标志的并集，而不是负值。这与现有的 Flag 行为相匹配。

class enum.ReprEnum

ReprEnum 使用 Enum 的 repr() ，但混合数据类型的 str() ：

int.__str__() 适用于 IntEnum 和 IntFlag str.__str__() 换 StrEnum

继承自 ReprEnum 以保留混合数据类型的 str() / format() 而不是使用 Enum - 默认 str() 。

3.11 版本中的新功能。

class enum.EnumCheck

EnumCheck包含 verify() 装饰器用来确保各种约束的选项；失败的约束会导致 ValueError 。

UNIQUE

确保每个值只有一个名称：

>>> from enum import Enum, verify, UNIQUE >>> @verify(UNIQUE) ... class Color(Enum): ... RED = 1 ... GREEN = 2 ... BLUE = 3 ... CRIMSON = 1 Traceback (most recent call last): ... ValueError: aliases found in : CRIMSON -> RED CONTINUOUS

确保价值最低的成员和价值最高的成员之间不存在缺失值：

>>> from enum import Enum, verify, CONTINUOUS >>> @verify(CONTINUOUS) ... class Color(Enum): ... RED = 1 ... GREEN = 2 ... BLUE = 5 Traceback (most recent call last): ... ValueError: invalid enum 'Color': missing values 3, 4 NAMED_FLAGS

确保任何标志组/掩码仅包含命名标志 - 当指定值而不是由 auto() 生成时有用：

>>> from enum import Flag, verify, NAMED_FLAGS >>> @verify(NAMED_FLAGS) ... class Color(Flag): ... RED = 1 ... GREEN = 2 ... BLUE = 4 ... WHITE = 15 ... NEON = 31 Traceback (most recent call last): ... ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]

Note

CONTINUOUS 和 NAMED_FLAGS 旨在与整数值成员一起使用。

3.11 版本中的新功能。

class enum.FlagBoundary

FlagBoundary 控制 Flag 及其子类中如何处理超出范围的值。

STRICT

超出范围的值会导致 ValueError 升高。这是 Flag 的默认设置：

>>> from enum import Flag, STRICT, auto >>> class StrictFlag(Flag, boundary=STRICT): ... RED = auto() ... GREEN = auto() ... BLUE = auto() ... >>> StrictFlag(2**2 + 2**4) Traceback (most recent call last): ... ValueError: invalid value 20 given 0b0 10100 allowed 0b0 00111 CONFORM

超出范围的值已删除无效值，留下有效的标志值：

>>> from enum import Flag, CONFORM, auto >>> class ConformFlag(Flag, boundary=CONFORM): ... RED = auto() ... GREEN = auto() ... BLUE = auto() ... >>> ConformFlag(2**2 + 2**4) EJECT

超出范围的值将失去其标志成员身份并恢复为 int 。

>>> from enum import Flag, EJECT, auto >>> class EjectFlag(Flag, boundary=EJECT): ... RED = auto() ... GREEN = auto() ... BLUE = auto() ... >>> EjectFlag(2**2 + 2**4) 20 KEEP

超出范围的值将被保留，并且标志成员身份将被保留。这是 IntFlag 的默认设置：

>>> from enum import Flag, KEEP, auto >>> class KeepFlag(Flag, boundary=KEEP): ... RED = auto() ... GREEN = auto() ... BLUE = auto() ... >>> KeepFlag(2**2 + 2**4)

3.11 版本中的新功能。

支持的 __dunder__ 名称

__members__ 是 member_name : member 项的只读有序映射。它仅在课堂上可用。

__new__() ，如果指定，必须创建并返回枚举成员；适当设置会员的 _value_ 也是一个很好的主意。一旦创建了所有成员，就不再使用它。

支持的 _sunder_ 名称 _name_ – 会员姓名 _value_ ——会员价值；可以在 __new__ 中设置/修改 _missing_ – 未找到值时使用的查找函数；可能会被覆盖 _ignore_ – 名称列表，作为 list 或 str ，不会转换为成员，并将从最终类中删除 _order_ – 在 Python 2/3 代码中使用，以确保成员顺序一致（类属性，在类创建期间删除）

_generate_next_value_ – 用于获取枚举成员的适当值；可能会被覆盖

Note

对于标准 Enum 类，选择的下一个值是最后一个递增 1 的值。

对于 Flag 类别，选择的下一个值将是下一个最高的 2 的幂，无论最后看到的值是什么。

3.6版本新增： _missing_ 、 _order_ 、 _generate_next_value_

3.7版本新增： _ignore_

实用程序和装饰器 class enum.auto

auto 可以用来代替值。如果使用，Enum 机制将调用 Enum 的 _generate_next_value_() 来获取适当的值。对于 Enum 和 IntEnum，适当的值将是最后一个值加一；对于 Flag 和 IntFlag 来说，它将是第一个大于最高值的 2 的幂；对于 StrEnum 来说，它将是成员名称的小写版本。如果将 auto() 与手动指定的值混合使用，必须小心。

auto 实例仅在分配的顶层时才会解析：

FIRST = auto() 将工作（ auto() 替换为 1 ）； SECOND = auto(), -2 will work (auto is replaced with 2, so 2, -2 is

用于创建 SECOND 枚举成员；

THREE = [auto(), -3] 将不起作用（ , -3 用于创建 THREE 枚举成员）

版本 3.11.1 中的更改：在之前的版本中， auto() 必须是分配线上唯一能够正常工作的设备。

可以覆盖 _generate_next_value_ 以自定义 auto 使用的值。

Note

在 3.13 中，默认的 _generate_next_value_ 将始终返回递增 1 的最高成员值，如果任何成员是不兼容的类型，则会失败。

@enum.property

与内置属性类似的装饰器，但专门用于枚举。它允许成员属性与成员本身具有相同的名称。

Note

属性和成员必须在单独的类中定义；例如， value 和 name 属性在 Enum 类中定义，并且 Enum 子类可以定义名称为 value 和 name 的成员。

3.11 版本中的新功能。

@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 : FOUR -> THREE @enum.verify

专门用于枚举的 class 装饰器。 EnumCheck 中的成员用于指定应在修饰枚举上检查哪些约束。

3.11 版本中的新功能。

@enum.member

用于枚举的装饰器：它的目标将成为成员。

3.11 版本中的新功能。

@enum.nonmember

用于枚举的装饰器：它的目标不会成为成员。

3.11 版本中的新功能。

@enum.global_enum

一个装饰器，用于更改枚举的 str() 和 repr() ，以将其成员显示为属于模块而不是属于其类。仅当枚举成员导出到模块全局命名空间时才应使用（有关示例，请参阅 re.RegexFlag ）。

3.11 版本中的新功能。

enum.show_flag_values(value)

返回标志值中包含的所有二次方整数的列表。

3.11 版本中的新功能。

Notes

IntEnum 、 StrEnum 和 IntFlag

这三种枚举类型旨在替代现有的基于整数和字符串的值；因此，它们有额外的限制：

__str__ 使用值而不是枚举成员的名称 __format__ 因为它使用 __str__ ，所以也将使用枚举成员的值而不是其名称

如果您不需要/想要这些限制，您可以通过自己混合 int 或 str 类型来创建自己的基类：

>>> from enum import Enum >>> class MyIntEnum(int, Enum): ... pass

或者您可以在枚举中重新分配适当的 str() 等：

>>> from enum import Enum, IntEnum >>> class MyIntEnum(IntEnum): ... __str__ = Enum.__str__

【本文地址】

公司简介

联系我们