> **Источник:** https://python-all.ru/3.10/library/dataclasses.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # [`dataclasses`](https://python-all.ru/3.10/library/dataclasses.html#module-dataclasses) – Классы данных **Исходный код:** [Lib/dataclasses.py](https://python-all.ru/src/3.10/Lib/dataclasses.py) --- Этот модуль предоставляет декоратор и функции для автоматического добавления генерируемых [специальных методов](https://python-all.ru/3.10/glossary.html#term-special-method), таких как `__init__()` и `__repr__()`, в пользовательские классы. Изначально он описан в [**PEP 557**](https://python-all.ru/3.10/library/dataclasses.html). Переменные-члены, используемые в этих сгенерированных методах, определяются с помощью аннотаций типов [**PEP 526**](https://python-all.ru/3.10/library/dataclasses.html). Например, следующий код: ```python from dataclasses import dataclass @dataclass class InventoryItem: """Класс для отслеживания предмета в инвентаре.""" name: str unit_price: float quantity_on_hand: int = 0 def total_cost(self) -> float: return self.unit_price * self.quantity_on_hand ``` добавит, среди прочего, метод `__init__()`, который будет выглядеть так: ```python def __init__(self, name: str, unit_price: float, quantity_on_hand: int = 0): self.name = name self.unit_price = unit_price self.quantity_on_hand = quantity_on_hand ``` Обратите внимание, что этот метод добавляется в класс автоматически: он не указан явно в определении `InventoryItem`, показанном выше. Добавлено в версии 3.7. ## Содержимое модуля #### `@dataclasses.dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False)` Эта функция – [декоратор](https://python-all.ru/3.10/glossary.html#term-decorator), который используется для добавления сгенерированных [специальные методы](https://python-all.ru/3.10/glossary.html#term-special-method) в классы, как описано ниже. Декоратор [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) просматривает класс в поисках `field`. `field` определяется как переменная класса, имеющая [аннотацию типа](https://python-all.ru/3.10/glossary.html#term-variable-annotation). За двумя исключениями, описанными ниже, в [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) тип, указанный в аннотации переменной, не проверяется. Порядок полей во всех сгенерированных методах соответствует порядку их объявления в определении класса. Декоратор [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) добавит в класс различные «дандер»-методы, описанные ниже. Если какой-либо из добавляемых методов уже существует в классе, поведение зависит от параметра, как описано ниже. Декоратор возвращает тот же класс, к которому он был применён; новый класс не создаётся. Если [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) используется как простой декоратор без параметров, он ведёт себя так, как если бы использовались значения по умолчанию, описанные в этой сигнатуре. То есть следующие три варианта применения [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) эквивалентны: ```python @dataclass class C: ... @dataclass() class C: ... @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False) class C: ... ``` Параметры [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass): - `init`: Если true (по умолчанию), будет сгенерирован метод `__init__()`. Если класс уже определяет `__init__()`, этот параметр игнорируется. - `repr`: Если true (по умолчанию), будет сгенерирован метод `__repr__()`. Сгенерированная repr-строка будет содержать имя класса и имя и repr каждого поля в порядке их определения в классе. Поля, помеченные как исключённые из repr, не включаются. Например: `InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)`. Если класс уже определяет `__repr__()`, этот параметр игнорируется. - `eq`: Если true (по умолчанию), будет сгенерирован метод `__eq__()`. Этот метод сравнивает класс так, как если бы он был кортежем его полей, по порядку. Оба сравниваемых экземпляра должны быть одного типа. Если класс уже определяет `__eq__()`, этот параметр игнорируется. - `order`: Если true (по умолчанию `False`), будут сгенерированы методы `__lt__()`, `__le__()`, `__gt__()` и `__ge__()`. Они сравнивают класс так, как если бы он был кортежем его полей, по порядку. Оба сравниваемых экземпляра должны быть одного типа. Если `order` равно true, а `eq` – false, возбуждается [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError). Если класс уже определяет любой из `__lt__()`, `__le__()`, `__gt__()` или `__ge__()`, то вызывается [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). - `unsafe_hash`: Если `False` (по умолчанию), метод `__hash__()` генерируется в соответствии с тем, как установлены `eq` и `frozen`. `__hash__()` используется встроенной [`hash()`](https://python-all.ru/3.10/library/functions.html#hash) и при добавлении объектов в хешируемые коллекции, такие как словари и множества. Наличие `__hash__()` подразумевает, что экземпляры класса неизменяемы. Изменяемость – сложное свойство, зависящее от намерений программиста, наличия и поведения `__eq__()`, а также значений флагов `eq` и `frozen` в декораторе [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass). По умолчанию [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) не будет неявно добавлять метод `__hash__()`, если это не безопасно. Он также не будет добавлять или изменять существующий явно определённый метод `__hash__()`. Установка атрибута класса `__hash__ = None` имеет для Python определённое значение, описанное в документации `__hash__()`. Если `__hash__()` не определён явно или установлен в `None`, то [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) *может* добавить неявный метод `__hash__()`. Хотя это не рекомендуется, можно принудительно заставить [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) создать метод `__hash__()` с помощью `unsafe_hash=True`. Это может потребоваться, если класс логически неизменяем, но всё же может быть изменён. Это специализированный случай использования, и к нему следует отнестись с осторожностью. Вот правила, определяющие неявное создание метода `__hash__()`. Обратите внимание, что нельзя одновременно иметь явный метод `__hash__()` в классе данных и устанавливать `unsafe_hash=True`; это приведёт к [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). Если `eq` и `frozen` оба равны true, по умолчанию [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) сгенерирует метод `__hash__()`. Если `eq` равно true, а `frozen` – false, `__hash__()` будет установлено в `None`, что делает объект нехешируемым (каковым он и является, поскольку изменяем). Если `eq` равно false, `__hash__()` останется без изменений, то есть будет использован метод `__hash__()` родительского класса (если родительский класс – [`object`](https://python-all.ru/3.10/library/functions.html#object), это означает возврат к хешированию на основе id). - `frozen`: Если true (по умолчанию `False`), присваивание полям будет вызывать исключение. Это эмулирует неизменяемые (замороженные) экземпляры. Если `__setattr__()` или `__delattr__()` определён в классе, то возбуждается [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). См. обсуждение ниже. - `match_args`: Если true (по умолчанию `True`), кортеж `__match_args__` будет создан из списка параметров сгенерированного метода `__init__()` (даже если `__init__()` не генерируется, см. выше). Если false, или если `__match_args__` уже определён в классе, то `__match_args__` не будет сгенерирован. > Новое в версии 3.10. - `kw_only`: Если true (значение по умолчанию `False`), то все поля помечаются как keyword-only. Если поле помечено как keyword-only, то единственный эффект заключается в том, что параметр `__init__()`, сгенерированный из такого поля, должен указываться с ключевым словом при вызове `__init__()`. На остальные аспекты dataclasses это не влияет. Подробнее см. глоссарий, запись [параметр](https://python-all.ru/3.10/glossary.html#term-parameter). Также см. раздел [`KW_ONLY`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.KW_ONLY). > Новое в версии 3.10. - `slots`: Если true (по умолчанию `False`), будет сгенерирован атрибут `__slots__` и возвращён новый класс вместо исходного. Если `__slots__` уже определён в классе, то возбуждается [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). > Новое в версии 3.10. `field` могут опционально задавать значение по умолчанию, используя обычный синтаксис Python: ```python @dataclass class C: a: int # 'a' не имеет значения по умолчанию b: int = 0 # задайте значение по умолчанию для 'b' ``` В этом примере и `a`, и `b` будут включены в добавленный метод `__init__()`, который будет определён как: ```python def __init__(self, a: int, b: int = 0): ``` [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError) будет возбуждено, если поле без значения по умолчанию следует за полем со значением по умолчанию. Это верно как для одного класса, так и в случае наследования классов. #### `dataclasses.field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)` Для простых и распространённых случаев никакой дополнительной функциональности не требуется. Однако у dataclass есть некоторые возможности, для которых нужна дополнительная информация о полях. Чтобы восполнить эту потребность, можно заменить значение поля по умолчанию на вызов предоставленной функции [`field()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.field). Например: ```python @dataclass class C: mylist: list[int] = field(default_factory=list) c = C() c.mylist += [1, 2, 3] ``` Как показано выше, значение [`MISSING`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.MISSING) – это объект-страж, используемый для определения того, какие параметры были заданы пользователем. Этот страж используется, потому что `None` является допустимым значением для некоторых параметров и имеет собственный смысл. Код не должен напрямую использовать значение [`MISSING`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.MISSING). Параметры [`field()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.field): - `default`: Если указано, это будет значением по умолчанию для данного поля. Это необходимо, потому что сам вызов [`field()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.field) заменяет обычную позицию значения по умолчанию. - `default_factory`: Если указано, это должен быть вызываемый объект без аргументов, который будет вызван, когда потребуется значение по умолчанию для этого поля. Помимо прочего, это можно использовать для указания полей с изменяемыми значениями по умолчанию, как обсуждается ниже. Указывать одновременно `default` и `default_factory` – ошибка. - `init`: Если true (по умолчанию), это поле включается в качестве параметра в сгенерированный метод `__init__()`. - `repr`: Если true (по умолчанию), это поле включается в строку, возвращаемую сгенерированным методом `__repr__()`. - `hash`: Это может быть bool или `None`. Если true, это поле включается в сгенерированный метод `__hash__()`. Если `None` (по умолчанию), используется значение `compare`: обычно это ожидаемое поведение. Поле должно учитываться в хеше, если оно используется для сравнений. Установка этого значения в любое значение, отличное от `None`, не рекомендуется. Одна из возможных причин установить `hash=False`, но `compare=True` – если вычисление хэш-значения для поля дорого, это поле нужно для проверки равенства, а есть другие поля, которые вносят вклад в хэш типа. Даже если поле исключено из хэша, оно всё равно будет использоваться для сравнений. - `compare`: Если true (по умолчанию), это поле включается в сгенерированные методы равенства и сравнения (`__eq__()`, `__gt__()` и др.). - `metadata`: Это может быть отображение или None. None обрабатывается как пустой словарь. Это значение оборачивается в [`MappingProxyType()`](https://python-all.ru/3.10/library/types.html#types.MappingProxyType) для обеспечения только для чтения и предоставляется в объекте [`Field`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.Field). Оно вообще не используется Data Classes и предоставляется как механизм расширения сторонними библиотеками. Несколько сторонних библиотек могут иметь свои собственные ключи для использования в качестве пространства имён в метаданных. - `kw_only`: Если true, это поле будет помечено как keyword-only. Это используется при вычислении параметров сгенерированного метода `__init__()`. > Новое в версии 3.10. Если значение поля по умолчанию задаётся вызовом [`field()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.field), то атрибут класса для этого поля будет заменён указанным значением `default`. Если `default` не указан, атрибут класса будет удалён. Предполагается, что после выполнения декоратора [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) атрибуты класса будут содержать значения по умолчанию для полей, как если бы было указано само значение по умолчанию. Например, после: ```python @dataclass class C: x: int y: int = field(repr=False) z: int = field(repr=False, default=10) t: int = 20 ``` Атрибут класса `C.z` будет равен `10`, атрибут класса `C.t` будет равен `20`, а атрибуты класса `C.x` и `C.y` не будут установлены. #### `class dataclasses.Field` Объекты [`Field`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.Field) описывают каждое определённое поле. Эти объекты создаются внутренне и возвращаются методом уровня модуля [`fields()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.fields) (см. ниже). Пользователи никогда не должны создавать экземпляр [`Field`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.Field) напрямую. Его документированные атрибуты: > - `name`: Имя поля. > - `type`: Тип поля. > - `default`, `default_factory`, `init`, `repr`, `hash`, `compare`, `metadata` и `kw_only` имеют те же значения и смысл, что и в функции [`field()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.field). Могут существовать и другие атрибуты, но они приватные, и на них не следует полагаться или проверять их. #### `dataclasses.fields(class_or_instance)` Возвращает кортеж объектов [`Field`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.Field), определяющих поля этого датакласса. Принимает либо датакласс, либо экземпляр датакласса. Вызывает [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError), если передан не датакласс и не его экземпляр. Не возвращает псевдополя, которые являются `ClassVar` или `InitVar`. #### `dataclasses.asdict(obj, *, dict_factory=dict)` Преобразует dataclass `obj` в словарь (с помощью фабричной функции `dict_factory`). Каждый dataclass преобразуется в словарь своих полей в виде пар `name: value`. Рекурсивно обрабатываются dataclass'ы, словари, списки и кортежи. Другие объекты копируются с помощью [`copy.deepcopy()`](https://python-all.ru/3.10/library/copy.html#copy.deepcopy). Пример использования [`asdict()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.asdict) на вложенных датаклассах: ```python @dataclass class Point: x: int y: int @dataclass class C: mylist: list[Point] p = Point(10, 20) assert asdict(p) == {'x': 10, 'y': 20} c = C([Point(0, 0), Point(10, 4)]) assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]} ``` Для создания поверхностной копии можно использовать следующий обходной путь: ```python dict((field.name, getattr(obj, field.name)) for field in fields(obj)) ``` [`asdict()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.asdict) возбуждает [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError), если `obj` не является экземпляром dataclass. #### `dataclasses.astuple(obj, *, tuple_factory=tuple)` Преобразует dataclass `obj` в кортеж (с помощью фабричной функции `tuple_factory`). Каждый dataclass преобразуется в кортеж значений своих полей. Рекурсивно обрабатываются dataclass'ы, словари, списки и кортежи. Другие объекты копируются с помощью [`copy.deepcopy()`](https://python-all.ru/3.10/library/copy.html#copy.deepcopy). Продолжая предыдущий пример: ```python assert astuple(p) == (10, 20) assert astuple(c) == ([(0, 0), (10, 4)],) ``` Для создания поверхностной копии можно использовать следующий обходной путь: ```python tuple(getattr(obj, field.name) for field in dataclasses.fields(obj)) ``` [`astuple()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.astuple) возбуждает [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError), если `obj` не является экземпляром dataclass. #### `dataclasses.make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False)` Создаёт новый dataclass с именем `cls_name`, полями, определёнными в `fields`, базовыми классами, указанными в `bases`, и инициализированным пространством имён из `namespace`. `fields` – это итерируемый объект, элементы которого могут быть `name`, `(name, type)` или `(name, type, Field)`. Если указан только `name`, то `typing.Any` используется для `type`. Значения `init`, `repr`, `eq`, `order`, `unsafe_hash`, `frozen`, `match_args`, `kw_only` и `slots` имеют тот же смысл, что и в [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass). Эта функция не является строго обязательной, поскольку любой механизм Python для создания нового класса с помощью `__annotations__` может затем применить функцию [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) для преобразования этого класса в датакласс. Эта функция предоставляется для удобства. Например: ```python C = make_dataclass('C', [('x', int), 'y', ('z', int, field(default=5))], namespace={'add_one': lambda self: self.x + 1}) ``` Эквивалентно: ```python @dataclass class C: x: int y: 'typing.Any' z: int = 5 def add_one(self): return self.x + 1 ``` #### `dataclasses.replace(obj, /, **changes)` Создаёт новый объект того же типа, что и `obj`, заменяя поля значениями из `changes`. Если `obj` не является Data Class, возбуждает [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). Если значения в `changes` не указывают поля, возбуждает [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError). Новый возвращаемый объект создаётся вызовом метода `__init__()` датакласса. Это гарантирует, что `__post_init__()`, если он присутствует, также будет вызван. Переменные, предназначенные только для инициализации, без значений по умолчанию (если таковые имеются) должны быть указаны в вызове [`replace()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.replace), чтобы их можно было передать в `__init__()` и `__post_init__()`. Ошибкой считается, если `changes` содержит какие-либо поля, определённые как имеющие `init=False`. В этом случае будет возбуждено [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError). Следует заранее знать, как работают поля `init=False` при вызове [`replace()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.replace). Они не копируются из исходного объекта, а инициализируются в `__post_init__()`, если вообще инициализируются. Ожидается, что поля `init=False` будут использоваться редко и осмотрительно. Если они используются, возможно, разумно иметь альтернативные конструкторы класса или, возможно, пользовательский метод `replace()` (или с похожим именем), который обрабатывает копирование экземпляра. #### `dataclasses.is_dataclass(obj)` Возвращает `True`, если его параметр является dataclass или экземпляром dataclass, иначе возвращает `False`. Если нужно узнать, является ли класс экземпляром dataclass (а не самим dataclass), добавьте дополнительную проверку на `not isinstance(obj, type)`: ```python def is_dataclass_instance(obj): return is_dataclass(obj) and not isinstance(obj, type) ``` #### `dataclasses.MISSING` Сторожевое значение, обозначающее отсутствие значения по умолчанию или default\_factory. #### `dataclasses.KW_ONLY` Сторожевое значение, используемое в качестве аннотации типа. Все поля после псевдополя с типом [`KW_ONLY`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.KW_ONLY) помечаются как keyword-only поля. Обратите внимание, что псевдополе типа [`KW_ONLY`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.KW_ONLY) в остальном полностью игнорируется, включая имя такого поля. По соглашению имя `_` используется для поля [`KW_ONLY`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.KW_ONLY). Keyword-only поля означают параметры `__init__()`, которые должны быть указаны как ключевые слова при создании класса. В этом примере поля `y` и `z` будут помечены как keyword-only поля: ```python @dataclass class Point: x: float _: KW_ONLY y: float z: float p = Point(0, y=1.5, z=2.0) ``` В одном dataclass указывать более одного поля с типом [`KW_ONLY`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.KW_ONLY) – ошибка. Новое в версии 3.10. #### `exception dataclasses.FrozenInstanceError` Возбуждается, когда неявно определённые `__setattr__()` или `__delattr__()` вызываются для dataclass, определённого с `frozen=True`. Является подклассом [`AttributeError`](https://python-all.ru/3.10/library/exceptions.html#AttributeError). ## Обработка после инициализации Сгенерированный код `__init__()` вызовет метод с именем `__post_init__()`, если `__post_init__()` определён в классе. Обычно он вызывается как `self.__post_init__()`. Однако, если определены какие-либо поля `InitVar`, они также будут переданы в `__post_init__()` в порядке их определения в классе. Если метод `__init__()` не сгенерирован, то `__post_init__()` не будет вызываться автоматически. Среди прочего, это позволяет инициализировать значения полей, которые зависят от одного или нескольких других полей. Например: ```python @dataclass class C: a: float b: float c: float = field(init=False) def __post_init__(self): self.c = self.a + self.b ``` Метод `__init__()`, сгенерированный [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass), не вызывает методы `__init__()` базового класса. Если базовый класс имеет метод `__init__()`, который необходимо вызвать, обычно этот метод вызывается в методе `__post_init__()`: ```python @dataclass class Rectangle: height: float width: float @dataclass class Square(Rectangle): side: float def __post_init__(self): super().__init__(self.side, self.side) ``` Однако обратите внимание, что в целом вызывать сгенерированные dataclass методы `__init__()` не требуется, поскольку производный dataclass сам позаботится об инициализации всех полей любого базового класса, который сам является dataclass. Смотрите раздел ниже о переменных, используемых только для инициализации, чтобы узнать о способах передачи параметров в `__post_init__()`. Также обратите внимание на предупреждение о том, как [`replace()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.replace) обрабатывает поля `init=False`. ## Переменные класса Одно из немногих мест, где [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) фактически проверяет тип поля, – это определение, является ли поле переменной класса, как определено в [**PEP 526**](https://python-all.ru/3.10/library/dataclasses.html). Это делается путём проверки, является ли тип поля `typing.ClassVar`. Если поле является `ClassVar`, оно исключается из рассмотрения как поле и игнорируется механизмами dataclass. Такие псевдополя `ClassVar` не возвращаются функцией модульного уровня [`fields()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.fields). ## Переменные только для инициализации Ещё одно место, где [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) проверяет аннотацию типа, – определение, является ли поле переменной, используемой только для инициализации. Для этого проверяется, имеет ли поле тип `dataclasses.InitVar`. Если поле является `InitVar`, оно считается псевдополем, называемым полем, используемым только для инициализации. Поскольку это не настоящее поле, оно не возвращается функцией модульного уровня [`fields()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.fields). Поля, используемые только для инициализации, добавляются как параметры в сгенерированный метод `__init__()` и передаются в необязательный метод `__post_init__()`. В остальном они не используются модулем dataclasses. Например, предположим, что поле будет инициализироваться из базы данных, если значение не указано при создании класса: ```python @dataclass class C: i: int j: int | None = None database: InitVar[DatabaseType | None] = None def __post_init__(self, database): if self.j is None and database is not None: self.j = database.lookup('j') c = C(10, database=my_database) ``` В этом случае [`fields()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.fields) вернёт объекты [`Field`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.Field) для `i` и `j`, но не для `database`. ## Замороженные экземпляры Создать по-настоящему неизменяемые объекты Python невозможно. Однако, передав `frozen=True` декоратору [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass), можно эмулировать неизменяемость. В этом случае dataclasses добавит в класс методы `__setattr__()` и `__delattr__()`. При вызове эти методы вызовут исключение [`FrozenInstanceError`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.FrozenInstanceError). Использование `frozen=True` сопряжено с небольшим снижением производительности: `__init__()` не может использовать простое присваивание для инициализации полей и должен использовать [`object.__setattr__()`](https://python-all.ru/3.10/reference/datamodel.html#object.__setattr__). ## Наследование Когда dataclass создаётся декоратором [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass), он просматривает все базовые классы в порядке, обратном MRO (начиная с [`object`](https://python-all.ru/3.10/library/functions.html#object)), и для каждого найденного dataclass добавляет поля из этого базового класса в упорядоченное отображение полей. После добавления всех полей базовых классов он добавляет свои собственные поля в это упорядоченное отображение. Все сгенерированные методы будут использовать это объединённое вычисленное упорядоченное отображение полей. Поскольку поля располагаются в порядке вставки, производные классы переопределяют базовые. Пример: ```python @dataclass class Base: x: Any = 15.0 y: int = 0 @dataclass class C(Base): z: int = 10 x: int = 15 ``` Итоговый список полей в порядке: `x`, `y`, `z`. Итоговый тип `x` – `int`, как указано в классе `C`. Сгенерированный метод `__init__()` для `C` будет выглядеть так: ```python def __init__(self, x: int = 15, y: int = 0, z: int = 10): ``` ## Переупорядочивание keyword-only параметров в `__init__()` После того как вычислены параметры, необходимые для `__init__()`, все параметры, доступные только по ключевому слову, перемещаются так, чтобы они следовали за всеми обычными (не ключевыми) параметрами. Это требование реализации ключевых параметров в Python: они должны идти после обычных параметров. В этом примере `Base.y`, `Base.w` и `D.t` – поля, доступные только по ключевому слову, а `Base.x` и `D.z` – обычные поля. ```python @dataclass class Base: x: Any = 15.0 _: KW_ONLY y: int = 0 w: int = 1 @dataclass class D(Base): z: int = 10 t: int = field(kw_only=True, default=0) ``` Сгенерированный метод `__init__()` для `D` будет выглядеть так: ```python def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: int = 0): ``` Обратите внимание, что порядок параметров изменился по сравнению с тем, как они указаны в списке полей: параметры, полученные из обычных полей, следуют за параметрами, полученными из ключевых полей. Относительный порядок ключевых параметров сохраняется в переупорядоченном списке параметров `__init__()`. ## Функции фабрики по умолчанию > Если [`field()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.field) указывает `default_factory`, то он вызывается без аргументов, когда требуется значение по умолчанию для поля. Например, чтобы создать новый экземпляр списка, используйте: > > ```python > mylist: list = field(default_factory=list) > ``` > > Если поле исключено из `__init__()` (с помощью `init=False`) и поле также указывает `default_factory`, то функция фабрики значений по умолчанию всегда будет вызываться из сгенерированной функции `__init__()`. Это происходит потому, что нет другого способа задать полю начальное значение. ## Изменяемые значения по умолчанию > Python хранит значения переменных-членов по умолчанию в атрибутах класса. Рассмотрим этот пример без использования dataclasses: > > ```python > class C: > x = [] > def add(self, element): > self.x.append(element) > > o1 = C() > o2 = C() > o1.add(1) > o2.add(2) > assert o1.x == [1, 2] > assert o1.x is o2.x > ``` > > Обратите внимание, что два экземпляра класса `C` разделяют одну и ту же переменную класса `x`, как и ожидалось. > > При использовании dataclasses, *если* бы этот код был корректным: > > ```python > @dataclass > class D: > x: List = [] > def add(self, element): > self.x += element > ``` > > он бы сгенерировал код, похожий на: > > ```python > class D: > x = [] > def __init__(self, x=x): > self.x = x > def add(self, element): > self.x += element > > assert D().x is D().x > ``` > > Это та же проблема, что и в исходном примере с классом `C`. А именно, два экземпляра класса `D`, не указывающие значение для `x` при создании экземпляра класса, будут совместно использовать одну и ту же копию `x`. Поскольку dataclasses используют обычное создание классов Python, они также имеют такое поведение. Не существует общего способа для классов данных обнаружить это условие. Вместо этого декоратор [`dataclass()`](https://python-all.ru/3.10/library/dataclasses.html#dataclasses.dataclass) вызовет исключение [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError), если обнаружит параметр по умолчанию типа `list`, `dict` или `set`. Это частичное решение, но оно защищает от многих распространённых ошибок. > > Использование фабричных функций по умолчанию – это способ создавать новые экземпляры изменяемых типов в качестве значений полей по умолчанию: > > ```python > @dataclass > class D: > x: list = field(default_factory=list) > > assert D().x is not D().x > ``` ## Поля с типом дескриптора Поля, которым назначены [объекты-дескрипторы](https://python-all.ru/3.10/reference/datamodel.html#descriptors) в качестве значения по умолчанию, обладают следующим особым поведением: - Значение поля, переданное в метод `__init__` класса данных, передается в метод `__set__` дескриптора, а не перезаписывает объект-дескриптор. - Аналогично, при чтении или записи поля вызывается метод `__get__` или `__set__` дескриптора, а не возвращается или перезаписывается объект-дескриптор. - Чтобы определить, содержит ли поле значение по умолчанию, `dataclasses` вызывает метод `__get__` дескриптора, используя его форму доступа через класс (т.е. `descriptor.__get__(obj=None, type=cls)`). Если в этом случае дескриптор возвращает значение, оно будет использовано как значение поля по умолчанию. Если же в этой ситуации дескриптор возбуждает исключение [`AttributeError`](https://python-all.ru/3.10/library/exceptions.html#AttributeError), значение по умолчанию для поля предоставлено не будет. ```python class IntConversionDescriptor: def __init__(self, *, default): self._default = default def __set_name__(self, owner, name): self._name = "_" + name def __get__(self, obj, type): if obj is None: return self._default return getattr(obj, self._name, self._default) def __set__(self, obj, value): setattr(obj, self._name, int(value)) @dataclass class InventoryItem: quantity_on_hand: IntConversionDescriptor = IntConversionDescriptor(default=100) i = InventoryItem() print(i.quantity_on_hand) # 100 i.quantity_on_hand = 2.5 # вызывает __set__ с 2.5 print(i.quantity_on_hand) # 2 ``` Обратите внимание: если поле аннотировано типом дескриптора, но ему не назначен объект-дескриптор в качестве значения по умолчанию, такое поле будет вести себя как обычное поле.