Text of docs.python.org › 3.14 › library › dataclasses.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

dataclasses — Data Classes — Python 3.14.10 documentation

Navigation index modules | next | previous | Python » 3.14.10 documentation » The Python standard library » Python Runtime Services » dataclasses — Data Classes | Theme | dataclasses — Data Classes ¶ Source code: Lib/dataclasses.py This module provides a decorator and functions for automatically adding generated special methods such as __init__() and __repr__() to user-defined classes. It was originally described in PEP 557 .

The member variables to use in these generated methods are defined using PEP 526 type annotations. For example, this code: from dataclasses import dataclass @dataclass class InventoryItem : """Class for keeping track of an item in inventory.""" name : str unit_price : float quantity_on_hand : int = 0 def total_cost ( self ) -> float : return self . unit_price * self . quantity_on_hand will add, among other things, a __init__() that looks like: def __init__ ( self , name : str , unit_price : float , quantity_on_hand : int = 0 ): self . name = name self . unit_price = unit_price self . quantity_on_hand = quantity_on_hand Note that this method is automatically added to the class: it is not directly specified in the InventoryItem definition shown above.

Added in version 3.7. Module contents ¶ @ dataclasses. dataclass ( * , init = True , repr = True , eq = True , order = False , unsafe_hash = False , frozen = False , match_args = True , kw_only = False , slots = False , weakref_slot = False ) ¶ This function is a decorator that is used to add generated special methods to classes, as described below. The @dataclass decorator examines the class to find field s. A field is defined as a class variable that has a type annotation .

With two exceptions described below, nothing in @dataclass examines the type specified in the variable annotation. The order of the fields in all of the generated methods is the order in which they appear in the class definition. The @dataclass decorator will add various “dunder” methods to the class, described below. If any of the added methods already exist in the class, the behavior depends on the parameter, as documented below.

The decorator returns the same class that it is called on; no new class is created. If @dataclass is used just as a simple decorator with no parameters, it acts as if it has the default values documented in this signature. That is, these three uses of @dataclass are equivalent: @dataclass class C : ... @dataclass () class C : ... @dataclass ( init = True , repr = True , eq = True , order = False , unsafe_hash = False , frozen = False , match_args = True , kw_only = False , slots = False , weakref_slot = False ) class C : ...

The parameters to @dataclass are: init : If true (the default), a __init__() method will be generated. If the class already defines __init__() , this parameter is ignored. repr : If true (the default), a __repr__() method will be generated. The generated repr string will have the class name and the name and repr of each field, in the order they are defined in the class. Fields that are marked as being excluded from the repr are not included.

For example: InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10) . If the class already defines __repr__() , this parameter is ignored. eq : If true (the default), an __eq__() method will be generated. This method compares the class by comparing each field in order. Both instances in the comparison must be of the identical type. If the class already defines __eq__() , this parameter is ignored. Changed in version 3.13: The generated __eq__ method now compares each field individually (for example, self.a == other.a and self.b == other.b ), rather than comparing tuples of fields as in previous versions.

This change makes the comparison faster but it may alter results in cases where attributes compare equal by identity but not by value (such as float('nan') ). In Python 3.12 and earlier, the comparison was performed by creating tuples of the fields and comparing them (for example, (self.a, self.b) == (other.a, other.b) ). order : If true (the default is False ), __lt__() , __le__() , __gt__() , and __ge__() methods will be generated.

These compare the class as if it were a tuple of its fields, in order. Both instances in the comparison must be of the identical type. If order is true and eq is false, a ValueError is raised. If the class already defines any of __lt__() , __le__() , __gt__() , or __ge__() , then TypeError is raised. unsafe_hash : If true, force dataclasses to create a __hash__() method, even though it may not be safe to do so. Otherwise, generate a __hash__() method according to how eq and frozen are set.

The default value is False . __hash__() is used by built-in hash() , and when objects are added to hashed collections such as dictionaries and sets. Having a __hash__() implies that instances of the class are immutable. Mutability is a complicated property that depends on the programmer’s intent, the existence and behavior of __eq__() , and the values of the eq and frozen flags in the @dataclass decorator. By default, @dataclass will not implicitly add a __hash__() method unless it is safe to do so.

Neither will it add or change an existing explicitly defined __hash__() method. Setting the class attribute __hash__ = None has a specific meaning to Python, as described in the __hash__() documentation. If __hash__() is not explicitly defined, or if it is set to None , then @dataclass may add an implicit __hash__() method. Although not recommended, you can force @dataclass to create a __hash__() method with unsafe_hash=True .

This might be the case if your class is logically immutable but can still be mutated. This is a specialized use case and should be considered carefully. Here are the rules governing implicit creation of a __hash__() method. Note that you cannot both have an explicit __hash__() method in your dataclass and set unsafe_hash=True ; this will result in a TypeError . If eq and frozen are both true, by default @dataclass will generate a __hash__() method for you.

If eq is true and frozen is false, __hash__() will be set to None , marking it unhashable (which it is, since it is mutable). If eq is false, __hash__() will be left untouched meaning the __hash__() method of the superclass will be used (if the superclass is object , this means it will fall back to id-based hashing). frozen : If true (the default is False ), assigning to fields will generate an exception. This emulates read-only frozen instances.

See the discussion below. If __setattr__() or __delattr__() is defined in the class and frozen is true, then TypeError is raised. match_args : If true (the default is True ), the __match_args__ tuple will be created from the list of non keyword-only parameters to the generated __init__() method (even if __init__() is not generated, see above). If false, or if __match_args__ is already defined in the class, then __match_args__ will not be generated.

Added in version 3.10. kw_only : If true (the default value is False ), then all fields will be marked as keyword-only. If a field is marked as keyword-only, then the only effect is that the __init__() parameter generated from a keyword-only field must be specified with a keyword when __init__() is called. See the parameter glossary entry for details. Also see the KW_ONLY section. Keyword-only fields are not included in __match_args__ .

Added in version 3.10. slots : If true (the default is False ), __slots__ attribute will be generated and new class will be returned instead of the original one. If __slots__ is already defined in the class, then TypeError is raised. Warning Passing parameters to a base class __init_subclass__() when using slots=True will result in a TypeError . Either use __init_subclass__ with no parameters or use default values as a workaround.

See gh-91126 for full details. Added in version 3.10. Changed in version 3.11: If a field name is already included in the __slots__ of a base class, it will not be in

The rest of this page is on the live site.