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