enum
--- 列挙型のサポート¶
バージョン 3.4 で追加.
ソースコード: Lib/enum.py
列挙型とは:
一意の値に紐付けられたシンボリックな名前の集合です
反復可能であり、定義順にその正規の(エイリアスでない)メンバーを返します
値を渡してメンバーを返すために、 呼び出し 構文を使用します
名前を受け取ってメンバーを返すために、 インデックス 構文を使用します
列挙型は、class
構文を使用するか、関数呼び出し構文を使用して作成されます:
>>> from enum import Enum
>>> # class syntax
>>> class Color(Enum):
... RED = 1
... GREEN = 2
... BLUE = 3
>>> # functional syntax
>>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])
Enum の作成に class
文を使用できるものの、Enum は通常の Python クラスではありません。詳細は Enum はどう違うのか? を参照してください。
注釈
用語
クラス
Color
は 列挙型 (または Enum) です属性
Color.RED
,Color.GREEN
などは 列挙型のメンバー (または メンバー) で、機能的には定数です。列挙型のメンバーは 名前 と 値 を持ちます (
Color.RED
の名前はRED
、Color.BLUE
の値は3
など。)
モジュールコンテンツ¶
Enumおよびそのサブクラスのための
type
です。列挙型定数を作成する基底クラスです。
列挙型定数を作成する基底クラスで、ビット演算を使って組み合わせられ、その結果も
IntFlag
メンバーになります。
CONTINUOUS
、NAMED_FLAGS
、UNIQUE
の値を持つ列挙型です。verify()
と共に使用して、指定された列挙型がさまざまな制約を満たしていることを確認します。An enumeration with the values
STRICT
,CONFORM
,EJECT
, andKEEP
which allows for more fine-grained control over how invalid values are dealt with in an enumeration.インスタンスは列挙型のメンバーに適切な値で置き換えられます。
StrEnum
ではデフォルトの値がメンバー名を小文字にしたものですが、その他の列挙型のデフォルトは1から連番で増加する値となります。メンバー名との競合を避けながら
Enum
メンバーに属性を持たせます。value
属性とname
属性はこの方法で実装されます。一つの名前だけがひとつの値に束縛されていることを保証する Enum クラスのデコレーターです。
Enum class decorator that checks user-selectable constraints on an enumeration.
obj
をメンバーにします。デコレータとして使用できます。
obj
をメンバーにしません。デコレータとして使用できます。フラグに含まれる、全ての2の累乗の整数のリストを返します。
バージョン 3.6 で追加: Flag
, IntFlag
, auto
バージョン 3.11 で追加: StrEnum
, EnumCheck
, ReprEnum
, FlagBoundary
, property
, member
, nonmember
, global_enum
, show_flag_values
データ型¶
- class enum.EnumType¶
EnumType は enum 列挙型の メタクラス です。 EnumType のサブクラスを作成することが可能です -- 詳細は EnumTypeのサブクラスを作る を参照してください。
EnumType は、 enum に
__repr__()
、__str__()
、__format__()
、および__reduce__()
メソッドを正しく設定し、また、enum メンバーを作成したり、重複を適切に処理したり、enum クラスのイテレーション機能を提供するなどの責務を持ちます。- __call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
このメソッドは2つの異なる方法で呼び出されます。
既存のメンバーを検索する:
- cls:
呼び出されるenumクラス。
- value:
検索する値。
cls
を使って新しい列挙型を作成する(既存の列挙型がメンバーを持たない場合のみ):
- __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__']
- __iter__(cls)¶
Returns each member in cls in definition order:
>>> list(Color) [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
- __len__(cls)¶
cls 内のメンバーの数を返します。:
>>> len(Color) 3
- __members__¶
Returns a mapping of every enum name to its member, including aliases
- __reversed__(cls)¶
cls 内の各メンバー を定義順の逆順で返します:
>>> list(reversed(Color)) [<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]
バージョン 3.11 で追加: 3.11 以前は
enum
はEnumMeta
型を使用していました。これはエイリアスとして保持されています。
- class enum.Enum¶
Enum は全ての enum 列挙型の基底クラスです。
- name¶
Enum
メンバーを定義するために使用される名前:>>> Color.BLUE.name 'BLUE'
- value¶
Enum
メンバーに与えられた値:>>> Color.RED.value 1
Value of the member, can be set in
__new__()
.注釈
列挙型のメンバー値
メンバー値は何であっても構いません:
int
,str
などなど。 正確な値が重要でない場合は、auto
インスタンスを使っておくと、適切な値が選ばれます。 詳細はauto
を参照してください。While mutable/unhashable values, such as
dict
,list
or a mutabledataclass
, can be used, they will have a quadratic performance impact during creation relative to the total number of mutable/unhashable values in the enum.
- _name_¶
Name of the member.
- _order_¶
No longer used, kept for backward compatibility. (class attribute, removed during class creation).
- _ignore_¶
_ignore_
は列挙の作成中にのみ使用され、作成が完了すると削除されます。_ignore_
は、メンバーにならず、作成された列挙から削除される名前のリストです。例については、TimePeriod を参照してください。
- __dir__(self)¶
Returns
['__class__', '__doc__', '__module__', 'name', 'value']
and any public methods defined on self.__class__:>>> 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:
Enumの開始値。デフォルトは1です。
- count:
定義済みのメンバーの数。現在のメンバーを含めない。
- last_values:
定義済みの値のリスト。
auto
によって返される次の値を決定するために使用される staticmethod です:>>> 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__(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)¶
cls で見つからない値を検索するための classmethod です。デフォルトでは何もしませんが、カスタムの検索の振る舞いを実装するためにオーバーライドすることができます:
>>> 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') <Build.DEBUG: 'debug'>
- __new__(cls, *args, **kwds)¶
デフォルトでは存在しません。指定された場合、列挙型のクラス定義またはmix-inクラス(例えば
int
など)のいずれかで、メンバーに代入されたすべての値が渡されます。例:>>> from enum import Enum >>> class MyIntEnum(Enum): ... SEVENTEEN = '1a', 16
results in the call
int('1a', 16)
and a value of17
for the member.- ..note:: When writing a custom
__new__
, do not usesuper().__new__
-- call the appropriate
__new__
instead.
- ..note:: When writing a custom
- __repr__(self)¶
repr() の呼び出しに使用される文字列を返します。デフォルトでは、 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 の名前とメンバーの名前を返しますが、オーバーライドすることもできます:
>>> 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__()
の戻り値を返しますが、オーバーライドすることもできます。:>>> 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')
バージョン 3.12 で変更: データクラスのサポート の追加
- 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
バージョン 3.11 で変更:
__str__()
は、既存の定数を置き換えるユースケースをより良くサポートするためにint.__str__()
に変更されました。同じ理由で、__format__()
は既にint.__format__()
に変更されています。
- class enum.StrEnum¶
StrEnum は Enum と同じですが、そのメンバーは文字列でもあり、ほとんどの文字列が使用できる場所で使用することができます。 StrEnum のメンバーに対して行われる文字列操作の結果は列挙の一部ではありません。
注釈
標準ライブラリの中には、
str
の代わりにstr
のサブクラス(つまり、type(unknown) == str
の代わりにisinstance(unknown, str)
)を厳密にチェックする場所があります。そのような場所では、str(StrEnum.member)
を使用する必要があります。注釈
__str__()
は 既存の定数の置換 ユースケースをより良くサポートするためにstr.__str__()
となりました。__format__()
も同様に、同じ理由でstr.__format__()
となりました。バージョン 3.11 で追加.
- class enum.Flag¶
Flag
はEnum
と同じですが、そのメンバーはビット単位演算子&
(論理積)、|
(論理和)、^
(排他的論理和)、 および~
(反転) をサポートしています。これらの演算の結果は列挙型のメンバーです。- __contains__(self, value)¶
値を含む場合に 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):
flag 内のメンバーの数を返します:
>>> len(Color.GREEN) 1 >>> len(white) 3
- __bool__(self):
メンバーがflagに含まれている場合は 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) に含まれる、それ自身以外の全てのフラグを返します:
>>> ~white <Color: 0> >>> ~purple <Color.GREEN: 2> >>> ~Color.RED <Color.GREEN|BLUE: 6>
- _numeric_repr_()¶
Function used to format any remaining unnamed numeric values. Default is the value's repr; common choices are
hex()
andoct()
.
バージョン 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
Flag と IntFlag メンバーの演算が行われた場合:
結果が有効な IntFlag: IntFlag が返されます
結果が有効でない IntFlag: 結果は FlagBoundary の設定に依存します
値が0のフラグの repr() は変更されました。現在は以下のとおりです:
>>> Color(0) <Color: 0>
バージョン 3.11 で変更:
__str__()
は、既存の定数を置き換えるユースケースをより良くサポートするためにint.__str__()
に変更されました。同じ理由で、__format__()
は既にint.__format__()
に変更されています。IntFlag
の反転は、与えられたフラグ以外のすべてのフラグの結合となる正の値を返すようになりました。これは既存のFlag
の振る舞いに一致します。
- class enum.ReprEnum¶
ReprEnum
uses therepr()
ofEnum
, but thestr()
of the mixed-in data type:ReprEnum
を継承することで、Enum
デフォルトのstr()
を使用する代わりに、mix-inされたデータ型のstr()
/format()
を使用します。バージョン 3.11 で追加.
- class enum.EnumCheck¶
EnumCheck には
verify()
デコレータやさまざまな制約を保証するために使用されるオプションが含まれています。制約に違反するとValueError
が発生します。- UNIQUE¶
それぞれの値が1つの名前しか持たないことを確認します:
>>> 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>
バージョン 3.11 で追加.
__dunder__
名のサポート¶
__members__
は読み込み専用の、 member_name
:member
を要素とする順序付きマッピングです。これはクラスでのみ利用可能です。
__new__()
が、もし指定されていた場合、列挙型のメンバーを作成し、返します;
そのメンバー の _value_
を適切に設定するのも非常によい考えです。
いったん全てのメンバーが作成されると、それ以降 __new__()
は使われません。
_sunder_
名のサポート¶
_name_
-- name of the member_value_
-- value of the member; can be set in__new__
_missing_()
-- a lookup function used when a value is not found; may be overridden_ignore_
-- a list of names, either as alist
or astr
, that will not be transformed into members, and will be removed from the final class_order_
-- no longer used, kept for backward compatibility (class attribute, removed during class creation)_generate_next_value_()
-- used to get an appropriate value for an enum member; may be overridden
バージョン 3.6 で追加: _missing_
, _order_
, _generate_next_value_
バージョン 3.7 で追加: _ignore_
ユーティリティとデコレータ¶
- class enum.auto¶
auto は値の代わりに使用できます。使用すると、適切な値を取得するために*Enum* の
_generate_next_value_()
メソッドが呼び出されます。 Enum と IntEnum の場合、値は最後の値に1を加えたものになります。 Flag と IntFlag の場合、最大値より大きい最初の2の累乗になります。StrEnum の場合、メンバーの名前の小文字バージョンになります。手動で指定する値と auto() を混在させる場合は注意が必要です。auto インスタンスは、代入のトップレベルでのみ解決されます。
FIRST = auto()
は動作します(auto() は1
に置き換えられます)SECOND = auto(), -2
は動作します(auto は2
に置き換えられるため、SECOND
列挙型のメンバーには2, -2
が使用されます)THREE = [auto(), -3]
は動作 しません (enumメンバーTHREE
の作成に<auto instance>, -3
が使用されます)
バージョン 3.11.1 で変更: 以前のバージョンでは、
auto()
は、代入行に他のものがあると正しく動作しませんでした。_generate_next_value_
は、 auto が使用する値をカスタマイズするためにオーバーライドすることができる。注釈
3.13では、デフォルトの
_generate_next_value_
は常に最も高いメンバーの値に1を加えたものを返し、メンバーのいずれかが比較できない型である場合には失敗します。
- @enum.property¶
A decorator similar to the built-in property, but specifically for enumerations. It allows member attributes to have the same names as members themselves.
注釈
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
andname
.バージョン 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¶
A decorator to change the
str()
andrepr()
of an enum to show its members as belonging to the module instead of its class. Should only be used when the enum members are exported to the module global namespace (seere.RegexFlag
for an example).バージョン 3.11 で追加.
- enum.show_flag_values(value)¶
フラグの value に含まれる全ての2の累乗の整数のリストを返します。
バージョン 3.11 で追加.
注釈¶
これらの3つの列挙型は、既存の整数ベースおよび文字列ベースの値の代替として設計されています。そのため、追加の制限があります:
__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__