Pythonのdataclassの使い方|既定値・frozen・asdictを実例で解説
「名前と年齢を持つユーザー」「x と y を持つ座標」のように、いくつかの値をひとまとめにするクラスを作ることはよくあります。Python の dataclass(データクラス)を使うと、こうしたクラスを数行で書けます。Python 3.7 から標準で入っているので、インストールは不要です。
この記事では、普通のクラスと比べて何が楽になるのかを確かめたあと、既定値の書き方、field(default_factory=list) が必要な理由、frozen・order・__post_init__、JSON への変換、slots・kw_only、継承でつまずくエラーまでを順に説明します。載せている出力は、Windows 11・Python 3.12.6 で実際に実行して確かめたものです。
普通のクラスで書くと何が面倒か
まず、dataclass を使わずに「名前と年齢を持つユーザー」を作ってみます。次のコードを sample.py という名前で保存します。
class User:
def __init__(self, name, age):
self.name = name
self.age = age
u1 = User("田中", 25)
u2 = User("田中", 25)
print(u1)
print(u1 == u2)
PowerShell で、sample.py を保存したフォルダーに移動してから実行します。
py sample.py
<__main__.User object at 0x000002222D0E2DB0>
False
困る点が 2 つあります(0x で始まる数字は実行するたびに変わります)。
printしても中身が見えない。デバッグのときに不便です- 中身が同じでも
==がFalseになる。普通のクラスの==は「同じオブジェクトかどうか」を比べるためです
これを直すには、表示用の __repr__ と比較用の __eq__ を自分で書く必要があります。
class User:
def __init__(self, name: str, age: int):
self.name = name
self.age = age
def __repr__(self):
return f"User(name={self.name!r}, age={self.age!r})"
def __eq__(self, other):
if not isinstance(other, User):
return NotImplemented
return (self.name, self.age) == (other.name, other.age)
項目が 2 つでもこの長さです。項目を 1 つ増やすたびに、__init__・__repr__・__eq__ の 3 か所を直さなければならず、1 か所でも忘れるとバグになります。
dataclass の基本の書き方
同じクラスを dataclass で書くと次のようになります。クラスの上に @dataclass を付け、項目名: 型 の形で並べるだけです。この 1 つ 1 つの項目をフィールドと呼びます。
from dataclasses import dataclass
@dataclass
class User:
name: str
age: int
u1 = User("田中", 25)
u2 = User("田中", 25)
print(u1)
print(u1 == u2)
print(u1.name, u1.age)
u1.age = 26
print(u1)
print(u1 == u2)
User(name='田中', age=25)
True
田中 25
User(name='田中', age=26)
False
@dataclass が、書いたフィールドをもとに __init__・__repr__・__eq__ を自動で作ってくれます。== はフィールドの値を上から順に比べます。値はあとから書き換えることもできます。
型ヒントは必須、ただしチェックはされない
name: str の : str の部分を型ヒントといいます。dataclass は型ヒントが付いた変数だけをフィールドとして扱うので、型ヒントは省略できません。ただし、実行時に型が正しいかどうかは確かめません。次のように int のはずの age に文字列を入れても、エラーにならずにそのまま入ります。
from dataclasses import dataclass
@dataclass
class User:
name: str
age: int = 20
active: bool = True
print(User("佐藤"))
print(User("鈴木", 30, active=False))
print(User(name="高橋", age="三十"))
User(name='佐藤', age=20, active=True)
User(name='鈴木', age=30, active=False)
User(name='高橋', age='三十', active=True)
このコードでは、= 20 のように書いて既定値(省略したときに使う値)も付けています。dataclass を提案した PEP 557 でも、型ヒントを実行時に調べる仕組みはないと書かれています。型の間違いを見つけたいときは mypy などの型チェッカーを使うか、後で説明する __post_init__ で自分で確かめます。
リストを既定値にするときは field(default_factory=list)
「チームのメンバー一覧」のように、既定値を空のリストにしたいことがあります。素直に = [] と書くと、クラスを作った時点でエラーになります。
from dataclasses import dataclass
@dataclass
class Team:
name: str
members: list = []
Traceback (most recent call last):
...
ValueError: mutable default <class 'list'> for field members is not allowed: use default_factory
「変更できる(mutable な)値を既定値にしてはいけない。default_factory を使え」という意味です。正しくは、field(default_factory=list) と書きます。default_factory には「既定値を作る関数」を渡し、インスタンス(クラスから作った 1 つ 1 つのデータ)を作るたびに呼び出されます。
from dataclasses import dataclass, field
@dataclass
class Team:
name: str
members: list[str] = field(default_factory=list)
a = Team("開発")
b = Team("営業")
a.members.append("田中")
print(a)
print(b)
Team(name='開発', members=['田中'])
Team(name='営業', members=[])
なぜエラーにしてまで止めるのかは、普通の関数で同じことをすると分かります。次は dataclass を使わず、members=[] を引数の既定値にした例です。
class Team:
def __init__(self, name, members=[]):
self.name = name
self.members = members
a = Team("開発")
b = Team("営業")
a.members.append("田中")
print(a.members, b.members)
['田中'] ['田中']
「開発」チームに追加しただけなのに、「営業」チームにも田中さんが入ってしまいました。既定値の [] は 1 回だけ作られ、すべてのインスタンスで同じリストを共有するためです。dataclass はこの事故を防ぐために、最初からエラーにしています。dict(field(default_factory=dict))や set も同じです。
公式ドキュメントによると、Python 3.11 からは list・dict・set に限らず、ハッシュ化できない(=変更できるとみなされる)値を既定値にするとエラーになります。リストや辞書の基本は「Pythonのリスト・辞書・内包表記の基本」で解説しています。
@dataclass に付けられる主なオプション
@dataclass(frozen=True) のように、かっこの中にオプションを書くと動きを変えられます。よく使うものは次のとおりです(公式ドキュメントで確認)。
| オプション | 既定 | True にすると | 使えるバージョン |
|---|---|---|---|
frozen | False | 値を書き換えられなくなる。ハッシュ化でき、set や dict のキーに使える | 3.7〜 |
order | False | < > で比べられ、sorted で並べ替えられる | 3.7〜 |
slots | False | 決めたフィールド以外の属性を追加できなくなる | 3.10〜 |
kw_only | False | すべてのフィールドを「名前=値」の形でしか渡せなくなる | 3.10〜 |
frozen=True:変更できないデータにする
座標や設定値のように、作ったあとに変わってほしくないデータには frozen=True を付けます。
from dataclasses import dataclass
@dataclass(frozen=True)
class Point:
x: int
y: int
p = Point(1, 2)
visited = {p, Point(1, 2), Point(3, 4)}
print(visited)
print({p: "スタート"}[Point(1, 2)])
p.x = 10
{Point(x=1, y=2), Point(x=3, y=4)}
スタート
Traceback (most recent call last):
...
dataclasses.FrozenInstanceError: cannot assign to field 'x'
値を書き換えようとすると FrozenInstanceError になります。また、frozen にしたインスタンスはハッシュ化(値から検索用の番号を計算すること)ができるので、set に入れて重複を除いたり、dict のキーにしたりできます。frozen を付けない普通の dataclass を set に入れると、TypeError: unhashable type: 'Point' になりました。公式ドキュメントでは、eq(既定で True)だけで frozen でない場合、値が変わる可能性があるため __hash__ は None に設定される、と説明されています。
一部だけ変えたコピーがほしいときは、dataclasses.replace(p, x=10) と書くと、元の p はそのままで x だけ違う新しいインスタンスが返ります。
order=True:大小を比べて並べ替える
何も付けない dataclass で < を使うと、TypeError: '<' not supported between instances of 'Version' and 'Version' になります。order=True を付けると、フィールドを上から順に並べたタプルとして比べられるようになります。
from dataclasses import dataclass
@dataclass(order=True)
class Version:
major: int
minor: int
patch: int
vs = [Version(1, 10, 0), Version(1, 2, 3), Version(0, 9, 9)]
print(sorted(vs))
print(Version(1, 2, 0) < Version(1, 10, 0))
[Version(major=0, minor=9, patch=9), Version(major=1, minor=2, patch=3), Version(major=1, minor=10, patch=0)]
True
文字列の "1.2.0" < "1.10.0" は文字の順で比べるため False になりますが、数値のフィールドにしておけば 1.2 < 1.10 と正しく判定できます。比べる順番はフィールドを書いた順なので、優先したい項目を上に書きます。
__post_init__ で値をチェック・加工する
dataclass が作る __init__ は、受け取った値をそのまま入れるだけです。「価格はマイナス不可」「前後の空白を取る」のような処理は、__post_init__ というメソッドに書きます。自動で作られた __init__ の最後に呼ばれます。
from dataclasses import dataclass
@dataclass
class Product:
name: str
price: int
stock: int = 0
def __post_init__(self):
if self.price < 0:
raise ValueError(f"price は 0 以上にしてください: {self.price}")
self.name = self.name.strip()
print(Product(" ノートPC ", 98000))
Product("マウス", -100)
Product(name='ノートPC', price=98000, stock=0)
Traceback (most recent call last):
...
ValueError: price は 0 以上にしてください: -100
おかしな値のデータは作られる前に止まるので、後の処理で原因不明のバグになるのを防げます。発生させた ValueError を try・except で受け止める方法は「Pythonの例外処理入門」で解説しています。
asdict で辞書にして JSON に書き出す
dataclass のインスタンスは、そのままでは json.dumps に渡せません。試すと TypeError: Object of type User is not JSON serializable になりました。dataclasses.asdict で辞書に変えてから渡します。
import json
from dataclasses import dataclass, field, asdict
@dataclass
class Address:
city: str
zip_code: str
@dataclass
class User:
name: str
age: int
address: Address
tags: list[str] = field(default_factory=list)
u = User("田中", 25, Address("東京都", "100-0001"), ["admin"])
print(asdict(u))
print(json.dumps(asdict(u), ensure_ascii=False, indent=2))
{'name': '田中', 'age': 25, 'address': {'city': '東京都', 'zip_code': '100-0001'}, 'tags': ['admin']}
{
"name": "田中",
"age": 25,
"address": {
"city": "東京都",
"zip_code": "100-0001"
},
"tags": [
"admin"
]
}
asdict は、中に入っている dataclass(ここでは Address)やリストもたどって辞書に変えてくれます。ensure_ascii=False と indent=2 の意味は「PythonでJSONを扱う方法」を参照してください。出力した JSON の形を確かめたいときは、JSON整形ツールに貼り付けると、構文エラーの場所も分かります。
JSON から戻すときは入れ子に注意
逆に、JSON を読み込んだ辞書から作るときは User(**data) と書けます(** は辞書を「キー=値」の引数に展開する書き方)。ただし、入れ子の部分は自動では dataclass に戻りません。
data = json.loads('{"name": "佐藤", "age": 31, "address": {"city": "大阪府", "zip_code": "530-0001"}}')
u2 = User(**data)
print(u2)
print(type(u2.address))
User(name='佐藤', age=31, address={'city': '大阪府', 'zip_code': '530-0001'}, tags=[])
<class 'dict'>
address が dict のままです。u2.address.city と書くと AttributeError になるので、User(**{**data, "address": Address(**data["address"])}) のように入れ子の部分を自分で変換します。JSON にないキーや余分なキーがあると TypeError になる点にも注意してください。
slots=True と kw_only(Python 3.10 以降)
公式ドキュメントでは、slots と kw_only はどちらも「Added in version 3.10」と書かれています。3.9 以前では使えません。
slots=True:打ち間違いの属性を防ぐ
普通の dataclass では、u.nmae = "x" のような打ち間違いをしても、新しい属性が黙って追加されてしまいます。@dataclass(slots=True) にすると、決めたフィールド以外は追加できなくなります。
from dataclasses import dataclass
@dataclass(slots=True)
class Point:
x: int
y: int
p = Point(1, 2)
p.z = 3
Traceback (most recent call last):
...
AttributeError: 'Point' object has no attribute 'z'
slots を付けないと p.z = 3 はエラーにならず、そのまま 3 が入りました。slots にすると属性を入れる __dict__ を持たなくなるため、インスタンスを大量に作るときにメモリも節約できます。
kw_only:「名前=値」で渡すことを強制する
フィールドが多いと、Config("localhost", 8080, False) のように順番で渡したとき、どの値が何か分かりにくくなります。kw_only=True を付けると、必ず名前を書いて渡す決まりにできます。一部だけにしたいときは、_: KW_ONLY という目印の行を入れると、それより下のフィールドだけが対象になります。
from dataclasses import dataclass, KW_ONLY
@dataclass(kw_only=True)
class Config:
host: str
port: int = 8080
debug: bool = False
@dataclass
class Request:
url: str
_: KW_ONLY
timeout: float = 10.0
retries: int = 3
print(Config(host="localhost", debug=True))
print(Request("https://example.com", retries=5))
Config("localhost", 8080)
Config(host='localhost', port=8080, debug=True)
Request(url='https://example.com', timeout=10.0, retries=5)
Traceback (most recent call last):
...
TypeError: Config.__init__() takes 1 positional argument but 3 were given
順番で渡した最後の行だけがエラーになりました(「1 positional argument」の 1 は self のことです)。
継承で出る「non-default argument follows default argument」
dataclass を継承すると、親クラスのフィールドの後ろに子クラスのフィールドが並びます。親に既定値付きのフィールドがあり、子に既定値なしのフィールドを足すと、クラスを作った時点でエラーになります。
from dataclasses import dataclass
@dataclass
class Base:
id: int
created_by: str = "system"
@dataclass
class Article(Base):
title: str
Traceback (most recent call last):
...
TypeError: non-default argument 'title' follows default argument
作られる __init__ が (self, id, created_by="system", title) の順になり、関数の「既定値のない引数は、既定値のある引数より前に書く」という決まりに反するためです。公式ドキュメントにも、1 つのクラスの中でも継承の結果でも同じく TypeError になると書かれています。直し方は次のどれかです。
- 親と子の両方に
kw_only=Trueを付ける(名前で渡すので順番の決まりがなくなる。Article(id=1, title="dataclass入門")で作れることを確認しました) - 子のフィールドにも既定値を付ける
- 既定値付きのフィールドを親から外し、子の最後に書く
辞書・namedtuple との使い分け
値をまとめる方法は dataclass のほかに、辞書(dict)と namedtuple(名前付きタプル)があります。
| 方法 | 向いている場面 | 注意点 |
|---|---|---|
| 辞書 | JSON をそのまま扱う、キーが決まっていない一時的なデータ | キーの打ち間違いは実行するまで分からない |
| namedtuple | 変更しない小さなデータ。x, y = p のように分解したい | 値を変更できない。タプルなので p == (1, 2) が True になる |
| dataclass | 項目が決まったデータ。変更・既定値・チェック・メソッドが必要 | JSON との変換は asdict などで行う |
実際に、namedtuple("PointNT", ["x", "y"])(1, 2) == (1, 2) は True、同じ形の dataclass と (1, 2) の比較は False でした。PEP 557 でも、namedtuple は項目数が同じ別のタプルと等しくなってしまう点などが、dataclass を作った理由として挙げられています。迷ったら、「項目が決まっているなら dataclass、決まっていないなら辞書」と考えるとよいでしょう。
よくある質問
パスワードなどを print に出したくありません
password: str = field(default="", repr=False) のように repr=False を付けると、そのフィールドは表示から外れます。Settings(password="secret") を print すると Settings(theme='light', font_size=14) と表示され、password は出ませんでした。ログに秘密の値が残る事故を防げます。ただし、asdict の結果には含まれるので、JSON に書き出すときは別に取り除いてください。
フィールドの一覧をプログラムで取り出せますか?
dataclasses.fields() を使います。[f.name for f in fields(s)] で ['theme', 'font_size', 'password'] のように名前の一覧が取れました。CSV の見出し行を作るときなどに使えます。
まとめ
@dataclassと「項目名: 型」で、__init__・__repr__・__eq__が自動で作られる- リストや辞書の既定値は
field(default_factory=list)。= []は ValueError - 変更させないなら
frozen=True、並べ替えるならorder=True、値のチェックは__post_init__ - JSON にするときは
asdictで辞書にしてからjson.dumps - 継承の順番エラーは
kw_only=True(3.10 以降)で解決できる
関連する記事・ツール
- JSON整形ツール
- PythonでJSONを扱う方法|json.loads・dumpsの使い方とエラー対処
- Pythonのリスト・辞書・内包表記の基本|使い方とよくある間違いを実例で解説
- Pythonの例外処理入門|try・except・finally・raiseの使い方
- Pythonの型ヒント入門|typingの書き方とmypyで型の間違いを見つける方法
- Pythonのmatch文の使い方|パターンマッチとcase RED:の落とし穴