{"title":"Data Classes","description":"","content":"This section is about two small standard-library tools that make data-shaped classes pleasant to write: `dataclasses` and `enum`. The first one is `@dataclass`, a decorator that takes a class with type-annotated attributes and writes the boring methods for you: `__init__`, `__repr__`, and `__eq__`. This chapter covers the decorator at its plainest, the kind of class you'd reach for to model a `Product`, a `Customer`, or an `Order` line.\n\n---\n\n# Why dataclasses exist\n\nA lot of classes in real code are essentially containers: a name, a price, a stock count, maybe an `is_active` flag. The behavior is \"hold those values, print nicely, compare by content.\" Writing that by hand is repetitive. Here's the plain-class version of a `Product`:\n\n\n```python\nclass Product:\n def __init__(self, name, price, stock):\n self.name = name\n self.price = price\n self.stock = stock\n\n def __repr__(self):\n return f\"Product(name={self.name!r}, price={self.price!r}, stock={self.stock!r})\"\n\n def __eq__(self, other):\n if not isinstance(other, Product):\n return NotImplemented\n return (self.name, self.price, self.stock) == (other.name, other.price, other.stock)\n```\n\n\nThree attributes, fifteen lines, and three of those methods are pure boilerplate. The constructor just copies parameters onto `self`. The repr restates every field. The equality method compares every field. None of that code says anything interesting about a product; it's the same shape every class with three fields would have.\n\nThe `@dataclass` decorator, added in Python 3.7, looks at a class with type-annotated attributes and writes those methods for you. Same class:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Product:\n name: str\n price: float\n stock: int\n```\n\n\nThat's the whole class. The decorator inspects the class body, finds three annotated attributes, and generates `__init__`, `__repr__`, and `__eq__` with the same behavior as the hand-written version. The fields you list in the class body become the parameters to `__init__`, in order.\n\n\n```mermaid\nflowchart LR\n SRC[Class body
with type-annotated
attributes]:::cyan --> DEC[@dataclass
decorator]:::orange\n DEC --> GEN[Generates
__init__
__repr__
__eq__]:::green\n GEN --> CLS[Ready-to-use
class]:::teal\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe class is still a normal Python class. You can add methods, inherit from it, and use it anywhere a regular class fits. The decorator just removes the typing you'd otherwise repeat.\n\n---\n\n# Your first dataclass\n\nLet's build one and use it:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Product:\n name: str\n price: float\n stock: int\n\nshoes = Product(\"Running Shoes\", 79.99, 12)\n\nprint(shoes)\nprint(shoes.name)\nprint(shoes.price)\nprint(shoes.stock)\n```\n\n\nA few things to notice in that output. Creating an instance with `Product(\"Running Shoes\", 79.99, 12)` worked because the decorator built an `__init__` that takes the three fields in the order they appear in the class body. Printing the object gave a useful, multi-field representation instead of `<__main__.Product object at 0x10a3b4c10>`, because the decorator also generated `__repr__`. The attributes are accessible on the instance the same way they would be on any other class.\n\nKeyword arguments work too, and they tend to read better when the order isn't obvious:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Product:\n name: str\n price: float\n stock: int\n\nmug = Product(name=\"Ceramic Mug\", price=14.99, stock=80)\nprint(mug)\n```\n\n\nThe fields are positional by default, so positional arguments work in declaration order, and keyword arguments work by name. That's the same rule any normal function follows, because `__init__` is just a normal function the decorator wrote for you.\n\n---\n\n# What @dataclass generates\n\nIt's worth knowing exactly what the decorator gives you, because every dataclass in the rest of this section builds on these three methods.\n\n\n| Method generated | What it does |\n| --- | --- |\n| `__init__(self, ...)` | Takes one parameter per field, in declaration order, and assigns each to `self` |\n| `__repr__(self)` | Returns `ClassName(field1=value1, field2=value2, ...)` for printing and debugging |\n| `__eq__(self, other)` | Returns `True` when `other` is the same class and every field compares equal |\n\n\nEquality is the part people are most surprised by. Two instances of a plain class are unequal by default, even when every field has the same value. With `@dataclass`, equality compares by content:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Product:\n name: str\n price: float\n stock: int\n\na = Product(\"Notebook\", 4.99, 100)\nb = Product(\"Notebook\", 4.99, 100)\nc = Product(\"Notebook\", 5.99, 100)\n\nprint(a == b)\nprint(a == c)\nprint(a is b)\n```\n\n\n`a` and `b` are different objects in memory (so `a is b` is `False`), but they have identical field values, so the generated `__eq__` returns `True`. Change one field and equality breaks. This is what most code wants for value-shaped types: two orders with identical contents should compare equal.\n\nThe generated `__repr__` is the other quality-of-life win. Without it, printing an object gives you a useless memory-address line. With it, you see the actual contents:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Customer:\n name: str\n email: str\n is_active: bool\n\nclass PlainCustomer:\n def __init__(self, name, email, is_active):\n self.name = name\n self.email = email\n self.is_active = is_active\n\nprint(Customer(\"Asha\", \"asha@shop.com\", True))\nprint(PlainCustomer(\"Asha\", \"asha@shop.com\", True))\n```\n\n\nSame data, very different debugging experience. The plain class would need a hand-written `__repr__` to get parity, which is exactly the boilerplate `@dataclass` removes.\n\n---\n\n# Type hints are required\n\nHere's the rule that trips people up first: `@dataclass` only treats an attribute as a field when it has a type annotation. The annotation can be anything (`str`, `int`, `float`, `list`, even `object`), but it has to be there.\n\nThis works:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Order:\n order_id: str\n total: float\n```\n\n\nThis one doesn't behave the way you'd expect:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Order:\n order_id = \"ORD000001\"\n total = 0.0\n\nprint(Order())\n```\n\n\nNo `order_id`, no `total`, and `Order()` takes no arguments. The decorator ignored both lines because neither had a type annotation, so it found zero fields and generated an `__init__` with no parameters. The attributes are still on the class as class-level constants, but they're not part of the instance contract.\n\nTry to pass arguments and you get a clear error:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Order:\n order_id = \"ORD000001\"\n total = 0.0\n\nOrder(\"ORD123456\", 49.99)\n```\n\n\nThe fix is to add annotations:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Order:\n order_id: str\n total: float\n\nprint(Order(\"ORD123456\", 49.99))\n```\n\n\nThe annotations don't enforce types at runtime. You can still pass `Order(123, \"free\")` and Python won't object; the decorator uses the annotations as a list of fields, not as a runtime type check. Static type checkers like `mypy` and `pyright` use them, and editors use them for autocomplete, but `@dataclass` itself treats them as field declarations.\n\n---\n\n# Default values\n\nA field can have a default value the same way a function parameter can: write it after the type annotation with `=`.\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Product:\n name: str\n price: float\n stock: int = 0\n is_active: bool = True\n\nbread = Product(\"Sourdough\", 6.50)\nmug = Product(\"Ceramic Mug\", 14.99, 80)\nout_of_stock = Product(\"Limited Edition Tee\", 29.99, 0, False)\n\nprint(bread)\nprint(mug)\nprint(out_of_stock)\n```\n\n\nDefaults follow the same rule as normal Python function parameters: every field with a default has to come after every field without one. The decorator builds `__init__` in declaration order, and Python doesn't allow a non-default parameter after a default. If you put `stock: int = 0` before `price: float`, the decorator raises an error at class-definition time:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Product:\n name: str\n stock: int = 0\n price: float\n```\n\n\nThat error fires when Python tries to define the class, not when you create an instance. Move every defaulted field to the bottom and the class compiles cleanly.\n\nDefaults only work this way for simple immutable values like numbers, strings, booleans, and `None`. Mutable defaults like `[]`, `{}`, or `set()` are a separate topic with their own gotcha, because writing `items: list = []` shares one list across every instance. The fix uses `field(default_factory=list)`. For this chapter, stick to simple immutable defaults.\n\n\n> **INFO**\n>\n> **Cost:** `@dataclass` does its work once, at class-definition time. It inspects the annotations, generates source code for the methods, compiles them, and attaches them. After that, creating instances is the same speed as a plain class. There's no per-instance overhead.\n\n\n---\n\n# Equality and comparison\n\nThe generated `__eq__` compares two instances field by field, in declaration order. Two instances are equal when they're the same class and every field is equal.\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass CartItem:\n product_name: str\n quantity: int\n price: float\n\na = CartItem(\"Mug\", 2, 14.99)\nb = CartItem(\"Mug\", 2, 14.99)\nc = CartItem(\"Mug\", 3, 14.99)\n\nprint(a == b)\nprint(a == c)\n```\n\n\nThat's enough to support a lot of useful patterns. Checking whether two carts contain the same line items, deduplicating a list of orders with `set` won't work yet (we need hashability for that, and the default dataclass isn't hashable), but plain `==` comparison and `in` checks for lists already work:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass CartItem:\n product_name: str\n quantity: int\n price: float\n\ncart = [\n CartItem(\"Mug\", 2, 14.99),\n CartItem(\"Notebook\", 1, 4.99),\n CartItem(\"Pen\", 3, 1.50),\n]\n\nprint(CartItem(\"Notebook\", 1, 4.99) in cart)\nprint(CartItem(\"Notebook\", 2, 4.99) in cart)\n```\n\n\nThe `in` check uses `__eq__` under the hood. Because the dataclass equality compares contents, you can ask \"is this exact item already in the cart?\" without writing a loop. Without `@dataclass`, that check would fail because plain-class `==` falls back to identity comparison.\n\nEquality is also class-aware. Two dataclasses with the same field names and values but different classes are not equal:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass CartItem:\n name: str\n quantity: int\n\n@dataclass\nclass WishlistItem:\n name: str\n quantity: int\n\na = CartItem(\"Mug\", 1)\nb = WishlistItem(\"Mug\", 1)\n\nprint(a == b)\n```\n\n\nThe generated `__eq__` checks the type first. A cart item and a wishlist item with the same contents are still different things, so equality returns `False`. That's the behavior almost every value class wants.\n\nWhat `@dataclass` does not generate by default is ordering (`<`, `<=`, `>`, `>=`). Trying to sort or compare order is a `TypeError`:\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass CartItem:\n name: str\n quantity: int\n\na = CartItem(\"Mug\", 1)\nb = CartItem(\"Pen\", 2)\nprint(a < b)\n```\n\n\nOrdering is opt-in via `@dataclass(order=True)`, which is one of the decorator options alongside `frozen=True` and `slots=True`. For now, the rule is: `==` and `!=` work out of the box, ordering does not.","pageType":"python"}

Data Classes

Get Premium