1:mod:`dataclasses` --- Data Classes 2=================================== 3 4.. module:: dataclasses 5 :synopsis: Generate special methods on user-defined classes. 6 7.. moduleauthor:: Eric V. Smith <eric@trueblade.com> 8.. sectionauthor:: Eric V. Smith <eric@trueblade.com> 9 10**Source code:** :source:`Lib/dataclasses.py` 11 12-------------- 13 14This module provides a decorator and functions for automatically 15adding generated :term:`special method`\s such as :meth:`__init__` and 16:meth:`__repr__` to user-defined classes. It was originally described 17in :pep:`557`. 18 19The member variables to use in these generated methods are defined 20using :pep:`526` type annotations. For example this code:: 21 22 from dataclasses import dataclass 23 24 @dataclass 25 class InventoryItem: 26 """Class for keeping track of an item in inventory.""" 27 name: str 28 unit_price: float 29 quantity_on_hand: int = 0 30 31 def total_cost(self) -> float: 32 return self.unit_price * self.quantity_on_hand 33 34Will add, among other things, a :meth:`__init__` that looks like:: 35 36 def __init__(self, name: str, unit_price: float, quantity_on_hand: int=0): 37 self.name = name 38 self.unit_price = unit_price 39 self.quantity_on_hand = quantity_on_hand 40 41Note that this method is automatically added to the class: it is not 42directly specified in the ``InventoryItem`` definition shown above. 43 44.. versionadded:: 3.7 45 46Module-level decorators, classes, and functions 47----------------------------------------------- 48 49.. decorator:: dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False) 50 51 This function is a :term:`decorator` that is used to add generated 52 :term:`special method`\s to classes, as described below. 53 54 The :func:`dataclass` decorator examines the class to find 55 ``field``\s. A ``field`` is defined as class variable that has a 56 :term:`type annotation <variable annotation>`. With two 57 exceptions described below, nothing in :func:`dataclass` 58 examines the type specified in the variable annotation. 59 60 The order of the fields in all of the generated methods is the 61 order in which they appear in the class definition. 62 63 The :func:`dataclass` decorator will add various "dunder" methods to 64 the class, described below. If any of the added methods already 65 exist on the class, the behavior depends on the parameter, as documented 66 below. The decorator returns the same class that is called on; no new 67 class is created. 68 69 If :func:`dataclass` is used just as a simple decorator with no parameters, 70 it acts as if it has the default values documented in this 71 signature. That is, these three uses of :func:`dataclass` are 72 equivalent:: 73 74 @dataclass 75 class C: 76 ... 77 78 @dataclass() 79 class C: 80 ... 81 82 @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False) 83 class C: 84 ... 85 86 The parameters to :func:`dataclass` are: 87 88 - ``init``: If true (the default), a :meth:`__init__` method will be 89 generated. 90 91 If the class already defines :meth:`__init__`, this parameter is 92 ignored. 93 94 - ``repr``: If true (the default), a :meth:`__repr__` method will be 95 generated. The generated repr string will have the class name and 96 the name and repr of each field, in the order they are defined in 97 the class. Fields that are marked as being excluded from the repr 98 are not included. For example: 99 ``InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)``. 100 101 If the class already defines :meth:`__repr__`, this parameter is 102 ignored. 103 104 - ``eq``: If true (the default), an :meth:`__eq__` method will be 105 generated. This method compares the class as if it were a tuple 106 of its fields, in order. Both instances in the comparison must 107 be of the identical type. 108 109 If the class already defines :meth:`__eq__`, this parameter is 110 ignored. 111 112 - ``order``: If true (the default is ``False``), :meth:`__lt__`, 113 :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` methods will be 114 generated. These compare the class as if it were a tuple of its 115 fields, in order. Both instances in the comparison must be of the 116 identical type. If ``order`` is true and ``eq`` is false, a 117 :exc:`ValueError` is raised. 118 119 If the class already defines any of :meth:`__lt__`, 120 :meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`, then 121 :exc:`TypeError` is raised. 122 123 - ``unsafe_hash``: If ``False`` (the default), a :meth:`__hash__` method 124 is generated according to how ``eq`` and ``frozen`` are set. 125 126 :meth:`__hash__` is used by built-in :meth:`hash()`, and when objects are 127 added to hashed collections such as dictionaries and sets. Having a 128 :meth:`__hash__` implies that instances of the class are immutable. 129 Mutability is a complicated property that depends on the programmer's 130 intent, the existence and behavior of :meth:`__eq__`, and the values of 131 the ``eq`` and ``frozen`` flags in the :func:`dataclass` decorator. 132 133 By default, :func:`dataclass` will not implicitly add a :meth:`__hash__` 134 method unless it is safe to do so. Neither will it add or change an 135 existing explicitly defined :meth:`__hash__` method. Setting the class 136 attribute ``__hash__ = None`` has a specific meaning to Python, as 137 described in the :meth:`__hash__` documentation. 138 139 If :meth:`__hash__` is not explicit defined, or if it is set to ``None``, 140 then :func:`dataclass` *may* add an implicit :meth:`__hash__` method. 141 Although not recommended, you can force :func:`dataclass` to create a 142 :meth:`__hash__` method with ``unsafe_hash=True``. This might be the case 143 if your class is logically immutable but can nonetheless be mutated. 144 This is a specialized use case and should be considered carefully. 145 146 Here are the rules governing implicit creation of a :meth:`__hash__` 147 method. Note that you cannot both have an explicit :meth:`__hash__` 148 method in your dataclass and set ``unsafe_hash=True``; this will result 149 in a :exc:`TypeError`. 150 151 If ``eq`` and ``frozen`` are both true, by default :func:`dataclass` will 152 generate a :meth:`__hash__` method for you. If ``eq`` is true and 153 ``frozen`` is false, :meth:`__hash__` will be set to ``None``, marking it 154 unhashable (which it is, since it is mutable). If ``eq`` is false, 155 :meth:`__hash__` will be left untouched meaning the :meth:`__hash__` 156 method of the superclass will be used (if the superclass is 157 :class:`object`, this means it will fall back to id-based hashing). 158 159 - ``frozen``: If true (the default is ``False``), assigning to fields will 160 generate an exception. This emulates read-only frozen instances. If 161 :meth:`__setattr__` or :meth:`__delattr__` is defined in the class, then 162 :exc:`TypeError` is raised. See the discussion below. 163 164 ``field``\s may optionally specify a default value, using normal 165 Python syntax:: 166 167 @dataclass 168 class C: 169 a: int # 'a' has no default value 170 b: int = 0 # assign a default value for 'b' 171 172 In this example, both ``a`` and ``b`` will be included in the added 173 :meth:`__init__` method, which will be defined as:: 174 175 def __init__(self, a: int, b: int = 0): 176 177 :exc:`TypeError` will be raised if a field without a default value 178 follows a field with a default value. This is true either when this 179 occurs in a single class, or as a result of class inheritance. 180 181.. function:: field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None) 182 183 For common and simple use cases, no other functionality is 184 required. There are, however, some dataclass features that 185 require additional per-field information. To satisfy this need for 186 additional information, you can replace the default field value 187 with a call to the provided :func:`field` function. For example:: 188 189 @dataclass 190 class C: 191 mylist: list[int] = field(default_factory=list) 192 193 c = C() 194 c.mylist += [1, 2, 3] 195 196 As shown above, the ``MISSING`` value is a sentinel object used to 197 detect if the ``default`` and ``default_factory`` parameters are 198 provided. This sentinel is used because ``None`` is a valid value 199 for ``default``. No code should directly use the ``MISSING`` 200 value. 201 202 The parameters to :func:`field` are: 203 204 - ``default``: If provided, this will be the default value for this 205 field. This is needed because the :meth:`field` call itself 206 replaces the normal position of the default value. 207 208 - ``default_factory``: If provided, it must be a zero-argument 209 callable that will be called when a default value is needed for 210 this field. Among other purposes, this can be used to specify 211 fields with mutable default values, as discussed below. It is an 212 error to specify both ``default`` and ``default_factory``. 213 214 - ``init``: If true (the default), this field is included as a 215 parameter to the generated :meth:`__init__` method. 216 217 - ``repr``: If true (the default), this field is included in the 218 string returned by the generated :meth:`__repr__` method. 219 220 - ``compare``: If true (the default), this field is included in the 221 generated equality and comparison methods (:meth:`__eq__`, 222 :meth:`__gt__`, et al.). 223 224 - ``hash``: This can be a bool or ``None``. If true, this field is 225 included in the generated :meth:`__hash__` method. If ``None`` (the 226 default), use the value of ``compare``: this would normally be 227 the expected behavior. A field should be considered in the hash 228 if it's used for comparisons. Setting this value to anything 229 other than ``None`` is discouraged. 230 231 One possible reason to set ``hash=False`` but ``compare=True`` 232 would be if a field is expensive to compute a hash value for, 233 that field is needed for equality testing, and there are other 234 fields that contribute to the type's hash value. Even if a field 235 is excluded from the hash, it will still be used for comparisons. 236 237 - ``metadata``: This can be a mapping or None. None is treated as 238 an empty dict. This value is wrapped in 239 :func:`~types.MappingProxyType` to make it read-only, and exposed 240 on the :class:`Field` object. It is not used at all by Data 241 Classes, and is provided as a third-party extension mechanism. 242 Multiple third-parties can each have their own key, to use as a 243 namespace in the metadata. 244 245 If the default value of a field is specified by a call to 246 :func:`field()`, then the class attribute for this field will be 247 replaced by the specified ``default`` value. If no ``default`` is 248 provided, then the class attribute will be deleted. The intent is 249 that after the :func:`dataclass` decorator runs, the class 250 attributes will all contain the default values for the fields, just 251 as if the default value itself were specified. For example, 252 after:: 253 254 @dataclass 255 class C: 256 x: int 257 y: int = field(repr=False) 258 z: int = field(repr=False, default=10) 259 t: int = 20 260 261 The class attribute ``C.z`` will be ``10``, the class attribute 262 ``C.t`` will be ``20``, and the class attributes ``C.x`` and 263 ``C.y`` will not be set. 264 265.. class:: Field 266 267 :class:`Field` objects describe each defined field. These objects 268 are created internally, and are returned by the :func:`fields` 269 module-level method (see below). Users should never instantiate a 270 :class:`Field` object directly. Its documented attributes are: 271 272 - ``name``: The name of the field. 273 274 - ``type``: The type of the field. 275 276 - ``default``, ``default_factory``, ``init``, ``repr``, ``hash``, 277 ``compare``, and ``metadata`` have the identical meaning and 278 values as they do in the :func:`field` declaration. 279 280 Other attributes may exist, but they are private and must not be 281 inspected or relied on. 282 283.. function:: fields(class_or_instance) 284 285 Returns a tuple of :class:`Field` objects that define the fields for this 286 dataclass. Accepts either a dataclass, or an instance of a dataclass. 287 Raises :exc:`TypeError` if not passed a dataclass or instance of one. 288 Does not return pseudo-fields which are ``ClassVar`` or ``InitVar``. 289 290.. function:: asdict(instance, *, dict_factory=dict) 291 292 Converts the dataclass ``instance`` to a dict (by using the 293 factory function ``dict_factory``). Each dataclass is converted 294 to a dict of its fields, as ``name: value`` pairs. dataclasses, dicts, 295 lists, and tuples are recursed into. For example:: 296 297 @dataclass 298 class Point: 299 x: int 300 y: int 301 302 @dataclass 303 class C: 304 mylist: list[Point] 305 306 p = Point(10, 20) 307 assert asdict(p) == {'x': 10, 'y': 20} 308 309 c = C([Point(0, 0), Point(10, 4)]) 310 assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]} 311 312 Raises :exc:`TypeError` if ``instance`` is not a dataclass instance. 313 314.. function:: astuple(instance, *, tuple_factory=tuple) 315 316 Converts the dataclass ``instance`` to a tuple (by using the 317 factory function ``tuple_factory``). Each dataclass is converted 318 to a tuple of its field values. dataclasses, dicts, lists, and 319 tuples are recursed into. 320 321 Continuing from the previous example:: 322 323 assert astuple(p) == (10, 20) 324 assert astuple(c) == ([(0, 0), (10, 4)],) 325 326 Raises :exc:`TypeError` if ``instance`` is not a dataclass instance. 327 328.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False) 329 330 Creates a new dataclass with name ``cls_name``, fields as defined 331 in ``fields``, base classes as given in ``bases``, and initialized 332 with a namespace as given in ``namespace``. ``fields`` is an 333 iterable whose elements are each either ``name``, ``(name, type)``, 334 or ``(name, type, Field)``. If just ``name`` is supplied, 335 ``typing.Any`` is used for ``type``. The values of ``init``, 336 ``repr``, ``eq``, ``order``, ``unsafe_hash``, and ``frozen`` have 337 the same meaning as they do in :func:`dataclass`. 338 339 This function is not strictly required, because any Python 340 mechanism for creating a new class with ``__annotations__`` can 341 then apply the :func:`dataclass` function to convert that class to 342 a dataclass. This function is provided as a convenience. For 343 example:: 344 345 C = make_dataclass('C', 346 [('x', int), 347 'y', 348 ('z', int, field(default=5))], 349 namespace={'add_one': lambda self: self.x + 1}) 350 351 Is equivalent to:: 352 353 @dataclass 354 class C: 355 x: int 356 y: 'typing.Any' 357 z: int = 5 358 359 def add_one(self): 360 return self.x + 1 361 362.. function:: replace(instance, /, **changes) 363 364 Creates a new object of the same type of ``instance``, replacing 365 fields with values from ``changes``. If ``instance`` is not a Data 366 Class, raises :exc:`TypeError`. If values in ``changes`` do not 367 specify fields, raises :exc:`TypeError`. 368 369 The newly returned object is created by calling the :meth:`__init__` 370 method of the dataclass. This ensures that 371 :meth:`__post_init__`, if present, is also called. 372 373 Init-only variables without default values, if any exist, must be 374 specified on the call to :func:`replace` so that they can be passed to 375 :meth:`__init__` and :meth:`__post_init__`. 376 377 It is an error for ``changes`` to contain any fields that are 378 defined as having ``init=False``. A :exc:`ValueError` will be raised 379 in this case. 380 381 Be forewarned about how ``init=False`` fields work during a call to 382 :func:`replace`. They are not copied from the source object, but 383 rather are initialized in :meth:`__post_init__`, if they're 384 initialized at all. It is expected that ``init=False`` fields will 385 be rarely and judiciously used. If they are used, it might be wise 386 to have alternate class constructors, or perhaps a custom 387 ``replace()`` (or similarly named) method which handles instance 388 copying. 389 390.. function:: is_dataclass(class_or_instance) 391 392 Return ``True`` if its parameter is a dataclass or an instance of one, 393 otherwise return ``False``. 394 395 If you need to know if a class is an instance of a dataclass (and 396 not a dataclass itself), then add a further check for ``not 397 isinstance(obj, type)``:: 398 399 def is_dataclass_instance(obj): 400 return is_dataclass(obj) and not isinstance(obj, type) 401 402Post-init processing 403-------------------- 404 405The generated :meth:`__init__` code will call a method named 406:meth:`__post_init__`, if :meth:`__post_init__` is defined on the 407class. It will normally be called as ``self.__post_init__()``. 408However, if any ``InitVar`` fields are defined, they will also be 409passed to :meth:`__post_init__` in the order they were defined in the 410class. If no :meth:`__init__` method is generated, then 411:meth:`__post_init__` will not automatically be called. 412 413Among other uses, this allows for initializing field values that 414depend on one or more other fields. For example:: 415 416 @dataclass 417 class C: 418 a: float 419 b: float 420 c: float = field(init=False) 421 422 def __post_init__(self): 423 self.c = self.a + self.b 424 425See the section below on init-only variables for ways to pass 426parameters to :meth:`__post_init__`. Also see the warning about how 427:func:`replace` handles ``init=False`` fields. 428 429Class variables 430--------------- 431 432One of two places where :func:`dataclass` actually inspects the type 433of a field is to determine if a field is a class variable as defined 434in :pep:`526`. It does this by checking if the type of the field is 435``typing.ClassVar``. If a field is a ``ClassVar``, it is excluded 436from consideration as a field and is ignored by the dataclass 437mechanisms. Such ``ClassVar`` pseudo-fields are not returned by the 438module-level :func:`fields` function. 439 440Init-only variables 441------------------- 442 443The other place where :func:`dataclass` inspects a type annotation is to 444determine if a field is an init-only variable. It does this by seeing 445if the type of a field is of type ``dataclasses.InitVar``. If a field 446is an ``InitVar``, it is considered a pseudo-field called an init-only 447field. As it is not a true field, it is not returned by the 448module-level :func:`fields` function. Init-only fields are added as 449parameters to the generated :meth:`__init__` method, and are passed to 450the optional :meth:`__post_init__` method. They are not otherwise used 451by dataclasses. 452 453For example, suppose a field will be initialized from a database, if a 454value is not provided when creating the class:: 455 456 @dataclass 457 class C: 458 i: int 459 j: int = None 460 database: InitVar[DatabaseType] = None 461 462 def __post_init__(self, database): 463 if self.j is None and database is not None: 464 self.j = database.lookup('j') 465 466 c = C(10, database=my_database) 467 468In this case, :func:`fields` will return :class:`Field` objects for ``i`` and 469``j``, but not for ``database``. 470 471Frozen instances 472---------------- 473 474It is not possible to create truly immutable Python objects. However, 475by passing ``frozen=True`` to the :meth:`dataclass` decorator you can 476emulate immutability. In that case, dataclasses will add 477:meth:`__setattr__` and :meth:`__delattr__` methods to the class. These 478methods will raise a :exc:`FrozenInstanceError` when invoked. 479 480There is a tiny performance penalty when using ``frozen=True``: 481:meth:`__init__` cannot use simple assignment to initialize fields, and 482must use :meth:`object.__setattr__`. 483 484Inheritance 485----------- 486 487When the dataclass is being created by the :meth:`dataclass` decorator, 488it looks through all of the class's base classes in reverse MRO (that 489is, starting at :class:`object`) and, for each dataclass that it finds, 490adds the fields from that base class to an ordered mapping of fields. 491After all of the base class fields are added, it adds its own fields 492to the ordered mapping. All of the generated methods will use this 493combined, calculated ordered mapping of fields. Because the fields 494are in insertion order, derived classes override base classes. An 495example:: 496 497 @dataclass 498 class Base: 499 x: Any = 15.0 500 y: int = 0 501 502 @dataclass 503 class C(Base): 504 z: int = 10 505 x: int = 15 506 507The final list of fields is, in order, ``x``, ``y``, ``z``. The final 508type of ``x`` is ``int``, as specified in class ``C``. 509 510The generated :meth:`__init__` method for ``C`` will look like:: 511 512 def __init__(self, x: int = 15, y: int = 0, z: int = 10): 513 514Default factory functions 515------------------------- 516 517 If a :func:`field` specifies a ``default_factory``, it is called with 518 zero arguments when a default value for the field is needed. For 519 example, to create a new instance of a list, use:: 520 521 mylist: list = field(default_factory=list) 522 523 If a field is excluded from :meth:`__init__` (using ``init=False``) 524 and the field also specifies ``default_factory``, then the default 525 factory function will always be called from the generated 526 :meth:`__init__` function. This happens because there is no other 527 way to give the field an initial value. 528 529Mutable default values 530---------------------- 531 532 Python stores default member variable values in class attributes. 533 Consider this example, not using dataclasses:: 534 535 class C: 536 x = [] 537 def add(self, element): 538 self.x.append(element) 539 540 o1 = C() 541 o2 = C() 542 o1.add(1) 543 o2.add(2) 544 assert o1.x == [1, 2] 545 assert o1.x is o2.x 546 547 Note that the two instances of class ``C`` share the same class 548 variable ``x``, as expected. 549 550 Using dataclasses, *if* this code was valid:: 551 552 @dataclass 553 class D: 554 x: List = [] 555 def add(self, element): 556 self.x += element 557 558 it would generate code similar to:: 559 560 class D: 561 x = [] 562 def __init__(self, x=x): 563 self.x = x 564 def add(self, element): 565 self.x += element 566 567 assert D().x is D().x 568 569 This has the same issue as the original example using class ``C``. 570 That is, two instances of class ``D`` that do not specify a value for 571 ``x`` when creating a class instance will share the same copy of 572 ``x``. Because dataclasses just use normal Python class creation 573 they also share this behavior. There is no general way for Data 574 Classes to detect this condition. Instead, dataclasses will raise a 575 :exc:`TypeError` if it detects a default parameter of type ``list``, 576 ``dict``, or ``set``. This is a partial solution, but it does protect 577 against many common errors. 578 579 Using default factory functions is a way to create new instances of 580 mutable types as default values for fields:: 581 582 @dataclass 583 class D: 584 x: list = field(default_factory=list) 585 586 assert D().x is not D().x 587 588Exceptions 589---------- 590 591.. exception:: FrozenInstanceError 592 593 Raised when an implicitly defined :meth:`__setattr__` or 594 :meth:`__delattr__` is called on a dataclass which was defined with 595 ``frozen=True``. 596