8.13. enum --- 列挙型のサポート

バージョン 3.4 で追加.

ソースコード: Lib/enum.py

---

列挙型は、一意の定数値に束縛された識別名 (メンバー) の集合です。列挙型の中でメンバーの同一性を比較でき、列挙型自身でイテレートが可能です。

8.13.1. モジュールコンテンツ

This module defines two enumeration classes that can be used to define unique sets of names and values: Enum and IntEnum. It also defines one decorator, unique().

class enum.Enum

列挙型定数を作成する基底クラスです。もうひとつの構築構文については 機能 API を参照してください。

class enum.IntEnum

int のサブクラスでもある列挙型定数を作成する基底クラスです。

enum.unique()

一つの名前だけがひとつの値に束縛されていることを保証する Enum クラスのデコレーターです。

8.13.2. Enum の作成

列挙型は読み書きが容易になるよう class 文を使って作成します。もうひとつの作成方法は 機能 API で説明しています。列挙型は以下のように Enum のサブクラスとして定義します:

>>> from enum import Enum
>>> class Color(Enum):
...     red = 1
...     green = 2
...     blue = 3
...

注釈

用語

• クラス Color は 列挙型 (または Enum) です
• The attributes Color.red, Color.green, etc., are enumeration members (or enum members).
• The enum members have names and values (the name of Color.red is red, the value of Color.blue is 3, etc.)

注釈

Enum の作成に class 文を使用するものの、Enum は通常の Python クラスではありません。詳細は Enum はどう違うのか? を参照してください。

列挙型のメンバーは人が読める文字列表現を持ちます:

>>> print(Color.red)
Color.red

...その一方でそれらの repr はより多くの情報を持っています:

>>> print(repr(Color.red))
<Color.red: 1>

列挙型メンバーの データ型 はそれが所属する列挙型になります:

>>> type(Color.red)
<enum 'Color'>
>>> isinstance(Color.green, Color)
True
>>>

Enum メンバーは自身の名前を持つだけのプロパティも持っています:

>>> print(Color.red.name)
red

列挙型は定義順でのイテレーションをサポートしています:

>>> class Shake(Enum):
...     vanilla = 7
...     chocolate = 4
...     cookies = 9
...     mint = 3
...
>>> for shake in Shake:
...     print(shake)
...
Shake.vanilla
Shake.chocolate
Shake.cookies
Shake.mint

列挙型のメンバーはハッシュ化可能なため、辞書や集合で使用できます:

>>> apples = {}
>>> apples[Color.red] = 'red delicious'
>>> apples[Color.green] = 'granny smith'
>>> apples == {Color.red: 'red delicious', Color.green: 'granny smith'}
True

8.13.3. 列挙型メンバーおよびそれらの属性へのプログラム的アクセス

Sometimes it's useful to access members in enumerations programmatically (i.e. situations where Color.red won't do because the exact color is not known at program-writing time). Enum allows such access:

>>> Color(1)
<Color.red: 1>
>>> Color(3)
<Color.blue: 3>

列挙型メンバーに 名前 でアクセスしたい場合はアイテムとしてアクセスできます:

>>> Color['red']
<Color.red: 1>
>>> Color['green']
<Color.green: 2>

列挙型メンバーの name か value が必要な場合:

>>> member = Color.red
>>> member.name
'red'
>>> member.value
1

8.13.4. 列挙型メンバーと値の重複

同じ名前の列挙型メンバーを複数持つことはできません:

>>> class Shape(Enum):
...     square = 2
...     square = 3
...
Traceback (most recent call last):
...
TypeError: Attempted to reuse key: 'square'

ただし、複数の列挙型メンバーが同じ値を持つことはできます。同じ値を持つ 2 つのメンバー A および B (先に定義したのは A) が与えられたとき、B は A の別名になります。A および B を値で調べたとき、A が返されます。B を名前で調べたとき、A が返されます:

>>> class Shape(Enum):
...     square = 2
...     diamond = 1
...     circle = 3
...     alias_for_square = 2
...
>>> Shape.square
<Shape.square: 2>
>>> Shape.alias_for_square
<Shape.square: 2>
>>> Shape(2)
<Shape.square: 2>

注釈

すでに定義されている属性と同じ名前のメンバー (一方がメンバーでもう一方がメソッド、など) の作成、あるいはメンバーと同じ名前の属性の作成はできません。

8.13.5. 番号付けの値が同一であることの確認

デフォルトでは、前述のように複数の名前への同じ値の定義は別名とすることで許されています。この挙動を望まない場合、以下のデコレーターを使用することで各値が列挙型内で一意かどうか確認できます:

@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

8.13.6. イテレーション

列挙型のメンバーのイテレートは別名をサポートしていません:

>>> list(Shape)
[<Shape.square: 2>, <Shape.diamond: 1>, <Shape.circle: 3>]

特殊属性 __members__ は名前をメンバーにマッピングする順序を記憶する辞書です。列挙型内で定義されたすべての名前を別名も含めて格納しています:

>>> for name, member in Shape.__members__.items():
...     name, member
...
('square', <Shape.square: 2>)
('diamond', <Shape.diamond: 1>)
('circle', <Shape.circle: 3>)
('alias_for_square', <Shape.square: 2>)

属性 __members__ は列挙型メンバーへの詳細なアクセスに使用できます。以下はすべての別名を探す例です:

>>> [name for name, member in Shape.__members__.items() if member.name != name]
['alias_for_square']

8.13.7. 比較

列挙型メンバーは同一性を比較できます:

>>> Color.red is Color.red
True
>>> Color.red is Color.blue
False
>>> Color.red is not Color.blue
True

列挙型の値の順序の比較はサポートされて いません。Enum メンバーは整数ではありません (IntEnum を参照してください):

>>> Color.red < Color.blue
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unorderable types: Color() < Color()

ただし等価の比較は定義されています:

>>> Color.blue == Color.red
False
>>> Color.blue != Color.red
True
>>> Color.blue == Color.blue
True

非列挙型の値との比較は常に不等となります (繰り返しになりますが、IntEnum はこれと異なる挙動になるよう設計されています):

>>> Color.blue == 2
False

8.13.8. 列挙型で許されるメンバーと属性

上述の例では列挙型の値に整数を使用しています。整数の使用は短くて使いやすい (そして 機能 API でデフォルトで提供されています) のですが、厳密には強制ではありません。ほとんどの事例では列挙型の実際の値が何かを気にしていません。しかし、値が重要で ある 場合、列挙型は任意の値を持つことができます。

列挙型は Python のクラスであり、通常どおりメソッドや特殊メソッドを持つことができます:

>>> class Mood(Enum):
...     funky = 1
...     happy = 3
...
...     def describe(self):
...         # self is the member here
...         return self.name, self.value
...
...     def __str__(self):
...         return 'my custom str! {0}'.format(self.value)
...
...     @classmethod
...     def favorite_mood(cls):
...         # cls here is the enumeration
...         return cls.happy
...

上記の結果が以下のようになります:

>>> Mood.favorite_mood()
<Mood.happy: 3>
>>> Mood.happy.describe()
('happy', 3)
>>> str(Mood.funky)
'my custom str! 1'

何が許されているかのルールは次のとおりです。先頭と末尾が 1 個のアンダースコアの名前は列挙型により予約されているため、使用できません。列挙型内で定義されたその他すべての名前は、その列挙型のメンバーとして使用できます。特殊メソッド (__str__(), __add__(), など) と、メソッドを含むデスクリプタ (記述子) は例外です。

注意: 列挙型で __new__() および/または __init__() を定義した場合、列挙型メンバーに与えられた値はすべてこれらのメソッドに渡されます。例 Planet を参照してください。

8.13.9. 列挙型のサブクラス化の制限事項

列挙型のサブクラスの作成はその列挙型にメンバーが一つも定義されていない場合のみ行なえます。従って以下は許されません:

>>> class MoreColor(Color):
...     pink = 17
...
Traceback (most recent call last):
...
TypeError: Cannot extend enumerations

以下のような場合は許されます:

>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     happy = 1
...     sad = 2
...

メンバーが定義された列挙型のサブクラス化を許可すると、いくつかのデータ型およびインスタンスの重要な不変条件の違反を引き起こします。とはいえ、それが許可されると、列挙型のグループ間での共通の挙動を共有するという利点もあります。 (OrderedEnum の例を参照してください。)

8.13.10. Pickle 化

列挙型は pickle 化と unpickle 化が行えます:

>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.tomato is loads(dumps(Fruit.tomato))
True

通常の pickle 化の制限事項が適用されます: pickle 可能な列挙型はモジュールのトップレベルで定義されていなくてはならず、unpickle 化はモジュールからインポート可能でなければなりません。

注釈

pickle プロトコルバージョン 4 では他のクラスで入れ子になった列挙型の pickle 化も容易です。

Enum メンバーをどう pickle 化/unpickle 化するかは、列挙型クラス内の __reduce_ex__() で定義することで変更できます。

8.13.11. 機能 API

Enum クラスは呼び出し可能で、以下の機能 API を提供しています:

>>> Animal = Enum('Animal', 'ant bee cat dog')
>>> Animal
<enum 'Animal'>
>>> Animal.ant
<Animal.ant: 1>
>>> Animal.ant.value
1
>>> list(Animal)
[<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>]

この API の動作は namedtuple と似ています。Enum 呼び出しの第 1 引数は列挙型の名前です。

第 2 引数は列挙型メンバー名の ソース です。空白で区切った名前の文字列、名前のシーケンス、キー/値のペアの 2 要素タプルのシーケンス、あるいは名前と値のマッピング (例: 辞書) を指定できます。最後の 2 個のオプションでは、列挙型へ任意の値を割り当てることができます。前の 2 つのオプションでは、1 から始まり増加していく整数を自動的に割り当てます (別の開始値を指定するには、start 引数を使用します)。Enum から派生した新しいクラスが返されます。言い換えれば、上記の Animal への割り当ては以下と等価です:

>>> class Animal(Enum):
...     ant = 1
...     bee = 2
...     cat = 3
...     dog = 4
...

デフォルトの開始番号が 0 ではなく 1 である理由は、0 がブール演算子では False になりますが、すべての列挙型メンバーの評価は True でなければならないためです。

機能 API による Enum の pickle 化は、その列挙型がどのモジュールで作成されたかを見つけ出すためにフレームスタックの実装の詳細が使われるので、トリッキーになることがあります (例えば別のモジュールのユーティリティ関数を使うと失敗しますし、IronPython や Jython ではうまくいきません)。解決策は、以下のようにモジュール名を明示的に指定することです:

>>> Animal = Enum('Animal', 'ant bee cat dog', module=__name__)

警告

module が与えられない場合、Enum はそれがなにか決定できないため、新しい Enum メンバーは unpickle 化できなくなります; エラーをソースの近いところで発生させるため、pickle 化は無効になります。

新しい pickle プロトコルバージョン 4 では、一部の状況において、pickle がクラスを発見するための場所の設定に __qualname__ を参照します。例えば、そのクラスがグローバルスコープ内のクラス SomeData 内で利用可能とするには以下のように指定します:

>>> Animal = Enum('Animal', 'ant bee cat dog', qualname='SomeData.Animal')

完全な構文は以下のようになります:

Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)

value:

新しい Enum クラスに記録されるそれ自身の名前です。

名前:

Enum のメンバーです。 空白またはカンマで区切った文字列でも構いません (特に指定がない限り、値は 1 から始まります):

'red green blue' | 'red,green,blue' | 'red, green, blue'

または名前のイテレータで指定もできます:

['red', 'green', 'blue']

または (名前, 値) のペアのイテレータでも指定できます:

[('cyan', 4), ('magenta', 5), ('yellow', 6)]

またはマッピングでも指定できます:

{'chartreuse': 7, 'sea_green': 11, 'rosemary': 42}

module:

新しい Enum クラスが属するモジュールの名前です。

qualname:

新しい Enum クラスが属するモジュールの場所です。

type:

新しい Enum クラスに複合されるデータ型です。

start:

names のみが渡されたときにカウントを開始する数です。

バージョン 3.5 で変更: start 引数が追加されました。

8.13.12. 派生列挙型

8.13.12.1. IntEnum

A variation of Enum is provided which is also a subclass of int. Members of an IntEnum can be compared to integers; by extension, integer enumerations of different types can also be compared to each other:

>>> from enum import IntEnum
>>> class Shape(IntEnum):
...     circle = 1
...     square = 2
...
>>> class Request(IntEnum):
...     post = 1
...     get = 2
...
>>> Shape == 1
False
>>> Shape.circle == 1
True
>>> Shape.circle == Request.post
True

ただし、これらも標準の Enum 列挙型とは比較できません:

>>> class Shape(IntEnum):
...     circle = 1
...     square = 2
...
>>> class Color(Enum):
...     red = 1
...     green = 2
...
>>> Shape.circle == Color.red
False

IntEnum の値は他の用途では整数のように振る舞います:

>>> int(Shape.circle)
1
>>> ['a', 'b', 'c'][Shape.circle]
'b'
>>> [i for i in range(Shape.square)]
[0, 1]

For the vast majority of code, Enum is strongly recommended, since IntEnum breaks some semantic promises of an enumeration (by being comparable to integers, and thus by transitivity to other unrelated enumerations). It should be used only in special cases where there's no other choice; for example, when integer constants are replaced with enumerations and backwards compatibility is required with code that still expects integers.

8.13.12.2. その他

IntEnum は enum モジュールの一部ですが、単独での実装もとても簡単に行なえます:

class IntEnum(int, Enum):
    pass

ここでは似たような列挙型の派生を定義する方法を紹介します; 例えば、StrEnum は int ではなく str で複合させたものです。

いくつかのルール:

1. Enum のサブクラスを作成するとき、複合させるデータ型は、基底クラスの並びで Enum 自身より先に記述しなければなりません (上記 IntEnum の例を参照)。
2. Enum のメンバーはどんなデータ型でも構いませんが、追加のデータ型 (例えば、上の例の int) と複合させてしまうと、すべてのメンバーの値はそのデータ型でなければならなくなります。 この制限は、メソッドの追加するだけの、 int や str のような他のデータ型を指定しない複合には適用されません。
3. 他のデータ型と複合された場合、 value 属性は、たとえ等価であり等価であると比較が行えても、列挙型メンバー自身としては 同じではありません 。
4. %-方式の書式: %s および %r はそれぞれ Enum クラスの __str__() および __repr__() を呼び出します; その他のコード (IntEnum の %i や %h など) は列挙型のメンバーを複合されたデータ型として扱います。
5. str.format() (or format()) will use the mixed-in type's __format__(). If the Enum class's str() or repr() is desired, use the !s or !r format codes.

8.13.13. 興味深い例

While Enum and IntEnum are expected to cover the majority of use-cases, they cannot cover them all. Here are recipes for some different types of enumerations that can be used directly, or as examples for creating one's own.

8.13.13.1. AutoNumber

Avoids having to specify the value for each enumeration member:

>>> class AutoNumber(Enum):
...     def __new__(cls):
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...
>>> class Color(AutoNumber):
...     red = ()
...     green = ()
...     blue = ()
...
>>> Color.green.value == 2
True

注釈

__new__() メソッドが定義されていれば、Enum 番号の作成時に使用されます; これは Enum の __new__() と置き換えられ、クラスが作成された後の既存の番号を取得に使用されます。

8.13.13.2. OrderedEnum

IntEnum をベースとしないため、通常の Enum の不変条件 (他の列挙型と比較できないなど) のままで、メンバーを順序付けできる列挙型です:

>>> class OrderedEnum(Enum):
...     def __ge__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value >= other.value
...         return NotImplemented
...     def __gt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value > other.value
...         return NotImplemented
...     def __le__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value <= other.value
...         return NotImplemented
...     def __lt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value < other.value
...         return NotImplemented
...
>>> class Grade(OrderedEnum):
...     A = 5
...     B = 4
...     C = 3
...     D = 2
...     F = 1
...
>>> Grade.C < Grade.A
True

8.13.13.3. DuplicateFreeEnum

値が同じメンバーが見つかった場合、別名を作るのではなく、エラーを送出します:

>>> class DuplicateFreeEnum(Enum):
...     def __init__(self, *args):
...         cls = self.__class__
...         if any(self.value == e.value for e in cls):
...             a = self.name
...             e = cls(self.value).name
...             raise ValueError(
...                 "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
...                 % (a, e))
...
>>> class Color(DuplicateFreeEnum):
...     red = 1
...     green = 2
...     blue = 3
...     grene = 2
...
Traceback (most recent call last):
...
ValueError: aliases not allowed in DuplicateFreeEnum:  'grene' --> 'green'

注釈

これは Enum に別名を無効にするのと同様な振る舞いの追加や変更をおこなうためのサブクラス化に役立つ例です。単に別名を無効にしたいだけなら、 unique() デコレーターを使用して行えます。

8.13.13.4. Planet

__new__() や __init__() が定義されている場合、列挙型メンバーの値はこれらのメソッドに渡されます:

>>> class Planet(Enum):
...     MERCURY = (3.303e+23, 2.4397e6)
...     VENUS   = (4.869e+24, 6.0518e6)
...     EARTH   = (5.976e+24, 6.37814e6)
...     MARS    = (6.421e+23, 3.3972e6)
...     JUPITER = (1.9e+27,   7.1492e7)
...     SATURN  = (5.688e+26, 6.0268e7)
...     URANUS  = (8.686e+25, 2.5559e7)
...     NEPTUNE = (1.024e+26, 2.4746e7)
...     def __init__(self, mass, radius):
...         self.mass = mass       # in kilograms
...         self.radius = radius   # in meters
...     @property
...     def surface_gravity(self):
...         # universal gravitational constant  (m3 kg-1 s-2)
...         G = 6.67300E-11
...         return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129

8.13.14. Enum はどう違うのか?

Enum は Enum 派生クラスやそれらのインスタンス (メンバー) 双方の多くの側面に影響を及ぼすカスタムメタクラスを持っています。

8.13.14.1. Enum クラス

EnumMeta メタクラスは、__contains__()、__dir__()、__iter__() および標準的なクラスでは失敗するが Enum クラスでは動作するその他のメソッド (list(Color) や some_var in Color など) を責任を持って提供します。EnumMeta は最終的な Enum クラスのさまざまなメソッド (__new__()、__getnewargs__()、__str__() および __repr__()) が正しいことを責任を持って保証します。

8.13.14.2. Enum メンバー (インスタンス)

Enum メンバーについて最も興味深いのは、それらがシングルトンであるということです。EnumMeta は Enum 自身を作成し、メンバーを作成し、新しいインスタンスが作成されていないかどうかを確認するために既存のメンバーインスタンスだけを返すカスタム __new__() を追加します。

8.13.14.3. 細かい点

Enum members are instances of an Enum class, and even though they are accessible as EnumClass.member, they should not be accessed directly from the member as that lookup may fail or, worse, return something besides the Enum member you looking for:

>>> class FieldTypes(Enum):
...     name = 0
...     value = 1
...     size = 2
...
>>> FieldTypes.value.size
<FieldTypes.size: 2>
>>> FieldTypes.size.value
2

バージョン 3.5 で変更.

The __members__ attribute is only available on the class.

Enum サブクラスに追加のメソッドを与えた場合、上述の Planet クラスのように、そのメソッドはメンバーの dir() に表示されますが、クラスの dir() には表示されません:

>>> dir(Planet)
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
>>> dir(Planet.EARTH)
['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']

The __new__() method will only be used for the creation of the Enum members -- after that it is replaced. Any custom __new__() method must create the object and set the _value_ attribute appropriately.

If you wish to change how Enum members are looked up you should either write a helper function or a classmethod() for the Enum subclass.