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