"enum" --- 对枚举的支持
***********************

Added in version 3.4.

**源代码：** Lib/enum.py


Important
^^^^^^^^^

此页面仅包含 API 参考信息。教程信息和更多高级用法的讨论，请参阅

* 基础教程

* 进阶教程

* 枚举指南

======================================================================

一个枚举：

* 是绑定到唯一值的符号名称（成员）集合

* 可以被执行迭代以按定义顺序返回其规范的（即非别名的）成员

* 使用 *调用* 语法按值返回成员

* 使用 *索引* 语法按名称返回成员

枚举是通过使用 "class" 语法或是通过使用函数调用语法来创建的:

   >>> from enum import Enum

   >>> # 类语法
   >>> class Color(Enum):
   ...     RED = 1
   ...     GREEN = 2
   ...     BLUE = 3

   >>> # 函数语法
   >>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])

虽然我们可以使用 "class" 语法来创建枚举，但枚举并不是常规的 Python 类
。请参阅 枚举有什么不同？ 了解更多细节。

备注:

  命名法

  * 类 "Color" 是一个 *枚举* （或 *enum* ）

  * 属性 "Color.RED"、 "Color.GREEN" 等是 *枚举成员* （或 *members* ）
    并且在功能上是常量。

  * 枚举成员有 *名称* 和 *值* ("Color.RED" 的名称是 "RED"，
    "Color.BLUE" 的值是 "3"，等等)

======================================================================


模块内容
========

   "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" 的枚举，允许对枚举
      中无效值的处理方式进行更细粒度的控制。

   "EnumDict"

      一个被用于子类化 "EnumType" 的 "dict" 子类。

   "auto"

      实例被替换为枚举成员的适当值。 "StrEnum" 默认为成员名称的小写版
      本，而其他枚举默认为 1 并由此递增。

   "property()"

      允许 "Enum" 成员拥有属性而不会与成员名称相冲突。"value" 和
      "name" 属性都是以这样的方式实现的。

   "unique()"

      确保一个名称只绑定一个值的 Enum 类装饰器。

   "verify()"

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

   "member()"

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

   "nonmember()"

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

   "global_enum()"

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

   "show_flag_values()"

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

   "enum.bin()"

      与内置的 "bin()" 类似，区别在于负值将以补码表示，并且打头的比特
      位总是指明正负性 ("0" 表示正值，"1" 表示负值)。

Added in version 3.6: "Flag", "IntFlag", "auto"

Added in version 3.11: "StrEnum", "EnumCheck", "ReprEnum",
"FlagBoundary", "property", "member", "nonmember", "global_enum",
"show_flag_values"

Added in version 3.13: "EnumDict"

======================================================================


数据类型
========

class enum.EnumType

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

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

   Added in version 3.11: 在 3.11 之前 "EnumType" 被称为 "EnumMeta"，
   该名称作为别名仍然可用。

   __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:
              枚举的第一个整数值（由 "auto" 使用）。

           边界:
              如何处理来自位操作的超出范围的值 (仅限 "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 之前，如果在包含检测中使用
      了非枚举成员则会引发 "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* 中匹配 *name* 的 Enum 成员，或者引发 "KeyError":

         >>> Color['BLUE']
         <Color.BLUE: 3>

   __iter__(cls)

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

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

   __len__(cls)

      返回 *cls* 中成员的数量:

         >>> len(Color)
         3

   __members__

      返回一个从每个枚举名称到其成员的映射，包括别名

   __reversed__(cls)

      按定义的逆序返回 *cls* 中的每个成员:

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

class enum.Enum

   *Enum* 是所有 *enum* 枚举的基类。

   name

      用于定义 "Enum" 成员的名称:

         >>> Color.BLUE.name
         'BLUE'

   value

      赋给 "Enum" 成员的值:

         >>> Color.RED.value
         1

      成员的值，可在 "__new__()" 中设置。

      备注:

        Enum 成员值成员值可以为任意类型："int", "str" 等等。如果具体的
        值不重要则你可以使用 "auto" 实例这将为你选择一个适当的值。详情
        参见 "auto"。虽然可以使用可变/不可哈希的值，比如 "dict",
        "list" 或是可变的 "dataclass"，但它们在创建期间会产生基于枚举
        中可变/不可哈希的值总数量的二次方级性能影响。

   _name_

      成员的名称。

   _value_

      成员的值，可在 "__new__()" 中设置。

   _order_

      已不再使用，保留以便向下兼容。 （类属性，在类创建期间移除）。

      The "_order_" attribute can be provided to help keep Python 2 /
      Python 3 code in sync. It will be checked against the actual
      order of the enumeration and raise an error if the two do not
      match:

         >>> 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_" 属性是必须的，因为定义顺序在被记
        录之前就已丢失。

      Added in version 3.6.

   _ignore_

      "_ignore_" 仅在创建期间使用并会在创建完成后立即从枚举中移除。

      "_ignore_" 是由不会被作为成员的名称组成的列表，并且这些名称还将
      从完成的枚举中移除。请参阅 TimePeriod 获取示例。

      Added in version 3.7.

   __dir__(self)

      返回 "['__class__', '__doc__', '__module__', 'name', 'value']"
      以及在 *self.__class__* 上定义的任何公有方法:

         >>> from enum import Enum
         >>> import datetime as dt
         >>> class Weekday(Enum):
         ...     MONDAY = 1
         ...     TUESDAY = 2
         ...     WEDNESDAY = 3
         ...     THURSDAY = 4
         ...     FRIDAY = 5
         ...     SATURDAY = 6
         ...     SUNDAY = 7
         ...     @classmethod
         ...     def today(cls):
         ...         print(f'today is {cls(dt.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:
            Enum 的起始值；默认为 1。

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

         last_values:
            由前面的值组成的列表。

      A *staticmethod* that is used to determine the next value
      returned by "auto".

      备注:

        对于标准的 "Enum" 类来说下一个被选择的值将是已有的最高值加一。
        对于 "Flag" 类来说下一个选择的值将是下一个最高的二的幂数。

      此函数可以被重写，例如:

         >>> from enum import auto, Enum
         >>> 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

      Added in version 3.6.

      在 3.13 版本发生变更: 在之前版本中将会使用最近的值而不是最高的值
      。

   __init__(self, *args, **kwds)

      在默认情况下，将不做任何事。如果在成员赋值时给出了多个值，这些值
      将成为传给 "__init__" 的单独参数；例如

      >>> from enum import Enum
      >>> class Weekday(Enum):
      ...     MONDAY = 1, 'Mon'

      "Weekday.__init__()" 将以 "Weekday.__init__(self, 1, 'Mon')" 的
      形式被调用

   __init_subclass__(cls, **kwds)

      一个用来进一步配置后续子类的 *类方法*。在默认情况下，将不做任何
      事。

   _missing_(cls, value)

      一个用来查找不存在于 *cls* 中的值的 *类方法*。在默认情况下它将不
      做任何事，但可以被重写以实现自定义的搜索行为:

         >>> from enum import auto, 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')
         <Build.DEBUG: 'debug'>

      Added in version 3.6.

   __new__(cls, *args, **kwds)

      在默认情况下，将不会存在。如果指定，则或是在枚举类定义中或是在混
      入类定义中 (比如 "int")，在成员赋值时给出的所有值都将被传递；例
      如

      >>> from enum import Enum
      >>> class MyIntEnum(int, Enum):
      ...     TWENTYSIX = '1a', 16

      将导致调用 "int('1a', 16)" 并使该成员的值为 "26"。

      备注:

        当编写自定义的 "__new__" 时，不要使用 "super().__new__" -- 而
        要调用适当的 "__new__"。

   __repr__(self)

      返回用于 *repr()* 调用的字符串。在默认情况下，将返回 *Enum* 名称
      、成员名称和值，但也可以被重写:

         >>> from enum import auto, Enum
         >>> 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()* 调用的字符串。在默认情况下，返回 *Enum* 名称和
      成员名称，但也可以被重写:

         >>> from enum import auto, Enum
         >>> 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}"
         (<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')

   __format__(self)

      返回用于 *format()* 和 *f-string* 调用的字符串。在默认情况下，将
      返回 "__str__()" 的返回值，但也可以被重写:

         >>> from enum import auto, Enum
         >>> 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: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')

   备注:

     将 "auto" 用于 "Enum" 将得到递增的整数值，从 "1" 开始。

   在 3.12 版本发生变更: Added 数据类支持

   _add_alias_()

      添加一个新名称作为现有成员的别名:

         >>> Color.RED._add_alias_("ERROR")
         >>> Color.ERROR
         <Color.RED: 1>

      如果该名称已被分配给另一个成员则会引发 "NameError"。

      Added in version 3.13.

   _add_value_alias_()

      添加一个新值作为现有成员的别名:

         >>> Color.RED._add_value_alias_(42)
         >>> Color(42)
         <Color.RED: 1>

         如果该值已被链接到另一个成员则会引发 "ValueError"。
         参阅 MultiValueEnum 的示例。

      Added in version 3.13.

class enum.IntEnum

   *IntEnum* 和 "Enum" 是一样的，但其成员还属于整数并可被用在任何可以
   使用整数的地方。如果对一个 *IntEnum* 成员执行整数运算，结果值将失去
   其枚举状态。

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

   备注:

     将 "auto" 用于 "IntEnum" 将得到递增的整数值，从 "1" 开始。

   在 3.11 版本发生变更: "__str__()" 现在是 "int.__str__()" 以更好地支
   持 *现有常量的替换* 应用场景。 出于同样的原因 "__format__()" 也已经
   是 "int.__format__()"。

class enum.StrEnum

   *StrEnum* 和 "Enum" 是一样的，但其成员还属于字符串并可被用在任何可
   以使用字符串的地方。如果对一个 *StrEnum* 成员执行字符串操作其结果值
   将不再是该枚举的一部分。

   >>> from enum import StrEnum, auto
   >>> class Color(StrEnum):
   ...     RED = 'r'
   ...     GREEN = 'g'
   ...     BLUE = 'b'
   ...     UNKNOWN = auto()
   ...
   >>> Color.RED
   <Color.RED: 'r'>
   >>> Color.UNKNOWN
   <Color.UNKNOWN: 'unknown'>
   >>> str(Color.UNKNOWN)
   'unknown'

   备注:

     在标准库中有些地方会检查是否是真正的 "str" 而不是 "str" 的子类 (
     例如使用 "type(unknown) == str" 而不是 "isinstance(unknown,
     str)")，在这些地方你将需要使用 "str(MyStrEnum.MY_MEMBER)".

   备注:

     将 "auto" 用于 "StrEnum" 将得到小写形式的成员名称字符串值。

   备注:

     "__str__()" 是 "str.__str__()" 以更好地支持 *现有常量的替换* 应用
     场景。 出于同样的原因 "__format__()" 也是 "str.__format__()"。

   Added in version 3.11.

class enum.Flag

   "Flag" 与 "Enum" 的相同，但其成员支持按位运算符 "&" (*AND*), "|"
   (*OR*), "^" (*XOR*) 和 "~" (*INVERT*)；这些运算的结果都是枚举成员（
   的别名）。

   __contains__(self, value)

      如果 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)
         [<Color.RED: 1>]
         >>> list(purple)
         [<Color.RED: 1>, <Color.BLUE: 4>]

      Added in version 3.11.

   __len__(self):

      返回旗标中成员的数量:

         >>> len(Color.GREEN)
         1
         >>> len(white)
         3

      Added in version 3.11.

   __bool__(self):

      如果旗标中有成员则返回 *True*，否则返回 *False*:

         >>> bool(Color.GREEN)
         True
         >>> bool(white)
         True
         >>> black = Color(0)
         >>> bool(black)
         False

   __or__(self, other)

      返回当前旗标与另一个旗标执行二进制或运算的结果:

         >>> Color.RED | Color.GREEN
         <Color.RED|GREEN: 3>

   __and__(self, other)

      返回当前旗标与另一个旗标执行二进制与运算的结果:

         >>> purple & white
         <Color.RED|BLUE: 5>
         >>> purple & Color.GREEN
         <Color: 0>

   __xor__(self, other)

      返回当前旗标与另一个旗标执行二进制异或运算的结果:

         >>> purple ^ white
         <Color.GREEN: 2>
         >>> purple ^ Color.GREEN
         <Color.RED|GREEN|BLUE: 7>

   __invert__(self):

      返回 *type(self)* 中所有不在 *self* 中的旗标:

         >>> ~white
         <Color: 0>
         >>> ~purple
         <Color.GREEN: 2>
         >>> ~Color.RED
         <Color.GREEN|BLUE: 6>

   _numeric_repr_()

      用于格式化任何其他未命名数字值的函数。默认为数字值的 repr；常见
      的选择有 "hex()" 和 "oct()"。

   备注:

     将 "auto" 用于 "Flag" 将得到二的整数次方，从 "1" 开始。

   在 3.11 版本发生变更: 零值旗标的 *repr()* 已被修改。现在将是：

   >>> Color(0)
   <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: 0>
   >>> Color.RED | 2
   <Color.RED|GREEN: 3>

   如果对一个 *IntFlag* 成员执行任何整数运算，结果将不再是一个
   *IntFlag*:

      >>> Color.RED + 2
      3

   如果对一个 *IntFlag* 成员执行 "Flag" 操作并且：

   * 结果是一个合法的 *IntFlag*: 将返回一个 *IntFlag*

   * 其结果将不是合法的 *IntFlag*: 具体结果将取决于 "FlagBoundary" 设
     置

   未命名旗标的 "repr()" 已被修改。现在将是:

      >>> Color(0)
      <Color: 0>

   备注:

     将 "auto" 用于 "IntFlag" 将得到二的整数次方，从 "1" 开始。

   在 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()"。

   Added in version 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 <enum 'Color'>: 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]

   备注:

     CONTINUOUS 和 NAMED_FLAGS 被设计用于配合整数值成员。

   Added in version 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: <flag 'StrictFlag'> invalid value 20
             given 0b0 10100
           allowed 0b0 00111

   CONFORM

      超出范围的值将导致无效的值被移除，保留有效的 "Flag" 值:

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

   EJECT

      超出范围的值将失去其 "Flag" 成员资格并转换为 "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

      超出范围的值将被保留，"Flag" 成员资格也将被保留。这是 "IntFlag"
      的默认设置:

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

   Added in version 3.11.

class enum.EnumDict

   *EnumDict* 是一个用作定义枚举类的命名空间的 "dict" 子类 (参见 准备
   类命名空间)。 它被对外公开以允许 "EnumType" 的子类具有高级行为如每
   个成员可包含多个值。 它在调用时应当传入被创建的枚举类的名称，否则私
   有名称和内部类将无法被正确地处理。

   请注意只有 "MutableMapping" 接口 ("__setitem__()" 和 "update()") 会
   被重写。有可能使用其他 "dict" 操作如 "|=" 来绕过此项检查。

   member_names

      由成员名称组成的列表。

   Added in version 3.13.

======================================================================


支持的 "__dunder__" 名称
------------------------

"__members__" 是由 "member_name":"member" 条目组成的只读有序映射。 它
只在类上可用。

"__new__()", if specified, must create and return the enum members; it
is also a very good idea to set the member's "_value_" appropriately.
Once all the members are created it is no longer used.


支持的 "_sunder_" 名称
----------------------

* "_name_" -- 成员的名称

* "_value_" -- 成员的值；可在 "__new__" 中设置

* "_missing_()" -- 当未找到某个值时所使用的查找函数；可被重写

* "_ignore_" -- 一个名称列表，可以为 "list" 或 "str"，它不会被转化为成
  员，并将从最终类中移除

* "_order_" -- 已不再使用，保留以便向下兼容（类属性，在类创建期间移除
  ）

* "_generate_next_value_()" -- 用于为枚举成员获取适当的值；可被重写

* "_add_alias_()" -- 添加一个新名称作为现有成员的别名。

* "_add_value_alias_()" -- 添加一个新值作为现有成员的别名。

* 虽然 "_sunder_" 名称通常被保留用于 "Enum" 类的后续开发因而不可被使用
  ，但有一些则被显式地允许：

  * "_repr_*" (例如 "_repr_html_")，用于 IPython's rich display

Added in version 3.6: "_missing_", "_order_", "_generate_next_value_"

Added in version 3.7: "_ignore_"

Added in version 3.13: "_add_alias_", "_add_value_alias_", "_repr_*"

======================================================================


Utilities and decorators
========================

class enum.auto

   *auto* can be used in place of a value.  If used, the *Enum*
   machinery will call an "Enum"'s "_generate_next_value_()" to get an
   appropriate value. For "Enum" and "IntEnum" that appropriate value
   will be the last value plus one; for "Flag" and "IntFlag" it will
   be the first power-of-two greater than the highest value; for
   "StrEnum" it will be the lower-cased version of the member's name.
   Care must be taken if mixing *auto()* with manually specified
   values.

   *auto* 实例仅会在赋值操作的最高层级上作为本身或元组的一部分被解析。

   * "FIRST = auto()" 将是可用的 (auto() 会被替换为 "1");

   * "SECOND = auto(), -2" 将是可用的 (auto 会被替换为 "2"，因此将使用
     "2, -2" 来创建 "SECOND" 枚举成员；

   * "THREE = [auto(), -3]" will *not* work ("[<auto instance>, -3]"
     is used to create the "THREE" enum member)

   在 3.11.1 版本发生变更: 在之前的版本中，"auto()" 必须为赋值行中唯一
   的内容才是可用的。

   "_generate_next_value_" 可以被重写以便自定义 *auto* 所使用的值。

   备注:

     in 3.13 the default "_generate_next_value_" will always return
     the highest member value incremented by 1, and will fail if any
     member is an incompatible type.

@enum.property

   一个类似于内置 *property* 的装饰器，但是专用于枚举。它允许成员属性
   具有与成员自身相同的名称。

   备注:

     the *property* and the member must be defined in separate
     classes; for example, the *value* and *name* attributes are
     defined in the *Enum* class, and *Enum* subclasses can define
     members with the names "value" and "name".

   Added in version 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 <enum 'Mistake'>: FOUR -> THREE

@enum.verify

   一个专用于枚举的 "class" 装饰器。将使用来自 "EnumCheck" 的成员指明
   应当在被装饰的枚举上检查哪些约束。

   Added in version 3.11.

@enum.member

   一个在枚举中使用的装饰器：它的目标将成为一个成员。

   Added in version 3.11.

@enum.nonmember

   一个在枚举中使用的装饰器：它的目标将不会成为一个成员。

   Added in version 3.11.

@enum.global_enum

   一个修改枚举的 "str()" 和 "repr()" 来将其成员显示为属于模块而不是类
   的装饰器。 应当仅在枚举成员被导出到模块全局命名空间时（请参看
   "re.RegexFlag" 获取示例）使用。

   Added in version 3.11.

enum.show_flag_values(value)

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

   Added in version 3.11.

enum.bin(num, max_bits=None)

   与内置的 "bin()" 类似，区别在于负值将以补码表示，并且打头的比特位总
   是指明正负性 ("0" 表示正值，"1" 表示负值)。

   >>> import enum
   >>> enum.bin(10)
   '0b0 1010'
   >>> enum.bin(~10)   # ~10 is -11
   '0b1 0101'

   Added in version 3.11.

======================================================================


备注
====

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