Skip to content

Python Dataclasses: @dataclassデコレータ完全ガイド

Soren Atelier
Name
Soren Atelier

Updated on

Pythonでクラスを書くと、しばしば繰り返しのボイラープレートコードが発生します。属性を初期化するために__init__を定義し、見やすい出力のために__repr__を用意し、比較のために__eq__を実装し、ときにはハッシュ可能にするために__hash__まで書く必要があります。こうした手作業の実装は、設定オブジェクト、APIレスポンス、データベースレコードのような「データを保持するだけのクラス」では特に面倒になりがちです。

Python 3.7ではPEP 557によりdataclassesが導入され、このボイラープレートを自動化しつつ、通常のクラスと同等の柔軟性を保てるようになりました。@dataclassデコレータは型アノテーションに基づいて特殊メソッドを自動生成し、何十行にもなりがちなコードを数行に圧縮できます。このガイドでは、dataclassesを活用してよりクリーンで保守しやすいPythonコードを書く方法を紹介します。

📚

    なぜDataclassesが存在するのか：ボイラープレート問題の解決

    従来のPythonクラスでは、よくある操作のために明示的なメソッド定義が必要です。たとえば、ユーザーデータを保存する標準的なクラスは次のようになります。

    class User:
    def __init__(self, name, email, age):
        self.name = name
        self.email = email
        self.age = age
 
    def __repr__(self):
        return f"User(name={self.name!r}, email={self.email!r}, age={self.age!r})"
 
    def __eq__(self, other):
        if not isinstance(other, User):
            return NotImplemented
        return (self.name, self.email, self.age) == (other.name, other.email, other.age)

    dataclassesを使うと、これは次のように短くなります。

    from dataclasses import dataclass
 
@dataclass
class User:
    name: str
    email: str
    age: int

    デコレータが型アノテーションから__init__、__repr__、__eq__を自動生成します。結果として15行以上のボイラープレートが不要になり、機能は同等のままです。

    基本の@dataclass構文

    最もシンプルなdataclassは、フィールドに型アノテーションを付けるだけで作れます。

    from dataclasses import dataclass
 
@dataclass
class Product:
    name: str
    price: float
    quantity: int
 
product = Product("Laptop", 999.99, 5)
print(product)  # Product(name='Laptop', price=999.99, quantity=5)
 
product2 = Product("Laptop", 999.99, 5)
print(product == product2)  # True

    デコレータは動作をカスタマイズするためのパラメータを受け取れます。

    @dataclass(
    init=True,       # __init__を生成（デフォルト: True）
    repr=True,       # __repr__を生成（デフォルト: True）
    eq=True,         # __eq__を生成（デフォルト: True）
    order=False,     # 比較メソッド群を生成（デフォルト: False）
    frozen=False,    # インスタンスを不変にする（デフォルト: False）
    unsafe_hash=False  # __hash__を生成（デフォルト: False）
)
class Config:
    host: str
    port: int

    フィールド型とデフォルト値

    dataclassesはフィールドのデフォルト値をサポートします。デフォルトなしのフィールドは、デフォルトありのフィールドより前に置く必要があります。

    from dataclasses import dataclass
 
@dataclass
class Server:
    host: str
    port: int = 8080
    protocol: str = "http"
 
server1 = Server("localhost")
print(server1)  # Server(host='localhost', port=8080, protocol='http')
 
server2 = Server("api.example.com", 443, "https")
print(server2)  # Server(host='api.example.com', port=443, protocol='https')

    listやdictのようなミュータブルなデフォルト値には、参照の共有を避けるためdefault_factoryを使います。

    from dataclasses import dataclass, field
 
# WRONG - 全インスタンスで同じlistを共有する
@dataclass
class WrongConfig:
    tags: list = []  # Raises error in Python 3.10+
 
# CORRECT - 各インスタンスが新しいlistを持つ
@dataclass
class CorrectConfig:
    tags: list = field(default_factory=list)
    metadata: dict = field(default_factory=dict)
 
config1 = CorrectConfig()
config2 = CorrectConfig()
 
config1.tags.append("production")
print(config1.tags)  # ['production']
print(config2.tags)  # [] - separate list

    field()関数：高度なフィールド設定

    field()関数を使うと、個々のフィールドを細かく制御できます。

    from dataclasses import dataclass, field
from typing import List
 
@dataclass
class Employee:
    name: str
    employee_id: int
    salary: float = field(repr=False)  # reprから給与を隠す
    skills: List[str] = field(default_factory=list)
    _internal_id: str = field(init=False, repr=False)  # __init__に含めない
    performance_score: float = field(default=0.0, compare=False)  # 比較から除外
 
    def __post_init__(self):
        self._internal_id = f"EMP_{self.employee_id:06d}"
 
emp = Employee("Alice", 12345, 85000.0, ["Python", "SQL"])
print(emp)  # Employee(name='Alice', employee_id=12345, skills=['Python', 'SQL'], performance_score=0.0)
print(emp._internal_id)  # EMP_012345

    主なfield()パラメータ：

    ParameterTypeDescription
    defaultAnyフィールドのデフォルト値
    default_factoryCallableデフォルト値を返す引数なし関数
    initbool__init__に含める（デフォルト: True）
    reprbool__repr__に含める（デフォルト: True）
    comparebool比較メソッドに含める（デフォルト: True）
    hashbool__hash__に含める（デフォルト: None）
    metadatadict任意のメタデータ（dataclassesモジュール自体は利用しない）
    kw_onlyboolフィールドをキーワード専用にする（Python 3.10+）

    metadataはfields()から参照できる任意情報を保持できます。

    from dataclasses import dataclass, field, fields
 
@dataclass
class APIRequest:
    endpoint: str = field(metadata={"description": "API endpoint path"})
    method: str = field(default="GET", metadata={"choices": ["GET", "POST", "PUT", "DELETE"]})
 
for f in fields(APIRequest):
    print(f"{f.name}: {f.metadata}")
# endpoint: {'description': 'API endpoint path'}
# method: {'choices': ['GET', 'POST', 'PUT', 'DELETE']}

    Dataclassesにおける型アノテーション

    dataclassesは型アノテーションを前提としますが、実行時に型を強制しません。複雑な型にはtypingモジュールを使います。

    from dataclasses import dataclass
from typing import List, Dict, Optional, Union, Tuple
from datetime import datetime
 
@dataclass
class DataAnalysisJob:
    job_id: str
    dataset_path: str
    columns: List[str]
    filters: Dict[str, Union[str, int, float]]
    output_format: str = "csv"
    created_at: datetime = field(default_factory=datetime.now)
    completed_at: Optional[datetime] = None
    error_message: Optional[str] = None
    results: Optional[Dict[str, Tuple[float, float]]] = None
 
job = DataAnalysisJob(
    job_id="job_001",
    dataset_path="/data/sales.csv",
    columns=["date", "revenue", "region"],
    filters={"year": 2026, "region": "US"}
)

    実行時の型チェックが必要なら、pydanticのようなライブラリと統合するか、__post_init__で検証を行います。

    frozen=True：不変なDataclassを作る

    frozen=Trueを設定すると、生成後にインスタンスを変更できない（不変の）データモデルになります。namedtupleに近い挙動です。

    from dataclasses import dataclass
 
@dataclass(frozen=True)
class Point:
    x: float
    y: float
 
    def distance_from_origin(self):
        return (self.x**2 + self.y**2) ** 0.5
 
point = Point(3.0, 4.0)
print(point.distance_from_origin())  # 5.0
 
# 変更しようとするとFrozenInstanceError
try:
    point.x = 5.0
except AttributeError as e:
    print(f"Error: {e}")  # Error: cannot assign to field 'x'

    Frozen dataclassは、全フィールドがhashableであればデフォルトでhashableになり、setやdictのキーとして使えます。

    @dataclass(frozen=True)
class Coordinate:
    latitude: float
    longitude: float
 
locations = {
    Coordinate(40.7128, -74.0060): "New York",
    Coordinate(51.5074, -0.1278): "London"
}
 
print(locations[Coordinate(40.7128, -74.0060)])  # New York

    __post_init__メソッド：バリデーションと計算フィールド

    __post_init__は__init__の後に実行され、検証や計算フィールドの初期化に使えます。

    from dataclasses import dataclass, field
from datetime import datetime
 
@dataclass
class BankAccount:
    account_number: str
    balance: float
    created_at: datetime = field(default_factory=datetime.now)
    account_type: str = field(init=False)
 
    def __post_init__(self):
        if self.balance < 0:
            raise ValueError("Initial balance cannot be negative")
 
        # 残高に基づいてaccount_typeを計算
        if self.balance >= 100000:
            self.account_type = "Premium"
        elif self.balance >= 10000:
            self.account_type = "Gold"
        else:
            self.account_type = "Standard"
 
account = BankAccount("ACC123456", 50000.0)
print(account.account_type)  # Gold

    他フィールドに依存するinit=Falseなフィールドは、__post_init__で設定します。

    from dataclasses import dataclass, field
 
@dataclass
class Rectangle:
    width: float
    height: float
    area: float = field(init=False)
    perimeter: float = field(init=False)
 
    def __post_init__(self):
        self.area = self.width * self.height
        self.perimeter = 2 * (self.width + self.height)
 
rect = Rectangle(5.0, 3.0)
print(f"Area: {rect.area}, Perimeter: {rect.perimeter}")  # Area: 15.0, Perimeter: 16.0

    Dataclassesの継承

    dataclassesは継承をサポートし、フィールドは自動的にマージされます。

    from dataclasses import dataclass
 
@dataclass
class Animal:
    name: str
    age: int
 
@dataclass
class Dog(Animal):
    breed: str
    is_good_boy: bool = True
 
dog = Dog("Buddy", 5, "Golden Retriever")
print(dog)  # Dog(name='Buddy', age=5, breed='Golden Retriever', is_good_boy=True)

    サブクラスは親のフィールドを引き継ぎ、新しいフィールドを追加できます。ただし、継承をまたいでも「デフォルトなしフィールドがデフォルトありフィールドの後に来てはいけない」制約があります。

    from dataclasses import dataclass
 
@dataclass
class BaseConfig:
    environment: str = "production"
 
# ERROR: Non-default field 'api_key' cannot follow default field 'environment'
# @dataclass
# class APIConfig(BaseConfig):
#     api_key: str
 
# CORRECT: デフォルトを付けるか、フィールド順を調整する
@dataclass
class APIConfig(BaseConfig):
    api_key: str = ""  # デフォルトを提供
    timeout: int = 30

    Python 3.10+ではkw_onlyでこの問題を回避できます。

    from dataclasses import dataclass
 
@dataclass
class BaseConfig:
    environment: str = "production"
 
@dataclass(kw_only=True)
class APIConfig(BaseConfig):
    api_key: str  # キーワード引数として渡す必要がある
    timeout: int = 30
 
config = APIConfig(api_key="secret_key_123")  # OK
# config = APIConfig("secret_key_123")  # TypeError

    slots=True：メモリ効率（Python 3.10+）

    Python 3.10ではslots=Trueが追加され、__slots__を定義してメモリ使用量を削減できます。

    from dataclasses import dataclass
import sys
 
@dataclass
class RegularUser:
    username: str
    email: str
    age: int
 
@dataclass(slots=True)
class SlottedUser:
    username: str
    email: str
    age: int
 
regular = RegularUser("john", "john@example.com", 30)
slotted = SlottedUser("jane", "jane@example.com", 28)
 
print(f"Regular: {sys.getsizeof(regular.__dict__)} bytes")  # ~104 bytes
print(f"Slotted: {sys.getsizeof(slotted)} bytes")          # ~64 bytes

    Slotted dataclassはメモリを30〜40%節約でき、属性アクセスも高速化する一方、動的な属性追加はできなくなります。

    regular.new_attribute = "allowed"  # OK
# slotted.new_attribute = "error"  # AttributeError

    kw_only=True：キーワード専用フィールド（Python 3.10+）

    すべてのフィールドをキーワード専用にして、生成時の明確さを高めます。

    from dataclasses import dataclass
 
@dataclass(kw_only=True)
class DatabaseConnection:
    host: str
    port: int
    username: str
    password: str
    database: str = "default"
 
# キーワード引数が必須
conn = DatabaseConnection(
    host="localhost",
    port=5432,
    username="admin",
    password="secret"
)
 
# 位置引数はTypeError
# conn = DatabaseConnection("localhost", 5432, "admin", "secret")

    kw_onlyはフィールド単位でも制御できます。

    from dataclasses import dataclass, field
 
@dataclass
class MixedArgs:
    required_positional: str
    optional_positional: int = 0
    required_keyword: str = field(kw_only=True)
    optional_keyword: bool = field(default=False, kw_only=True)
 
obj = MixedArgs("value", 10, required_keyword="kw_value")

    比較：dataclass vs 代替案

    FeaturedataclassnamedtupleTypedDictPydanticattrs
    MutabilityMutable (default)ImmutableN/A (dict subclass)MutableConfigurable
    Type validationAnnotations onlyNoAnnotations onlyRuntime validationRuntime validation
    Default valuesYesYesNoYesYes
    MethodsFull class supportLimitedNoFull class supportFull class support
    InheritanceYesNoLimitedYesYes
    Memory overheadModerateLowLowHigherModerate
    Slots supportYes (3.10+)NoNoYesYes
    PerformanceFastFastestFastSlower (validation)Fast
    Built-inYes (3.7+)YesYes (3.8+)NoNo

    dataclassesを選ぶべきケース：

    • 依存関係を増やしたくない標準的なPythonプロジェクト
    • 型ヒント付きのシンプルなデータコンテナ
    • frozen/mutableの柔軟性が必要
    • 継承階層がある

    Pydanticを選ぶべきケース：

    • APIリクエスト/レスポンスの検証
    • 厳密なバリデーションを伴う設定管理
    • JSON schema生成

    namedtupleを選ぶべきケース：

    • 軽量な不変コンテナ
    • 最大限のメモリ効率が必要
    • Python < 3.7互換が必要

    辞書への変換／辞書からの変換

    dataclassesはシリアライズ用にasdict()とastuple()を提供します。

    from dataclasses import dataclass, asdict, astuple
 
@dataclass
class Config:
    host: str
    port: int
    ssl_enabled: bool = True
 
config = Config("api.example.com", 443)
 
# 辞書へ変換
config_dict = asdict(config)
print(config_dict)  # {'host': 'api.example.com', 'port': 443, 'ssl_enabled': True}
 
# タプルへ変換
config_tuple = astuple(config)
print(config_tuple)  # ('api.example.com', 443, True)

    ネストしたdataclassの場合：

    from dataclasses import dataclass, asdict
 
@dataclass
class Address:
    street: str
    city: str
    zipcode: str
 
@dataclass
class Person:
    name: str
    address: Address
 
person = Person("Alice", Address("123 Main St", "Springfield", "12345"))
person_dict = asdict(person)
print(person_dict)
# {'name': 'Alice', 'address': {'street': '123 Main St', 'city': 'Springfield', 'zipcode': '12345'}}

    DataclassesのJSONシリアライズ

    dataclasses自体はJSONシリアライズをネイティブにサポートしませんが、統合は簡単です。

    import json
from dataclasses import dataclass, asdict
from datetime import datetime
 
@dataclass
class Event:
    name: str
    timestamp: datetime
    attendees: int
 
    def to_json(self):
        data = asdict(self)
        # datetime用のカスタムシリアライズ
        data['timestamp'] = self.timestamp.isoformat()
        return json.dumps(data)
 
    @classmethod
    def from_json(cls, json_str):
        data = json.loads(json_str)
        data['timestamp'] = datetime.fromisoformat(data['timestamp'])
        return cls(**data)
 
event = Event("Python Conference", datetime.now(), 500)
json_str = event.to_json()
print(json_str)
 
restored = Event.from_json(json_str)
print(restored)

    より複雑なケースではdataclasses-jsonライブラリやPydanticの利用を検討してください。

    実務で使えるパターン

    設定オブジェクト

    from dataclasses import dataclass, field
from typing import List
 
@dataclass
class AppConfig:
    app_name: str
    version: str
    debug: bool = False
    allowed_hosts: List[str] = field(default_factory=lambda: ["localhost"])
    database_url: str = "sqlite:///app.db"
    cache_timeout: int = 300
 
    def __post_init__(self):
        if self.debug:
            print(f"Running {self.app_name} v{self.version} in DEBUG mode")
 
config = AppConfig("DataAnalyzer", "2.1.0", debug=True)

    APIレスポンスモデル

    from dataclasses import dataclass
from typing import List, Optional
from datetime import datetime
 
@dataclass
class APIResponse:
    status: str
    data: Optional[List[dict]] = None
    error_message: Optional[str] = None
    timestamp: datetime = field(default_factory=datetime.now)
 
    @property
    def is_success(self):
        return self.status == "success"
 
response = APIResponse("success", data=[{"id": 1, "name": "Dataset A"}])
print(response.is_success)  # True

    PyGWalker連携によるデータベースレコード

    from dataclasses import dataclass, asdict
from typing import List
import pandas as pd
 
@dataclass
class SalesRecord:
    date: str
    product: str
    revenue: float
    region: str
    quantity: int
 
# Create sample data
records = [
    SalesRecord("2026-01-01", "Laptop", 1299.99, "US", 5),
    SalesRecord("2026-01-02", "Mouse", 29.99, "EU", 50),
    SalesRecord("2026-01-03", "Keyboard", 89.99, "US", 20),
]
 
# Convert to DataFrame for visualization with PyGWalker
df = pd.DataFrame([asdict(r) for r in records])
 
# Use PyGWalker for interactive data exploration
# import pygwalker as pyg
# walker = pyg.walk(df)
# This creates a Tableau-like interface to visualize your dataclass-based data

    dataclassesは、可視化前のデータ構造化に特に強力です。PyGWalkerはDataFrameをインタラクティブな可視化UIに変換できるため、dataclassベースのデータ分析ワークフローをスムーズにつなげられます。

    通常クラスとの性能ベンチマーク

    import timeit
from dataclasses import dataclass
 
# Regular class
class RegularClass:
    def __init__(self, x, y, z):
        self.x = x
        self.y = y
        self.z = z
 
    def __repr__(self):
        return f"RegularClass(x={self.x}, y={self.y}, z={self.z})"
 
    def __eq__(self, other):
        return (self.x, self.y, self.z) == (other.x, other.y, other.z)
 
@dataclass
class DataClass:
    x: int
    y: int
    z: int
 
# Benchmark instantiation
regular_time = timeit.timeit(lambda: RegularClass(1, 2, 3), number=1000000)
dataclass_time = timeit.timeit(lambda: DataClass(1, 2, 3), number=1000000)
 
print(f"Regular class: {regular_time:.4f}s")
print(f"Dataclass: {dataclass_time:.4f}s")
# Dataclasses are typically 5-10% slower due to decorator overhead
# but provide significantly cleaner code

    slots=True（Python 3.10+）を使うと、dataclassは通常クラスと同等以上の性能になりつつ、メモリ使用量を30〜40%削減できます。

    応用パターン：カスタムなフィールド順序（並べ替え）

    from dataclasses import dataclass, field
 
def sort_by_priority(items):
    return sorted(items, key=lambda x: x.priority, reverse=True)
 
@dataclass(order=True)
class Task:
    priority: int
    name: str = field(compare=False)
    description: str = field(compare=False)
 
tasks = [
    Task(3, "Review PR", "Code review for feature X"),
    Task(1, "Write docs", "Documentation update"),
    Task(5, "Fix bug", "Critical production issue"),
]
 
sorted_tasks = sorted(tasks)
for task in sorted_tasks:
    print(f"Priority {task.priority}: {task.name}")
# Priority 1: Write docs
# Priority 3: Review PR
# Priority 5: Fix bug

    ベストプラクティスと落とし穴

    1. ミュータブルなデフォルトには必ずdefault_factoryを使う：[]や{}を直接代入しない
    2. 型ヒントは必須：dataclassは値ではなくアノテーションに依存する
    3. フィールド順序が重要：デフォルトなし → デフォルトあり の順
    4. 不変データにはfrozen=True：hash可能・スレッド安全性にも有利
    5. __post_init__は控えめに：ロジックを詰めすぎるとdataclassの簡潔さが失われる
    6. 大量データにはslots=Trueを検討：Python 3.10+で大きなメモリ削減
    7. __post_init__で検証する：dataclassは実行時に型を強制しない

    FAQ

    まとめ

    Pythonのdataclassesは、クラスのボイラープレートを削減しつつ、クラスの持つ表現力をそのまま維持できます。@dataclassデコレータは初期化・表現・比較メソッドを自動生成し、開発時間と保守コストを大きく下げます。設定オブジェクトからAPIモデル、データベースレコードまで、dataclassesは型アノテーション付きのクリーンな「データ保持クラス」を作るための有力な選択肢です。

    主な利点は、自動メソッド生成、field()によるフィールド挙動のカスタマイズ、frozen=Trueによる不変化、__post_init__による検証、そしてslots=Trueによるメモリ効率です。namedtupleやPydanticにも適材適所はありますが、多くのPythonプロジェクトではdataclassesが「シンプルさと機能性」のバランスに優れています。

    データ分析の文脈では、dataclassesで整形した構造化データをPyGWalkerのようなツールに接続することで、データ取り込みから洞察の獲得までをインタラクティブに高速化できます。

    📚