python-docs-it/library/dataclasses.po at 3.12 · python/python-docs-it

861 lines (740 loc) · 31.2 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2019, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
"Project-Id-Version: Python 3.7\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-01 22:23+0200\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: library/dataclasses.rst:2
msgid ":mod:`!dataclasses` --- Data Classes"
#: library/dataclasses.rst:10
msgid "**Source code:** :source:`Lib/dataclasses.py`"
#: library/dataclasses.rst:14
"This module provides a decorator and functions for automatically adding "
"generated :term:`special methods <special method>` such as :meth:`~object."
"__init__` and :meth:`~object.__repr__` to user-defined classes.  It was "
"originally described in :pep:`557`."
#: library/dataclasses.rst:19
"The member variables to use in these generated methods are defined using :"
"pep:`526` type annotations.  For example, this code::"
#: library/dataclasses.rst:34
msgid "will add, among other things, a :meth:`!__init__` that looks like::"
#: library/dataclasses.rst:41
"Note that this method is automatically added to the class: it is not "
"directly specified in the :class:`!InventoryItem` definition shown above."
#: library/dataclasses.rst:47
msgid "Module contents"
#: library/dataclasses.rst:51
"This function is a :term:`decorator` that is used to add generated :term:"
"`special methods <special method>` to classes, as described below."
#: library/dataclasses.rst:54
"The ``@dataclass`` decorator examines the class to find ``field``\\s.  A "
"``field`` is defined as a class variable that has a :term:`type annotation "
"<variable annotation>`.  With two exceptions described below, nothing in "
"``@dataclass`` examines the type specified in the variable annotation."
#: library/dataclasses.rst:60
"The order of the fields in all of the generated methods is the order in "
"which they appear in the class definition."
#: library/dataclasses.rst:63
"The ``@dataclass`` decorator will add various \"dunder\" methods to the "
"class, described below.  If any of the added methods already exist in the "
"class, the behavior depends on the parameter, as documented below. The "
"decorator returns the same class that it is called on; no new class is "
#: library/dataclasses.rst:69
"If ``@dataclass`` is used just as a simple decorator with no parameters, it "
"acts as if it has the default values documented in this signature.  That is, "
"these three uses of ``@dataclass`` are equivalent::"
#: library/dataclasses.rst:87
msgid "The parameters to ``@dataclass`` are:"
#: library/dataclasses.rst:89
"*init*: If true (the default), a :meth:`~object.__init__` method will be "
"generated."
#: library/dataclasses.rst:92
"If the class already defines :meth:`!__init__`, this parameter is ignored."
#: library/dataclasses.rst:95
"*repr*: If true (the default), a :meth:`~object.__repr__` method will be "
"generated.  The generated repr string will have the class name and the name "
"and repr of each field, in the order they are defined in the class.  Fields "
"that are marked as being excluded from the repr are not included.  For "
"example: ``InventoryItem(name='widget', unit_price=3.0, "
"quantity_on_hand=10)``."
#: library/dataclasses.rst:102
"If the class already defines :meth:`!__repr__`, this parameter is ignored."
#: library/dataclasses.rst:105
"*eq*: If true (the default), an :meth:`~object.__eq__` method will be "
"generated.  This method compares the class as if it were a tuple of its "
"fields, in order.  Both instances in the comparison must be of the identical "
#: library/dataclasses.rst:110
"If the class already defines :meth:`!__eq__`, this parameter is ignored."
#: library/dataclasses.rst:113
"*order*: If true (the default is ``False``), :meth:`~object.__lt__`, :meth:"
"`~object.__le__`, :meth:`~object.__gt__`, and :meth:`~object.__ge__` methods "
"will be generated.  These compare the class as if it were a tuple of its "
"fields, in order.  Both instances in the comparison must be of the identical "
"type.  If *order* is true and *eq* is false, a :exc:`ValueError` is raised."
#: library/dataclasses.rst:120
"If the class already defines any of :meth:`!__lt__`, :meth:`!__le__`, :meth:"
"`!__gt__`, or :meth:`!__ge__`, then :exc:`TypeError` is raised."
#: library/dataclasses.rst:124
"*unsafe_hash*: If ``False`` (the default), a :meth:`~object.__hash__` method "
"is generated according to how *eq* and *frozen* are set."
#: library/dataclasses.rst:127
":meth:`!__hash__` is used by built-in :meth:`hash()`, and when objects are "
"added to hashed collections such as dictionaries and sets.  Having a :meth:`!"
"__hash__` implies that instances of the class are immutable. Mutability is a "
"complicated property that depends on the programmer's intent, the existence "
"and behavior of :meth:`!__eq__`, and the values of the *eq* and *frozen* "
"flags in the ``@dataclass`` decorator."
#: library/dataclasses.rst:134
"By default, ``@dataclass`` will not implicitly add a :meth:`~object."
"__hash__` method unless it is safe to do so.  Neither will it add or change "
"an existing explicitly defined :meth:`!__hash__` method.  Setting the class "
"attribute ``__hash__ = None`` has a specific meaning to Python, as described "
"in the :meth:`!__hash__` documentation."
#: library/dataclasses.rst:140
"If :meth:`!__hash__` is not explicitly defined, or if it is set to ``None``, "
"then ``@dataclass`` *may* add an implicit :meth:`!__hash__` method. Although "
"not recommended, you can force ``@dataclass`` to create a :meth:`!__hash__` "
"method with ``unsafe_hash=True``. This might be the case if your class is "
"logically immutable but can still be mutated. This is a specialized use case "
"and should be considered carefully."
#: library/dataclasses.rst:147
"Here are the rules governing implicit creation of a :meth:`!__hash__` "
"method.  Note that you cannot both have an explicit :meth:`!__hash__` method "
"in your dataclass and set ``unsafe_hash=True``; this will result in a :exc:"
"`TypeError`."
#: library/dataclasses.rst:152
"If *eq* and *frozen* are both true, by default ``@dataclass`` will generate "
"a :meth:`!__hash__` method for you.  If *eq* is true and *frozen* is false, :"
"meth:`!__hash__` will be set to ``None``, marking it unhashable (which it "
"is, since it is mutable).  If *eq* is false, :meth:`!__hash__` will be left "
"untouched meaning the :meth:`!__hash__` method of the superclass will be "
"used (if the superclass is :class:`object`, this means it will fall back to "
"id-based hashing)."
#: library/dataclasses.rst:160
"*frozen*: If true (the default is ``False``), assigning to fields will "
"generate an exception.  This emulates read-only frozen instances.  If :meth:"
"`~object.__setattr__` or :meth:`~object.__delattr__` is defined in the "
"class, then :exc:`TypeError` is raised.  See the discussion below."
#: library/dataclasses.rst:165
"*match_args*: If true (the default is ``True``), the :attr:`~object."
"__match_args__` tuple will be created from the list of parameters to the "
"generated :meth:`~object.__init__` method (even if :meth:`!__init__` is not "
"generated, see above).  If false, or if :attr:`!__match_args__` is already "
"defined in the class, then :attr:`!__match_args__` will not be generated."
#: library/dataclasses.rst:174
"*kw_only*: If true (the default value is ``False``), then all fields will be "
"marked as keyword-only.  If a field is marked as keyword-only, then the only "
"effect is that the :meth:`~object.__init__` parameter generated from a "
"keyword-only field must be specified with a keyword when :meth:`!__init__` "
"is called.  There is no effect on any other aspect of dataclasses.  See the :"
"term:`parameter` glossary entry for details.  Also see the :const:`KW_ONLY` "
#: library/dataclasses.rst:185
"*slots*: If true (the default is ``False``), :attr:`~object.__slots__` "
"attribute will be generated and new class will be returned instead of the "
"original one. If :attr:`!__slots__` is already defined in the class, then :"
"exc:`TypeError` is raised. Calling no-arg :func:`super` in dataclasses using "
"``slots=True`` will result in the following exception being raised: "
"``TypeError: super(type, obj): obj must be an instance or subtype of type``. "
"The two-arg :func:`super` is a valid workaround. See :gh:`90562` for full "
#: library/dataclasses.rst:195
"If a field name is already included in the :attr:`!__slots__` of a base "
"class, it will not be included in the generated :attr:`!__slots__` to "
"prevent :ref:`overriding them <datamodel-note-slots>`. Therefore, do not "
"use :attr:`!__slots__` to retrieve the field names of a dataclass. Use :func:"
"`fields` instead. To be able to determine inherited slots, base class :attr:"
"`!__slots__` may be any iterable, but *not* an iterator."
#: library/dataclasses.rst:205
"*weakref_slot*: If true (the default is ``False``), add a slot named "
"\"__weakref__\", which is required to make an instance weakref-able.  It is "
"an error to specify ``weakref_slot=True`` without also specifying "
"``slots=True``."
#: library/dataclasses.rst:212
"``field``\\s may optionally specify a default value, using normal Python "
#: library/dataclasses.rst:220
"In this example, both :attr:`!a` and :attr:`!b` will be included in the "
"added :meth:`~object.__init__` method, which will be defined as::"
#: library/dataclasses.rst:225
":exc:`TypeError` will be raised if a field without a default value follows a "
"field with a default value.  This is true whether this occurs in a single "
"class, or as a result of class inheritance."
#: library/dataclasses.rst:231
"For common and simple use cases, no other functionality is required.  There "
"are, however, some dataclass features that require additional per-field "
"information.  To satisfy this need for additional information, you can "
"replace the default field value with a call to the provided :func:`!field` "
"function.  For example::"
#: library/dataclasses.rst:244
"As shown above, the :const:`MISSING` value is a sentinel object used to "
"detect if some parameters are provided by the user. This sentinel is used "
"because ``None`` is a valid value for some parameters with a distinct "
"meaning.  No code should directly use the :const:`MISSING` value."
#: library/dataclasses.rst:249
msgid "The parameters to :func:`!field` are:"
#: library/dataclasses.rst:251
"*default*: If provided, this will be the default value for this field.  This "
"is needed because the :func:`!field` call itself replaces the normal "
"position of the default value."
#: library/dataclasses.rst:255
"*default_factory*: If provided, it must be a zero-argument callable that "
"will be called when a default value is needed for this field.  Among other "
"purposes, this can be used to specify fields with mutable default values, as "
"discussed below.  It is an error to specify both *default* and "
"*default_factory*."
#: library/dataclasses.rst:261
"*init*: If true (the default), this field is included as a parameter to the "
"generated :meth:`~object.__init__` method."
#: library/dataclasses.rst:264
"*repr*: If true (the default), this field is included in the string returned "
"by the generated :meth:`~object.__repr__` method."
#: library/dataclasses.rst:267
"*hash*: This can be a bool or ``None``.  If true, this field is included in "
"the generated :meth:`~object.__hash__` method.  If ``None`` (the default), "
"use the value of *compare*: this would normally be the expected behavior.  A "
"field should be considered in the hash if it's used for comparisons.  "
"Setting this value to anything other than ``None`` is discouraged."
#: library/dataclasses.rst:274
"One possible reason to set ``hash=False`` but ``compare=True`` would be if a "
"field is expensive to compute a hash value for, that field is needed for "
"equality testing, and there are other fields that contribute to the type's "
"hash value.  Even if a field is excluded from the hash, it will still be "
"used for comparisons."
#: library/dataclasses.rst:280
"*compare*: If true (the default), this field is included in the generated "
"equality and comparison methods (:meth:`~object.__eq__`, :meth:`~object."
"__gt__`, et al.)."
#: library/dataclasses.rst:284
"*metadata*: This can be a mapping or ``None``. ``None`` is treated as an "
"empty dict.  This value is wrapped in :func:`~types.MappingProxyType` to "
"make it read-only, and exposed on the :class:`Field` object. It is not used "
"at all by Data Classes, and is provided as a third-party extension "
"mechanism. Multiple third-parties can each have their own key, to use as a "
"namespace in the metadata."
#: library/dataclasses.rst:292
"*kw_only*: If true, this field will be marked as keyword-only. This is used "
"when the generated :meth:`~object.__init__` method's parameters are computed."
#: library/dataclasses.rst:298
"If the default value of a field is specified by a call to :func:`!field`, "
"then the class attribute for this field will be replaced by the specified "
"*default* value.  If *default* is not provided, then the class attribute "
"will be deleted.  The intent is that after the :func:`@dataclass "
"<dataclass>` decorator runs, the class attributes will all contain the "
"default values for the fields, just as if the default value itself were "
"specified.  For example, after::"
#: library/dataclasses.rst:314
"The class attribute :attr:`!C.z` will be ``10``, the class attribute :attr:`!"
"C.t` will be ``20``, and the class attributes :attr:`!C.x` and :attr:`!C.y` "
"will not be set."
#: library/dataclasses.rst:320
":class:`!Field` objects describe each defined field. These objects are "
"created internally, and are returned by the :func:`fields` module-level "
"method (see below).  Users should never instantiate a :class:`!Field` object "
"directly.  Its documented attributes are:"
#: library/dataclasses.rst:325
msgid ":attr:`!name`: The name of the field."
#: library/dataclasses.rst:326
msgid ":attr:`!type`: The type of the field."
#: library/dataclasses.rst:327
":attr:`!default`, :attr:`!default_factory`, :attr:`!init`, :attr:`!repr`, :"
"attr:`!hash`, :attr:`!compare`, :attr:`!metadata`, and :attr:`!kw_only` have "
"the identical meaning and values as they do in the :func:`field` function."
#: library/dataclasses.rst:331
"Other attributes may exist, but they are private and must not be inspected "
"or relied on."
#: library/dataclasses.rst:336
"Returns a tuple of :class:`Field` objects that define the fields for this "
"dataclass.  Accepts either a dataclass, or an instance of a dataclass. "
"Raises :exc:`TypeError` if not passed a dataclass or instance of one. Does "
"not return pseudo-fields which are ``ClassVar`` or ``InitVar``."
#: library/dataclasses.rst:343
"Converts the dataclass *obj* to a dict (by using the factory function "
"*dict_factory*).  Each dataclass is converted to a dict of its fields, as "
"``name: value`` pairs.  dataclasses, dicts, lists, and tuples are recursed "
"into.  Other objects are copied with :func:`copy.deepcopy`."
#: library/dataclasses.rst:349
msgid "Example of using :func:`!asdict` on nested dataclasses::"
#: library/dataclasses.rst:386
msgid "To create a shallow copy, the following workaround may be used::"
#: library/dataclasses.rst:370
":func:`!asdict` raises :exc:`TypeError` if *obj* is not a dataclass instance."
#: library/dataclasses.rst:375
"Converts the dataclass *obj* to a tuple (by using the factory function "
"*tuple_factory*).  Each dataclass is converted to a tuple of its field "
"values.  dataclasses, dicts, lists, and tuples are recursed into. Other "
"objects are copied with :func:`copy.deepcopy`."
#: library/dataclasses.rst:381
msgid "Continuing from the previous example::"
#: library/dataclasses.rst:390
":func:`!astuple` raises :exc:`TypeError` if *obj* is not a dataclass "
"instance."
#: library/dataclasses.rst:395
"Creates a new dataclass with name *cls_name*, fields as defined in *fields*, "
"base classes as given in *bases*, and initialized with a namespace as given "
"in *namespace*.  *fields* is an iterable whose elements are each either "
"``name``, ``(name, type)``, or ``(name, type, Field)``.  If just ``name`` is "
"supplied, :data:`typing.Any` is used for ``type``.  The values of *init*, "
"*repr*, *eq*, *order*, *unsafe_hash*, *frozen*, *match_args*, *kw_only*, "
"*slots*, and *weakref_slot* have the same meaning as they do in :func:"
"`@dataclass <dataclass>`."
#: library/dataclasses.rst:405
"If *module* is defined, the :attr:`!__module__` attribute of the dataclass "
"is set to that value. By default, it is set to the module name of the caller."
#: library/dataclasses.rst:409
"This function is not strictly required, because any Python mechanism for "
"creating a new class with :attr:`!__annotations__` can then apply the :func:"
"`@dataclass <dataclass>` function to convert that class to a dataclass.  "
"This function is provided as a convenience.  For example::"
#: library/dataclasses.rst:421
msgid "Is equivalent to::"
#: library/dataclasses.rst:434
"Creates a new object of the same type as *obj*, replacing fields with values "
"from *changes*.  If *obj* is not a Data Class, raises :exc:`TypeError`.  If "
"keys in *changes* are not field names of the given dataclass, raises :exc:"
"`TypeError`."
#: library/dataclasses.rst:439
"The newly returned object is created by calling the :meth:`~object.__init__` "
"method of the dataclass.  This ensures that :meth:`__post_init__`, if "
"present, is also called."
#: library/dataclasses.rst:443
"Init-only variables without default values, if any exist, must be specified "
"on the call to :func:`!replace` so that they can be passed to :meth:`!"
"__init__` and :meth:`__post_init__`."
#: library/dataclasses.rst:447
"It is an error for *changes* to contain any fields that are defined as "
"having ``init=False``.  A :exc:`ValueError` will be raised in this case."
#: library/dataclasses.rst:451
"Be forewarned about how ``init=False`` fields work during a call to :func:`!"
"replace`.  They are not copied from the source object, but rather are "
"initialized in :meth:`__post_init__`, if they're initialized at all.  It is "
"expected that ``init=False`` fields will be rarely and judiciously used.  If "
"they are used, it might be wise to have alternate class constructors, or "
"perhaps a custom :func:`!replace` (or similarly named) method which handles "
"instance copying."
#: library/dataclasses.rst:462
"Return ``True`` if its parameter is a dataclass (including subclasses of a "
"dataclass) or an instance of one, otherwise return ``False``."
#: library/dataclasses.rst:465
"If you need to know if a class is an instance of a dataclass (and not a "
"dataclass itself), then add a further check for ``not isinstance(obj, "
"type)``::"
#: library/dataclasses.rst:474
msgid "A sentinel value signifying a missing default or default_factory."
#: library/dataclasses.rst:478
"A sentinel value used as a type annotation.  Any fields after a pseudo-field "
"with the type of :const:`!KW_ONLY` are marked as keyword-only fields.  Note "
"that a pseudo-field of type :const:`!KW_ONLY` is otherwise completely "
"ignored.  This includes the name of such a field.  By convention, a name of "
"``_`` is used for a :const:`!KW_ONLY` field.  Keyword-only fields signify :"
"meth:`~object.__init__` parameters that must be specified as keywords when "
"the class is instantiated."
#: library/dataclasses.rst:487
"In this example, the fields ``y`` and ``z`` will be marked as keyword-only "
#: library/dataclasses.rst:498
"In a single dataclass, it is an error to specify more than one field whose "
"type is :const:`!KW_ONLY`."
#: library/dataclasses.rst:505
"Raised when an implicitly defined :meth:`~object.__setattr__` or :meth:"
"`~object.__delattr__` is called on a dataclass which was defined with "
"``frozen=True``. It is a subclass of :exc:`AttributeError`."
#: library/dataclasses.rst:512
msgid "Post-init processing"
#: library/dataclasses.rst:516
"When defined on the class, it will be called by the generated :meth:`~object."
"__init__`, normally as :meth:`!self.__post_init__`. However, if any "
"``InitVar`` fields are defined, they will also be passed to :meth:`!"
"__post_init__` in the order they were defined in the class.  If no :meth:`!"
"__init__` method is generated, then :meth:`!__post_init__` will not "
"automatically be called."
#: library/dataclasses.rst:523
"Among other uses, this allows for initializing field values that depend on "
"one or more other fields.  For example::"
#: library/dataclasses.rst:535
"The :meth:`~object.__init__` method generated by :func:`@dataclass "
"<dataclass>` does not call base class :meth:`!__init__` methods. If the base "
"class has an :meth:`!__init__` method that has to be called, it is common to "
"call this method in a :meth:`__post_init__` method::"
#: library/dataclasses.rst:552
"Note, however, that in general the dataclass-generated :meth:`!__init__` "
"methods don't need to be called, since the derived dataclass will take care "
"of initializing all fields of any base class that is a dataclass itself."
#: library/dataclasses.rst:556
"See the section below on init-only variables for ways to pass parameters to :"
"meth:`!__post_init__`.  Also see the warning about how :func:`replace` "
"handles ``init=False`` fields."
#: library/dataclasses.rst:563
msgid "Class variables"
#: library/dataclasses.rst:565
"One of the few places where :func:`@dataclass <dataclass>` actually inspects "
"the type of a field is to determine if a field is a class variable as "
"defined in :pep:`526`.  It does this by checking if the type of the field "
"is :data:`typing.ClassVar`.  If a field is a ``ClassVar``, it is excluded "
"from consideration as a field and is ignored by the dataclass mechanisms.  "
"Such ``ClassVar`` pseudo-fields are not returned by the module-level :func:"
"`fields` function."
#: library/dataclasses.rst:576
msgid "Init-only variables"
#: library/dataclasses.rst:578
"Another place where :func:`@dataclass <dataclass>` inspects a type "
"annotation is to determine if a field is an init-only variable.  It does "
"this by seeing if the type of a field is of type ``dataclasses.InitVar``.  "
"If a field is an ``InitVar``, it is considered a pseudo-field called an init-"
"only field.  As it is not a true field, it is not returned by the module-"
"level :func:`fields` function.  Init-only fields are added as parameters to "
"the generated :meth:`~object.__init__` method, and are passed to the "
"optional :meth:`__post_init__` method.  They are not otherwise used by "
"dataclasses."
#: library/dataclasses.rst:588
"For example, suppose a field will be initialized from a database, if a value "
"is not provided when creating the class::"
#: library/dataclasses.rst:603
"In this case, :func:`fields` will return :class:`Field` objects for :attr:`!"
"i` and :attr:`!j`, but not for :attr:`!database`."
#: library/dataclasses.rst:609
msgid "Frozen instances"
#: library/dataclasses.rst:611
"It is not possible to create truly immutable Python objects.  However, by "
"passing ``frozen=True`` to the :func:`@dataclass <dataclass>` decorator you "
"can emulate immutability.  In that case, dataclasses will add :meth:`~object."
"__setattr__` and :meth:`~object.__delattr__` methods to the class.  These "
"methods will raise a :exc:`FrozenInstanceError` when invoked."
#: library/dataclasses.rst:617
"There is a tiny performance penalty when using ``frozen=True``: :meth:"
"`~object.__init__` cannot use simple assignment to initialize fields, and "
"must use :meth:`!object.__setattr__`."
#: library/dataclasses.rst:626
msgid "Inheritance"
#: library/dataclasses.rst:628
"When the dataclass is being created by the :func:`@dataclass <dataclass>` "
"decorator, it looks through all of the class's base classes in reverse MRO "
"(that is, starting at :class:`object`) and, for each dataclass that it "
"finds, adds the fields from that base class to an ordered mapping of fields. "
"After all of the base class fields are added, it adds its own fields to the "
"ordered mapping.  All of the generated methods will use this combined, "
"calculated ordered mapping of fields.  Because the fields are in insertion "
"order, derived classes override base classes.  An example::"
#: library/dataclasses.rst:648
"The final list of fields is, in order, :attr:`!x`, :attr:`!y`, :attr:`!z`.  "
"The final type of :attr:`!x` is :class:`int`, as specified in class :class:`!"
#: library/dataclasses.rst:651
"The generated :meth:`~object.__init__` method for :class:`!C` will look "
#: library/dataclasses.rst:656
msgid "Re-ordering of keyword-only parameters in :meth:`!__init__`"
#: library/dataclasses.rst:658
"After the parameters needed for :meth:`~object.__init__` are computed, any "
"keyword-only parameters are moved to come after all regular (non-keyword-"
"only) parameters.  This is a requirement of how keyword-only parameters are "
"implemented in Python: they must come after non-keyword-only parameters."
#: library/dataclasses.rst:664
"In this example, :attr:`!Base.y`, :attr:`!Base.w`, and :attr:`!D.t` are "
"keyword-only fields, and :attr:`!Base.x` and :attr:`!D.z` are regular "
#: library/dataclasses.rst:679
msgid "The generated :meth:`!__init__` method for :class:`!D` will look like::"
#: library/dataclasses.rst:683
"Note that the parameters have been re-ordered from how they appear in the "
"list of fields: parameters derived from regular fields are followed by "
"parameters derived from keyword-only fields."
#: library/dataclasses.rst:687
"The relative ordering of keyword-only parameters is maintained in the re-"
"ordered :meth:`!__init__` parameter list."
#: library/dataclasses.rst:692
msgid "Default factory functions"
#: library/dataclasses.rst:694
"If a :func:`field` specifies a *default_factory*, it is called with zero "
"arguments when a default value for the field is needed.  For example, to "
"create a new instance of a list, use::"
#: library/dataclasses.rst:700
"If a field is excluded from :meth:`~object.__init__` (using ``init=False``) "
"and the field also specifies *default_factory*, then the default factory "
"function will always be called from the generated :meth:`!__init__` "
"function.  This happens because there is no other way to give the field an "
"initial value."
#: library/dataclasses.rst:707
msgid "Mutable default values"
#: library/dataclasses.rst:709
"Python stores default member variable values in class attributes. Consider "
"this example, not using dataclasses::"
#: library/dataclasses.rst:724
"Note that the two instances of class :class:`!C` share the same class "
"variable :attr:`!x`, as expected."
#: library/dataclasses.rst:727
msgid "Using dataclasses, *if* this code was valid::"
#: library/dataclasses.rst:735
msgid "it would generate code similar to::"
#: library/dataclasses.rst:746
"This has the same issue as the original example using class :class:`!C`. "
"That is, two instances of class :class:`!D` that do not specify a value for :"
"attr:`!x` when creating a class instance will share the same copy of :attr:`!"
"x`.  Because dataclasses just use normal Python class creation they also "
"share this behavior.  There is no general way for Data Classes to detect "
"this condition.  Instead, the :func:`@dataclass <dataclass>` decorator will "
"raise a :exc:`ValueError` if it detects an unhashable default parameter.  "
"The assumption is that if a value is unhashable, it is mutable.  This is a "
"partial solution, but it does protect against many common errors."
#: library/dataclasses.rst:757
"Using default factory functions is a way to create new instances of mutable "
"types as default values for fields::"
#: library/dataclasses.rst:766
"Instead of looking for and disallowing objects of type :class:`list`, :class:"
"`dict`, or :class:`set`, unhashable objects are now not allowed as default "
"values.  Unhashability is used to approximate mutability."
#: library/dataclasses.rst:773
msgid "Descriptor-typed fields"
#: library/dataclasses.rst:775
"Fields that are assigned :ref:`descriptor objects <descriptors>` as their "
"default value have the following special behaviors:"
#: library/dataclasses.rst:778
"The value for the field passed to the dataclass's :meth:`~object.__init__` "
"method is passed to the descriptor's :meth:`~object.__set__` method rather "
"than overwriting the descriptor object."
#: library/dataclasses.rst:782
"Similarly, when getting or setting the field, the descriptor's :meth:"
"`~object.__get__` or :meth:`!__set__` method is called rather than returning "
"or overwriting the descriptor object."
#: library/dataclasses.rst:786
"To determine whether a field contains a default value, :func:`@dataclass "
"<dataclass>` will call the descriptor's :meth:`!__get__` method using its "
"class access form: ``descriptor.__get__(obj=None, type=cls)``.  If the "
"descriptor returns a value in this case, it will be used as the field's "
"default. On the other hand, if the descriptor raises :exc:`AttributeError` "
"in this situation, no default value will be provided for the field."
#: library/dataclasses.rst:821
"Note that if a field is annotated with a descriptor type, but is not "
"assigned a descriptor object as its default value, the field will act like a "
"normal field."
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

dataclasses.po

Latest commit

History

dataclasses.po

File metadata and controls
