Сообщить об ошибке.

Функция field() модуля dataclasses в Python.

Дополнительная информация конкретного поля класса данных.

Синтаксис:

import dataclasses

dataclasses.field(*, default=MISSING, default_factory=MISSING, 
                  repr=True, hash=None, init=True, 
                  compare=True, metadata=None)

Параметры:

  • default=MISSING - значение по умолчанию,
  • default_factory=MISSING - фабричная функция,
  • repr=True - флаг для создания метода __repr__(),
  • hash=None - флаг для создания метода __hash__(),
  • init=True - флаг для создания метода __init__(),
  • compare=True - будет ли участвовать поле в сравнении,
  • metadata=None - словарь пространства имен в метаданных.

Возвращаемое значение:

  • дополнительную информацию для поля класса данных.

Описание:

Функция field() модуля dataclasses вызывается для некоторой дополнительной информации конкретного поля класса данных. Чтобы удовлетворить эту потребность, можно заменить значение поля по умолчанию, вызовом функции dataclasses.field().

Например:

@dataclass
class C:
    mylist: list[int] = field(default_factory=list)

c = C()
c.mylist += [1, 2, 3]

В приведенном выше синтаксисе можно заметить, что default и default_factory равны значению MISSING - это контрольный объект, используемый для определения того, предоставлены ли параметры default и default_factory. Так как None является допустимым по умолчанию значением для полей, то используется этот контрольный объект. Никакой код не должен напрямую использовать значение MISSING.

Поведение функции dataclasses.field() в зависимости от значений аргументов:

  • default: если указано, то это будет значение по умолчанию для вызываемого поля. Такое поведение необходимо, так как сам вызов dataclasses.field() заменяет нормальную позицию значения по умолчанию.

  • default_factory: если предоставлено, то это должен быть вызываемый объект с без аргументов, который будет вызываться, когда для этого поля потребуется значение по умолчанию. Такое поведение можно использовать для указания полей с изменяемыми значениями по умолчанию, как описано ниже. Ошибочно указывать и default и default_factory одновременно.

  • init: если True (по умолчанию), то это поле включается как параметр в сгенерированный метод __init__().

  • repr: если True (по умолчанию), то это поле включается в строку, возвращаемую методом __repr__().

  • compare: если true (по умолчанию), это поле включается в сгенерированные методы сравнения и сравнения (__eq __ (), __gt __ () и др.).

  • hash: значение может быть bool или None. Если True, то это поле включается в сгенерированный метод __hash__(). Если None (по умолчанию), то используйте значение аргумента compare: обычно это ожидаемое поведение. Поле следует учитывать в хэше, если оно используется для сравнения. Не рекомендуется устанавливать для этого значения какое то другое, кроме None.

    Одна из возможных причин для установки hash=False и compare=True может заключаться в том, что для поля сложно вычислять хеш-значение, это поле необходимо для проверки равенства, и есть другие поля, которые влияют на хеш-значение типа. Даже если поле исключено из хэша, оно все равно будет использоваться для сравнения.

  • metadata: значение может быть словарем или None. Пустой словарь недействителен. Это значение доступно только для чтения, и отображается в объекте Field. Оно вообще не используется классами данных и предоставляется как сторонний механизм расширения. Некоторые разработчики используют его в качестве пространства имен в метаданных.

Если значение поля по умолчанию задается вызовом dataclasses.field(), то тогда атрибут класса для этого поля будет заменен указанным значением по умолчанию. Если значение по умолчанию не указано, то атрибут класса будет удален. Цель состоит в том, что после запуска декоратора @dataclass() все атрибуты класса будут содержать значения по умолчанию для полей, как если бы само значение по умолчанию было указано. Например, после:

@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 не будут установлены.

Примеры вызова функции field() для полей класса данных.

Использование аргумента default.

Этот параметр задает значение по умолчанию для атрибута, если при создании объекта значение не задано. Подобно параметрам в функции, поля со значением по умолчанию должны следовать за любыми полями без значения по умолчанию.

from dataclasses import dataclass, field 
  
@dataclass
class Article: 
    title: str
    language: str = field(default ='Python3') 
  
>>> article = Article("User Types") 
>>> article
# Article(title='User Types', language='Python3')

Использование аргумента default_factory.

Аргумент default_factory должен быть вызываемый объект без аргументов и будет вызываться, когда для этого поля потребуется значение по умолчанию.

Возвращаемое значение будет установлено как значение по умолчанию для атрибута при создании объекта. Ошибочно указывать и default и default_factory одновременно. Необходимо предоставить либо вызываемый объект фабричной функции default_factory, либо предоставить значение default для атрибута.

from dataclasses import dataclass, field 
from random import choice 
  
def get_language(): 
    languages = ['Python3', 'Java', "C"] 
    return choice(languages) 
  
@dataclass
class Article: 
    title: str
    language: str = field(default_factory=get_language) 
  
>>> article = Article("User Types") 
>>> article
# Article(title='User Types', language='Java')

Использование аргумента compare, repr и init.

Аргументы init, repr и hash аналогичны аргументам декоратора @dataclass. Параметр compare может быть связан с порядком, как и в @dataclass. Разница заключается в их способности быть применимыми только к определенному атрибуту, а не ко всем атрибутам в классе данных под декоратором.

Если аргумент compare=True (по умолчанию), то это поле включается в сгенерированные методы сравнения и сравнения.

from dataclasses import dataclass, field 
  
@dataclass
class Article: 
    title: str = field(compare=False) 
    site: str = field(repr=False) 
    language: str = field(default='Python3') 
    likes: int = field(init=False, default=0) 
  
# Обратите внимание на разные `title`
>>> article1 = Article('User Types', 'docs-python.ru') 
>>> article2 = Article('Python import', 'docs-python.ru') 
>>> article1
# Article(title='User Types', language='Python3', likes=0)
>>> article1.site
# 'docs-python.ru'
>>> article1 == article2
# True