Python
PR

PythonのEnum(列挙型)の使い方|name・value・StrEnumを実例で解説

PythonのEnum(列挙型)の使い方|name・value・StrEnumを実例で解説
hr
記事内に商品プロモーションを含む場合があります

ユーザーの状態を "active"・"suspended" のような文字列で表していると、どこかで "actve" と打ち間違えても、エラーにならずに動き続けてしまいます。Python の Enum(イーナム、列挙型)を使うと、取りうる値を 1 か所にまとめて名前を付けられ、打ち間違いはすぐにエラーになります。標準ライブラリの enum モジュールに入っているので、インストールは不要です。

この記事では、Enum の基本(name と value、値や名前からメンバーを取り出す方法)、IntEnum・StrEnum との違い、auto()・@unique・Flag、JSON にするときのエラー、match 文や dataclass と組み合わせる例までを順に説明します。載せている出力は、Windows 11・Python 3.12.6 で実際に実行して確かめたものです。

文字列の定数で困ること

まず Enum を使わずに、「状態が active ならログインできる」という関数を書いてみます。次のコードを sample.py という名前で保存します。

def can_login(status):
    return status == "active"

print(can_login("active"))
print(can_login("actve"))

PowerShell で、sample.py を保存したフォルダーに移動してから実行します。

py sample.py
True
False

2 行目は打ち間違いなのに、エラーではなく「ログインできない(False)」という普通の結果が返っています。こうした間違いはテストで偶然見つかるまで気づけません。ほかにも、次のような困りごとがあります。

  • どんな値がありうるのか、コードのあちこちを探さないと分からない
  • 数値で表している場合(1=有効、2=停止 など)、if status == 2 を読んでも意味が分からない
  • エディターの入力補完が効かない

Enum で書き直す

同じ内容を Enum で書くと次のようになります。Enum を継承したクラスを作り、名前 = 値 の形で並べます。この 1 つ 1 つをメンバーと呼びます。名前は定数なので、慣習として大文字で書きます。

from enum import Enum

class Status(Enum):
    ACTIVE = "active"
    SUSPENDED = "suspended"
    DELETED = "deleted"

def can_login(status: Status) -> bool:
    return status is Status.ACTIVE

print(can_login(Status.ACTIVE))
print(Status.ACTVE)
True
Traceback (most recent call last):
  ...
AttributeError: type object 'Status' has no attribute 'ACTVE'. Did you mean: 'ACTIVE'?

打ち間違えた Status.ACTVE は、その行を実行した時点で AttributeError になり、「ACTIVE のことですか?」と候補まで出ます。ありうる値はクラスを見れば一覧でき、エディターでも Status. と打てば候補が表示されます。

なお、関数の引数に付けた status: Status は型ヒントで、実行時のチェックはしません。can_login("active") と文字列を渡すと、エラーにならずに False が返りました。型の間違いまで見つけたいときは、型チェッカーと組み合わせます(「Pythonの型ヒント入門」参照)。

メンバーの name と value

公式ドキュメントでは、Enum は「一意の値に結び付けられた、名前(メンバー)の集まり」と説明されています。メンバーは name(名前)と value(値)の 2 つを持ちます。色を例に確かめます。

from enum import Enum

class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

print(Color.RED)
print(repr(Color.RED))
print(Color.RED.name, Color.RED.value)
print(type(Color.RED))
print(Color(1))
print(Color["RED"])
Color.RED
<Color.RED: 1>
RED 1
<enum 'Color'>
Color.RED
Color.RED
  • Color.RED.name は名前の文字列 'RED'、Color.RED.value は値の 1
  • Color.RED 自体は 1 ではなく、Color 型のオブジェクト
  • Color(1) で値から、Color["RED"] で名前からメンバーを取り出せる。どちらも同じ Color.RED が返る
class Color(Enum) の中に Color.RED、Color.GREEN、Color.BLUE の 3 つのメンバーがあり、それぞれ name が RED・GREEN・BLUE、value が 1・2・3 の組を持つ。名前 RED からも値 1 からも同じメンバーを取り出せる
図 1:Enum クラスとメンバー(name と value の組)

Color(1) は、データベースや設定ファイルから読んだ数値・文字列を Enum に変換するときに使います。Color["RED"] は、画面やコマンドラインで名前を受け取るときに便利です。

存在しない値・名前を指定したとき

どちらも、ないものを指定するとエラーになります。種類が違う点に注意してください。

書き方出たエラー
Color(5)ValueError: 5 is not a valid Color
Color["PINK"]KeyError: 'PINK'

外から来た値を変換するときは、try・except ValueError で受け止めて「不正な値です」と知らせると安全です(「Pythonの例外処理入門」参照)。大文字小文字も区別されるので、Status("ACTIVE") は ValueError: 'ACTIVE' is not a valid Status になりました(値は小文字の “active” のため)。

エラーを出さずに「その値があるか」だけ調べたいときは、in が使えます。Python 3.12 で "active" in Status を実行すると True、"actve" in Status は False でした。公式ドキュメントには「Python 3.12 より前は、メンバーでないものを in で調べると TypeError になる」とあるので、3.11 以前では Status(s) を try で囲む方法を使います。

for で順に取り出す・len で数える

Enum クラスはそのまま for で回せます。順番は書いた順です。

print(len(Color))
for c in Color:
    print(c.name, c.value)
print(list(Color))
3
RED 1
GREEN 2
BLUE 3
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]

プルダウンの選択肢を作る、ヘルプに使える値を並べる、といった場面で使えます。また、メンバーはあとから書き換えられません。Color.RED = 5 は AttributeError: cannot reassign member 'RED' になりました。

比較は is か ==。生の値とは等しくならない

公式の Enum HOWTO には「メンバーは同一性(is)で比較される」とあります。メンバーはそれぞれ 1 つしか作られないので、is でも == でも正しく比べられます。注意したいのは、普通の Enum のメンバーは、元の値(1 や “active”)とは == で等しくならないことです。一方、IntEnum と StrEnum(Python 3.11 で追加)は、メンバーが int や str としても振る舞うので等しくなります。

from enum import Enum, IntEnum, StrEnum

class Color(Enum):
    RED = 1

class Priority(IntEnum):
    LOW = 1
    HIGH = 2

class Status(StrEnum):
    ACTIVE = "active"

print(Color.RED == 1, Color.RED.value == 1, Color.RED is Color.RED)
print(Priority.LOW == 1, Priority.HIGH > Priority.LOW, Priority.LOW + 10)
print(Status.ACTIVE == "active", Status.ACTIVE.upper())
print(f"{Color.RED} / {Priority.LOW} / {Status.ACTIVE}")
False True True
True True 11
True ACTIVE
Color.RED / 1 / active
種類生の値と ==大小の比較f 文字列での表示向いている場面
EnumFalse(.value で比べる)できない(TypeError)Color.RED基本はこれ。うっかり数値・文字列と混ざらない
IntEnumTrueできる1既存の数値定数を置き換える、優先度のように大小がある
StrEnum(3.11〜)True文字列として比較active文字列を受け取る既存の関数・JSON とやり取りする

普通の Enum で Color.RED < Color.GREEN と書くと、TypeError: '<' not supported between instances of 'Color' and 'Color' になりました。IntEnum では Priority.LOW + 10 が 11 になるように、計算結果は Enum ではなくただの数値になります(公式ドキュメントにも「整数の演算をすると結果は列挙型でなくなる」とあります)。f 文字列での表示が値になるのは、Python 3.11 で IntEnum の __str__ が int のものに変わったためです。

便利そうに見えますが、IntEnum・StrEnum は「別の種類の値と間違えて比べてもエラーにならない」という、文字列定数と同じ弱点を一部持ち込みます。公式の Enum HOWTO でも、新しいコードでは Enum と Flag を強く勧め、IntEnum・IntFlag は「整数の定数を置き換えるときや、ほかのシステムとやり取りするときなど、Enum では足りない場合だけ」に使うよう書かれています。

auto() で値を自動で付ける

値そのものに意味がなく、区別できればよいだけなら、auto() で値を自動で振れます。

from enum import Enum, StrEnum, auto

class Weekday(Enum):
    MONDAY = auto()
    TUESDAY = auto()
    WEDNESDAY = auto()

class Level(StrEnum):
    DEBUG = auto()
    INFO = auto()

print(list(Weekday))
print(list(Level))
[<Weekday.MONDAY: 1>, <Weekday.TUESDAY: 2>, <Weekday.WEDNESDAY: 3>]
[<Level.DEBUG: 'debug'>, <Level.INFO: 'info'>]

公式ドキュメントによると、auto() が付ける値は、Enum と IntEnum では「それまでの最大値+1」、Flag では「次の 2 の累乗」、StrEnum では「メンバー名を小文字にしたもの」です。ただし、値をデータベースやファイルに保存する場合は、auto() は避けて値を直接書くほうが安全です。途中にメンバーを足すと、後ろのメンバーの値がずれてしまい、保存済みのデータと合わなくなるためです。

値が重複すると「別名」になる。@unique で防ぐ

値をコピーして貼り付けたときなどに、うっかり同じ値を 2 回書いてしまうことがあります。Enum はこれをエラーにせず、あとのメンバーを前のメンバーの別名(エイリアス)として扱います。

from enum import Enum

class Status(Enum):
    ACTIVE = 1
    SUSPENDED = 2
    DELETED = 2

print(Status.DELETED)
print(Status.DELETED is Status.SUSPENDED)
print(list(Status))
print(list(Status.__members__))
Status.SUSPENDED
True
[<Status.ACTIVE: 1>, <Status.SUSPENDED: 2>]
['ACTIVE', 'SUSPENDED', 'DELETED']

Status.DELETED を指定したのに Status.SUSPENDED が返り、for で回しても DELETED は出てきません。「削除済みのユーザー」が「停止中」として扱われる、気づきにくいバグになります。別名をすべて含めた一覧は __members__ で見られます。

重複を許したくないときは、クラスに @unique デコレーターを付けます。重複があると、クラスを作った時点で止まります。

from enum import Enum, unique

@unique
class Status(Enum):
    ACTIVE = 1
    SUSPENDED = 2
    DELETED = 2
Traceback (most recent call last):
  ...
ValueError: duplicate values found in <enum 'Status'>: DELETED -> SUSPENDED

「DELETED が SUSPENDED と重複している」と教えてくれます。値を手で書く Enum には、付けておくと安心です。@ の仕組みは「Pythonのデコレーター入門」で解説しています。

メソッドやプロパティを足す

Enum もクラスなので、メソッドを書けます。メソッドの中の self は各メンバーです。値をタプルにして __init__ で受け取ると、メンバーごとに複数の情報を持たせることもできます。

from enum import Enum

class Plan(Enum):
    FREE = ("無料", 0)
    PRO = ("プロ", 980)

    def __init__(self, label, price):
        self.label = label
        self.price = price

    @property
    def is_paid(self):
        return self.price > 0

    def describe(self):
        return f"{self.label}プラン(月 {self.price} 円)"

for p in Plan:
    print(p.name, p.value, p.is_paid, p.describe())
FREE ('無料', 0) False 無料プラン(月 0 円)
PRO ('プロ', 980) True プロプラン(月 980 円)

value はタプル全体になり、label と price で個別に取り出せます。「有料かどうか」のような判定を Enum の中にまとめておくと、if plan == Plan.PRO or ... のような条件がコードのあちこちに散らばらずに済みます。

Flag で組み合わせを表す

「読み取り+書き込み」のように、複数を同時に選べる設定には Flag を使います。Flag のメンバーは |(または)でまとめられ、in で「含まれているか」を調べられます。

from enum import Flag, auto

class Perm(Flag):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

print([(p.name, p.value) for p in Perm])
rw = Perm.READ | Perm.WRITE
print(rw)
print(rw.value)
print(Perm.WRITE in rw, Perm.EXECUTE in rw)
rw |= Perm.EXECUTE
print(rw)
[('READ', 1), ('WRITE', 2), ('EXECUTE', 4)]
Perm.READ|WRITE
3
True False
Perm.READ|WRITE|EXECUTE

auto() で 1・2・4 と 2 の累乗が振られ、READ|WRITE は 1+2=3 という 1 つの値になります。中身は 2 進数のビットの組み合わせで、Linux のファイル権限(r=4、w=2、x=1)と同じ考え方です。ビットの仕組みは「ビット演算の基本」で詳しく解説しています。

JSON にするときは .value を使う

普通の Enum のメンバーは、そのままでは json.dumps に渡せません。

import json
from enum import Enum

class Color(Enum):
    RED = 1

print(json.dumps({"color": Color.RED.value}))
json.dumps({"color": Color.RED})
{"color": 1}
Traceback (most recent call last):
  ...
TypeError: Object of type Color is not JSON serializable

.value を付けて値を渡せば JSON にできます。一方、IntEnum・StrEnum は int・str の仲間なので、そのまま渡しても数値・文字列として書き出されました。JSON から読み込んだ値は、Status(data["status"]) で Enum に戻せます。

import json
from enum import IntEnum, StrEnum

class Priority(IntEnum):
    HIGH = 2

class Status(StrEnum):
    ACTIVE = "active"

print(json.dumps({"priority": Priority.HIGH, "status": Status.ACTIVE}))
data = json.loads('{"status": "active"}')
print(repr(Status(data["status"])))
{"priority": 2, "status": "active"}
<Status.ACTIVE: 'active'>

json モジュールの使い方は「PythonでJSONを扱う方法」を参照してください。書き出した JSON の形を確かめたいときは、JSON整形ツールに貼り付けると、インデントを付けて見やすく表示できます。

match 文と組み合わせる

Python 3.10 から使える match 文では、case Status.ACTIVE: のようにメンバーをそのまま書けます。| で複数のメンバーをまとめることもできます。

from enum import Enum

class Status(Enum):
    ACTIVE = "active"
    SUSPENDED = "suspended"
    DELETED = "deleted"

def message(status: Status) -> str:
    match status:
        case Status.ACTIVE:
            return "ログインできます"
        case Status.SUSPENDED | Status.DELETED:
            return "ログインできません"

for s in Status:
    print(s.value, message(s))
active ログインできます
suspended ログインできません
deleted ログインできません

if・elif を並べるより、どの状態でどうなるかが一目で分かります。for で全メンバーを回して結果を確かめると、メンバーを追加したときの書き漏れにも気づけます(書き漏れたメンバーでは、この関数は何も返さず None になります)。

dataclass や型ヒントと一緒に使う

dataclass のフィールドの型に Enum を使うと、「この項目に入るのは決まった値のどれか」がクラスの定義から分かるようになります。

from dataclasses import dataclass, asdict
from enum import Enum
import json

class Status(Enum):
    ACTIVE = "active"
    SUSPENDED = "suspended"

@dataclass
class User:
    name: str
    status: Status = Status.ACTIVE

u = User("田中")
print(u)
d = asdict(u)
print(d)
d["status"] = d["status"].value
print(json.dumps(d, ensure_ascii=False))
print(User("佐藤", Status("suspended")))
User(name='田中', status=<Status.ACTIVE: 'active'>)
{'name': '田中', 'status': <Status.ACTIVE: 'active'>}
{"name": "田中", "status": "active"}
User(name='佐藤', status=<Status.SUSPENDED: 'suspended'>)

Enum のメンバーは変更できない値なので、status: Status = Status.ACTIVE のように既定値にそのまま書けます(リストのように default_factory を使う必要はありません)。asdict は Enum を値に変えてくれないため、JSON にする前に .value に置き換えています。dataclass の基本は「Pythonのdataclassの使い方」で解説しています。

よくある間違い

書いたコード起きること直し方
if status == "active":(status は Enum)常に False になるstatus is Status.ACTIVE か status.value == "active"
Color("RED")ValueError(”RED” は値ではなく名前)名前からなら Color["RED"]
値の重複あとのメンバーが別名になり、for にも出ない@unique を付ける
json.dumps(Color.RED)TypeErrorColor.RED.value を渡す
保存する値に auto()途中にメンバーを足すと値がずれる値を直接書く

よくある質問

StrEnum が使えないと言われます

StrEnum は Python 3.11 で追加されたので、3.10 以前では ImportError になります。py --version でバージョンを確かめてください。古いバージョンでは、class Status(str, Enum): のように str と Enum を両方継承する書き方がよく使われますが、f 文字列での表示が StrEnum と異なります。Python 3.12 で試すと、class S(str, Enum) のメンバーは f"{S.A}" が S.A になり、StrEnum では値の active になりました(どちらも == "active" は True)。

Enum と辞書(dict)はどう使い分けますか?

「取りうる値が決まっていて、プログラムの中で名前で区別したい」なら Enum、「キーがあとから増える・外から読み込む」なら辞書が向いています。Enum の定数に表示名などの情報を付けたいときは、上の Plan の例のようにメソッドやタプルの値を使えます。辞書の基本は「Pythonのリスト・辞書・内包表記の基本」を参照してください。

まとめ

  • Enum は決まった値の集まりに名前を付ける仕組み。打ち間違いはすぐ AttributeError になる
  • メンバーは name と value を持つ。値からは Color(1)、名前からは Color["RED"]
  • 普通の Enum は生の値と == で等しくならない。IntEnum・StrEnum は等しくなる
  • 値の重複は別名になるので @unique で防ぐ。組み合わせには Flag
  • JSON にするときは .value を使う

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました