`enum` --- 對列舉的支援¶

在 3.4 版被加入.

列舉：

是一組綁定唯一值的代表名稱（成員）
可以用疊代的方式以定義的順序回傳其正式 (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()

與內建的 bin() 類似，但負值以二補數表示，且前導位元永遠表示正負號（0 表示正，1 表示負）。

在 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 中的每個成員：

enum --- 對列舉的支援¶

模組內容¶

資料型別¶

`enum` --- 對列舉的支援¶