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 explicitly 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``. It is a subclass of :exc:`AttributeError`.
596