"enum" --- 對列舉的支援
***********************

在 3.4 版被加入.

**原始碼：**Lib/enum.py


Important
^^^^^^^^^

本頁包含 API 的參考資訊。關於教學資訊及更多進階主題的討論請參考

* 基本教學

* 進階教學

* 列舉指南

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

列舉：

* 是一組綁定唯一值的代表名稱（成員）

* 可以用疊代的方式以定義的順序回傳其正式 (canonical)（即非別名）成員

* 使用 *call* 語法來透過值回傳成員

* 使用 *index* 語法來透過名稱回傳成員

列舉透過 "class" 語法或函式呼叫的語法來建立：

   >>> from enum import Enum

   >>> # class 語法
   >>> 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" 等屬性是*列舉成員*（或*成員*），並且使
    用上可以看作常數。

  * 列舉成員有*名稱*和*值*（"Color.RED" 的名稱是 "RED"，"Color.BLUE"
    的值是 "3" 諸如此類）

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


模組內容
========

   "EnumType"

      Enum 及其子類別的 "type"。

   "Enum"

      用來建立列舉常數的基礎類別。

   "IntEnum"

      用來建立列舉常數的基礎類別，同時也是 "int" 的子類別。（備註）

   "StrEnum"

      用來建立列舉常數的基礎類別，同時也是 "str" 的子類別。（備註）

   "Flag"

      用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不
      失去 "Flag" 的成員資格。

   "IntFlag"

      用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不
      失去 "IntFlag" 的成員資格。"IntFlag" 的成員也是 "int" 的子類別。
      （備註）

   "ReprEnum"

      由 "IntEnum"、"StrEnum" 及 "IntFlag" 所使用來保留這些混合型別的
      "str()"。

   "EnumCheck"

      一個有 "CONTINUOUS"、"NAMED_FLAGS" 及 "UNIQUE" 這些值的列舉，和
      "verify()" 一起使用來確保給定的列舉符合多種限制。

   "FlagBoundary"

      一個有 "STRICT"、"CONFORM"、"EJECT" 及 "KEEP" 這些值的列舉，允許
      列舉對如何處理非法值做更細微的控制。

   "EnumDict"

      "dict" 的子類別，用於當作 "EnumType" 的子類別時使用。

   "auto"

      列舉成員的實例會被取代成合適的值。"StrEnum" 預設是小寫版本的成員
      名稱，其它列舉則預設是 1 且往後遞增。

   "property()"

      允許 "Enum" 成員擁有屬性且不會與成員名稱有衝突。"value" 及
      "name" 屬性是用這個方式來實作。

   "unique()"

      Enum 類別的裝飾器，用來確保任何值只有綁定到一個名稱上。

   "verify()"

      Enum 類別的裝飾器，用來檢查列舉上使用者所選的限制。

   "member()"

      讓 "obj" 變成成員。可以當作裝飾器使用。

   "nonmember()"

      不讓 "obj" 變成成員。可以當作裝飾器使用。

   "global_enum()"

      修改列舉上的 "str()" 及 "repr()" ，讓成員顯示為屬於模組而不是類
      別，並將該列舉成員匯出到全域命名空間。

   "show_flag_values()"

      回傳旗標 (flag) 裡包含的所有 2 的次方的整數串列。

   "enum.bin()"

      Like built-in "bin()", except negative values are represented in
      two's complement, and the leading bit always indicates sign ("0"
      implies positive, "1" implies negative).

在 3.6 版被加入: "Flag", "IntFlag", "auto"

在 3.11 版被加入: "StrEnum", "EnumCheck", "ReprEnum", "FlagBoundary",
"property", "member", "nonmember", "global_enum", "show_flag_values"

在 3.13 版被加入: "EnumDict"

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


資料型別
========

class enum.EnumType

   *EnumType* 是 *enum* 列舉的 *metaclass*。*EnumType* 可以有子類別 --
   細節請參考 建立 EnumType 的子類別。

   "EnumType" 負責在最後的*列舉*上面設定正確的 "__repr__()"、
   "__str__()"、"__format__()" 及 "__reduce__()" 方法，以及建立列舉成
   員、正確處理重複、提供列舉類別的疊代等等。

   在 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" 所使用）

           boundary:
              在位元操作時怎麼處理範圍外的值（只有 "Flag" 會用到）

   __contains__(cls, member)

      如果 member 屬於 "cls" 則回傳 "True"：

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

      在 3.12 版的變更: 在 Python 3.12 之前，如果用非列舉成員做屬於檢
      查 (containment check) 會引發 "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* 的列舉成員，或引發 "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__()" 設定。

      備註:

        列舉成員的值成員的值可以是任何值："int"、"str" 等等。如果實際
        使用什麼值並不重要，你可以使用 "auto" 實例，它會為你選擇合適的
        值。更多細節請參考 "auto"。雖然可以使用可變的 (mutable) / 不可
        雜湊的 (unhashable) 值，例如 "dict"、"list" 或可變的
        "dataclass"，它們在建立期間會對效能產生相對於列舉中可變的 / 不
        可雜湊的值總數量的二次方影響。

   _name_

      成員名稱。

   _value_

      成員的值，可以在 "__new__()" 設定。

   _order_

      已不再使用，只為了向後相容而保留（類別屬性，在類別建立時移除）

   _ignore_

      "_ignore_" 只有在建立的時候用到，在列舉建立完成後會被移除。

      "_ignore_" 是一個不會變成成員的名稱串列，在列舉建立完成後其名稱
      會被移除。範例請參考 TimePeriod。

   __dir__(self)

      回傳 "['__class__', '__doc__', '__module__', 'name', 'value']"
      及任何 *self.__class__* 上定義的公開方法：

         >>> from enum import Enum
         >>> 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:
            一個之前值的串列。

      一個 *staticmethod*，用來決定 "auto" 下一個要回傳的值的：

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

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

      一個 *classmethod*，用來進一步設定後續的子類別，預設不做任何事。

   _missing_(cls, value)

      一個 *classmethod*，用來查詢在 *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'>

   __new__(cls, *args, **kwds)

      預設情況下不存在。如果有指定，無論是在列舉類別定義中還是在 mixin
      類別中（例如 "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')

   備註:

     "Enum" 使用 "auto" 會產生從 "1" 開始遞增的整數。

   在 3.12 版的變更: 新增 Dataclass support

   _add_alias_()

      新增一個名稱作為現有成員的別名：

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

      如果該名稱已經被指派給不同的成員，則會引發 "NameError"。

      在 3.13 版被加入.

   _add_value_alias_()

      新增一個值作為現有成員的別名：

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

      如果該值已經被連結到不同的成員，則會引發 "ValueError"。

      在 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

   備註:

     "IntEnum" 使用 "auto" 會產生從 "1" 開始遞增的整數。

   在 3.11 版的變更: 為了更好地支援*現存常數取代 (replacement of
   existing constants)* 的使用情境，"__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'

   備註:

     stdlib 裡有些地方會檢查只能是 "str" 而不是 "str" 的子類別（也就是
     "type(unknown) == str" 而不是 "isinstance(unknown, str)"），在這
     些地方你需要使用 "str(MyStrEnum.MY_MEMBER)"。

   備註:

     "StrEnum" 使用 "auto" 會產生小寫的成員名稱當作值。

   備註:

     為了更好地支援*現存常數取代 (replacement of existing constants)*
     的使用情境，"__str__()" 現在會是 "str.__str__()"。為了同樣的理由
     ，"__format__()" 也會是 "str.__format__()"。

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

      在 3.11 版被加入.

   __len__(self):

      回傳旗標裡的成員數量：

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

      在 3.11 版被加入.

   __bool__(self):

      如果成員在旗標裡則回傳 *True*，否則回傳 *False*：

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

   __or__(self, other)

      回傳和 other 做 OR 過後的二進位旗標：

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

   __and__(self, other)

      回傳和 other 做 AND 過後的二進位旗標：

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

   __xor__(self, other)

      回傳和 other 做 XOR 過後的二進位旗標：

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

   備註:

     "Flag" 使用 "auto" 會產生從 "1" 開始 2 的次方的整數。

   在 3.11 版的變更: 值為 0 的旗標的 *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" 的設定

   未命名且值為 0 的旗標的 "repr()" 已改變。現在是：

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

   備註:

     "IntFlag" 使用 "auto" 會產生從 "1" 開始 2 的次方的整數。

   在 3.11 版的變更: 為了更好地支援*現存常數取代 (replacement of
   existing constants)* 的使用情境，"__str__()" 現在會是
   "int.__str__()"。為了同樣的理由，"__format__()" 已經是
   "int.__format__()"。"IntFlag" 的反轉 (inversion) 現在會回傳正值，該
   值是不在給定旗標的所有旗標聯集，而不是一個負值。這符合現有 "Flag"
   的行為。

class enum.ReprEnum

   "ReprEnum" 使用 "Enum" 的 "repr()"，但使用混合資料型別的 "str()"：

   * 對 "IntEnum" 和 "IntFlag" 是 "int.__str__()"

   * 對 "StrEnum" 是 "str.__str__()"

   繼承 "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 <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 是設計用來運作在整數值的成員上。

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

   在 3.11 版被加入.

class enum.EnumDict

   *EnumDict* 是 "dict" 的子類別，用來作為定義列舉類別的命名空間（參見
   Preparing the class namespace）。它被公開來使得 "EnumType" 的子類別
   能具有進階行為，例如讓每個成員有多個值。它應該在被呼叫時帶上正在建
   立的列舉類別名稱，否則私有名稱和內部類別將無法被正確處理。

   注意只有 "MutableMapping" 介面（"__setitem__()" 和 "update()"）被覆
   寫。可能可以使用其他 "dict" 操作來繞過檢查，例如 "|="。

   member_names

      一個成員名稱的串列。

   在 3.13 版被加入.

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


支援的 "__dunder__" 名稱
------------------------

"__members__" 是一個唯讀有序的"成員名稱"："成員"項目的對映。只有在類別
上可用。

"__new__()"，如果有指定，它必須建立並回傳列舉成員；適當地設定成員的
"_value_" 也是一個很好的主意。一旦所有成員都建立之後就不會再被用到。


支援的 "_sunder_" 名稱
----------------------

* "_name_" -- 成員名稱

* "_value_" -- 成員的值；可以在 "__new__" 設定

* "_missing_()" -- 當值沒有被找到時會使用的查詢函式；可以被覆寫

* "_ignore_" -- 一個名稱的串列，可以是 "list" 或 "str"，它不會被轉換成
  成員，且在最後的類別上會被移除

* "_order_" -- 不再被使用，僅為了向後相容而保留（類別屬性，在類別建立
  時移除）

* "_generate_next_value_()" -- 用來為列舉成員取得合適的值；可以被覆寫

  備註:

    對標準的 "Enum" 類別來說，下一個被選擇的值是所看過的最大值加一。對
    "Flag" 類別來說，下一個被選擇的值是下一個最大的 2 的次方的數字。

* "_add_alias_()" -- 新增一個名稱作為現有成員的別名。

* "_add_value_alias_()" -- 新增一個值作為現有成員的別名。

* 雖然 "_sunder_" 名稱通常保留用於 "Enum" 類別的進一步開發而不能被使用
  ，但有些是明確允許的：

  * "_repr_*"（例如 "_repr_html_"），例如用於 IPython 的豐富顯示

在 3.6 版被加入: "_missing_"、"_order_"、"_generate_next_value_"

在 3.7 版被加入: "_ignore_"

在 3.13 版被加入: "_add_alias_"、"_add_value_alias_"、"_repr_*"

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


通用項目與裝飾器
================

class enum.auto

   *auto* 可以用來取代給值。如果使用的話，*Enum* 系統會呼叫 "Enum" 的
   "_generate_next_value_()" 來取得合適的值。對 "Enum" 和 "IntEnum" 來
   說，合適的值是最後一個值加一；對 "Flag" 和 "IntFlag" 來說，是第一個
   比最大值還大的 2 的次方的數字；對 "StrEnum" 來說，是成員名稱的小寫
   版本。如果混用 *auto()* 和手動指定值的話要特別注意。

   *auto* 實例只有在最上層的賦值時才會被解析，不論是獨自一個或作為元組
   的一部分：

   * "FIRST = auto()" 可以運作（auto() 會被取代成 "1"）

   * "SECOND = auto(), -2" 可以運作（auto 會被取代成 "2", 因此 "2, -2"
     會被用來建立列舉成員 "SECOND"；

   * "THREE = [auto(), -3]" *無法*運作（"[<auto instance>, -3]" 會被用
     來建立列舉成員 "THREE"）

   在 3.11.1 版的變更: 在之前的版本中，"auto()" 必須是賦值行裡的唯一內
   容才能運作正確。

   可以覆寫 "_generate_next_value_" 來客製 *auto* 使用的值。

   備註:

     在 3.13 預設 "_generate_next_value_" 總是回傳最大的成員值加一，如
     果任何成員是不相容的型別就會失敗。

@enum.property

   和內建的 *property* 相似的裝飾器，但只專門針對列舉。它允許成員屬性
   和成員本身有相同名稱。

   備註:

     *屬性*和成員必須定義在分開的類別裡；例如 *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 <enum 'Mistake'>: 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)

   回傳在旗標*值*中包含的所有 2 的次方的整數串列。

   在 3.11 版被加入.

enum.bin(num, max_bits=None)

   Like built-in "bin()", except negative values are represented in
   two's complement, and the leading bit always indicates sign ("0"
   implies positive, "1" implies negative).

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

   在 3.10 版被加入.

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


備註
====

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