Справочник по полям модели

В этом документе содержатся все справочные материалы API для Field, включая параметры полей и типы полей, доступные в Django.

См. также

Если встроенные поля не подходят, попробуйте django-localflavor (документация), содержащий различные фрагменты кода, полезные для отдельных стран и культур.

Кроме того, вы можете легко написать собственные пользовательские поля модели.

Примечание

Поля определены в django.db.models.fields, но для удобства импортируются в django.db.models. Обычно используют from django.db import models и обращаются к полям как к models.<Foo>Field.

Параметры полей

Следующие аргументы доступны для всех типов полей. Все они необязательны.

`null`

Field.null

Если True, Django будет сохранять пустые значения в базе данных как NULL. По умолчанию — False.

Избегайте использования null для строковых полей, таких как CharField и TextField. Согласно принятому в Django соглашению, для обозначения состояния «нет данных» в строковых полях используется пустая строка, а не NULL. Если для строкового поля задано null=False, для состояния «нет данных» по-прежнему можно сохранять пустые строки. Если для строкового поля задано null=True, это означает, что у состояния «нет данных» есть два возможных значения: NULL и пустая строка. В большинстве случаев наличие двух возможных значений для состояния «нет данных» избыточно. Исключение — когда для CharField заданы и unique=True, и blank=True. В этом случае null=True необходимо, чтобы избежать нарушения ограничений уникальности при сохранении нескольких объектов с пустыми значениями.

Как для строковых, так и для нестроковых полей, если вы хотите разрешить пустые значения в формах, также необходимо задать blank=True, поскольку параметр null влияет только на хранение данных в базе данных (см. blank).

Примечание

При использовании серверной части базы данных Oracle значение NULL будет сохраняться как обозначение пустой строки независимо от этого атрибута.

`blank`

Field.blank

Если задано True, поле может быть пустым. По умолчанию — False.

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

Указание отсутствующих значений

blank=True можно использовать с полями, для которых задано null=False, но для этого необходимо реализовать clean() в модели, чтобы программно указывать отсутствующие значения.

`choices`

Field.choices [исходный код]

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

Если передан словарь, ключевой элемент — это фактическое значение, которое будет присвоено модели, а второй элемент — понятное пользователю название. Например:

YEAR_IN_SCHOOL_CHOICES = {
    "FR": "Freshman",
    "SO": "Sophomore",
    "JR": "Junior",
    "SR": "Senior",
    "GR": "Graduate",
}

Также можно передать последовательность, состоящую из итерируемых объектов ровно с двумя элементами (например, [(A1, B1), (A2, B2), …]). Первый элемент каждого кортежа — это фактическое значение, которое будет присвоено модели, а второй — понятное пользователю название. Например:

YEAR_IN_SCHOOL_CHOICES = [
    ("FR", "Freshman"),
    ("SO", "Sophomore"),
    ("JR", "Junior"),
    ("SR", "Senior"),
    ("GR", "Graduate"),
]

choices также можно задать как вызываемый объект, который не принимает аргументов и возвращает любой из описанных выше форматов. Например:

def get_currencies():
    return {i: i for i in settings.CURRENCIES}


class Expense(models.Model):
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    currency = models.CharField(max_length=3, choices=get_currencies)

Передача вызываемого объекта для choices может быть особенно удобна, например, когда варианты выбора:

являются результатом операций с интенсивным вводом-выводом (которые потенциально можно кэшировать), например запроса таблицы в той же или внешней базе данных либо получения вариантов выбора из статического файла;
представляют собой список, который в основном остаётся неизменным, но может время от времени меняться или различаться в разных проектах. Примеры этой категории — сторонние приложения, предоставляющие общепринятый набор значений, таких как валюты, страны, языки, часовые пояса и т. д.

Как правило, лучше всего определять варианты выбора внутри класса модели и задавать константу с подходящим именем для каждого значения:

from django.db import models


class Student(models.Model):
    FRESHMAN = "FR"
    SOPHOMORE = "SO"
    JUNIOR = "JR"
    SENIOR = "SR"
    GRADUATE = "GR"
    YEAR_IN_SCHOOL_CHOICES = {
        FRESHMAN: "Freshman",
        SOPHOMORE: "Sophomore",
        JUNIOR: "Junior",
        SENIOR: "Senior",
        GRADUATE: "Graduate",
    }
    year_in_school = models.CharField(
        max_length=2,
        choices=YEAR_IN_SCHOOL_CHOICES,
        default=FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {self.JUNIOR, self.SENIOR}

Хотя можно определить список вариантов выбора вне класса модели и затем ссылаться на него, определение вариантов выбора и названий каждого из них внутри класса модели позволяет хранить всю эту информацию в классе, который её использует, и упрощает обращение к вариантам выбора (например, Student.SOPHOMORE будет работать в любом месте, где импортирована модель Student).

Также можно объединить доступные варианты выбора в именованные группы для удобства организации:

MEDIA_CHOICES = {
    "Audio": {
        "vinyl": "Vinyl",
        "cd": "CD",
    },
    "Video": {
        "vhs": "VHS Tape",
        "dvd": "DVD",
    },
    "unknown": "Unknown",
}

Ключ словаря — это название группы, а значение — варианты выбора в этой группе, состоящие из значения поля и понятного пользователю названия варианта. Сгруппированные варианты можно объединять с несгруппированными в одном словаре (например, вариант "unknown" в этом примере).

Можно также использовать последовательность, например список из 2-кортежей:

MEDIA_CHOICES = [
    (
        "Audio",
        (
            ("vinyl", "Vinyl"),
            ("cd", "CD"),
        ),
    ),
    (
        "Video",
        (
            ("vhs", "VHS Tape"),
            ("dvd", "DVD"),
        ),
    ),
    ("unknown", "Unknown"),
]

Обратите внимание, что варианты выбора могут быть любым объектом-последовательностью — не обязательно списком или кортежем. Это позволяет динамически формировать варианты выбора. Однако если вам приходится прибегать к хитростям, чтобы сделать choices динамическим, вероятно, лучше использовать подходящую таблицу базы данных с ForeignKey. choices предназначен для статических данных, которые меняются редко или не меняются вовсе.

Примечание

При каждом изменении порядка choices создаётся новая миграция.

Для каждого поля модели, у которого задано choices, Django преобразует варианты выбора в список 2-кортежей и добавляет метод для получения понятного пользователю названия текущего значения поля. См. get_FOO_display() в документации по API базы данных.

Если для поля не задано blank=False и при этом задано default, рядом со списком выбора будет отображаться метка со значением "---------". Чтобы изменить это поведение, добавьте в choices кортеж, содержащий None; например, (None, 'Your String For Display'). В качестве альтернативы можно использовать пустую строку вместо None, если это уместно, например для CharField.

Типы перечислений

Кроме того, Django предоставляет типы перечислений, которые можно наследовать для краткого определения вариантов выбора:

from django.utils.translation import gettext_lazy as _


class Student(models.Model):
    class YearInSchool(models.TextChoices):
        FRESHMAN = "FR", _("Freshman")
        SOPHOMORE = "SO", _("Sophomore")
        JUNIOR = "JR", _("Junior")
        SENIOR = "SR", _("Senior")
        GRADUATE = "GR", _("Graduate")

    year_in_school = models.CharField(
        max_length=2,
        choices=YearInSchool,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

Они похожи на enum из стандартной библиотеки Python, но с некоторыми изменениями:

Значения элементов перечисления — это кортеж аргументов, используемых при создании конкретного типа данных. Django поддерживает добавление в конец этого кортежа дополнительной строковой величины, которая будет использоваться как понятное пользователю название, или label. label может быть ленивой переводимой строкой. Поэтому в большинстве случаев значение элемента представляет собой (value, label) 2-кортеж. Ниже приведён пример наследования от choices с использованием более сложного типа данных. Если кортеж не указан или последний элемент не является (ленивой) строкой, label генерируется автоматически на основе имени элемента.
К значениям добавляется свойство .label, возвращающее понятное пользователю название.
К классам перечислений добавляется ряд пользовательских свойств — .choices, .labels, .values и .names, — которые упрощают доступ к спискам отдельных частей перечисления.

Предупреждение

Эти имена свойств нельзя использовать в качестве имён элементов, так как это приведёт к конфликту.
Применяется enum.unique(), чтобы гарантировать, что значения не будут определены несколько раз. Для вариантов выбора поля такое поведение вряд ли будет ожидаемым.

Обратите внимание: использование YearInSchool.SENIOR, YearInSchool['SENIOR'] или YearInSchool('SR') для доступа к элементам перечисления или поиска по ним работает как ожидается. Это также относится к свойствам .name и .value элементов.

Если переводить понятные пользователю названия не требуется, их можно сформировать на основе имени элемента (заменив подчёркивания пробелами и используя регистр заголовка):

>>> class Vehicle(models.TextChoices):
...     CAR = "C"
...     TRUCK = "T"
...     JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

Поскольку необходимость в целочисленных значениях элементов перечисления встречается очень часто, Django предоставляет класс IntegerChoices. Например:

class Card(models.Model):
    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit)

Также можно использовать функциональный API Enum, учитывая, что метки генерируются автоматически, как описано выше:

>>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
>>> MedalType.choices
[('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')]
>>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD")
>>> Place.choices
[(1, 'First'), (2, 'Second'), (3, 'Third')]

Если вам нужна поддержка конкретного типа данных, отличного от int или str, можно создать подкласс Choices и необходимого конкретного типа данных, например date для использования с DateField:

class MoonLandings(datetime.date, models.Choices):
    APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)"
    APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)"
    APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)"
    APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)"
    APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)"
    APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)"

Следует учитывать ещё несколько особенностей:

Типы перечислений не поддерживают именованные группы.
Поскольку перечисление с конкретным типом данных требует, чтобы все значения соответствовали этому типу, переопределить пустую метку нельзя, создав элемент со значением None. Вместо этого задайте атрибут __empty__ класса:
```
class Answer(models.IntegerChoices):
    NO = 0, _("No")
    YES = 1, _("Yes")

    __empty__ = _("(Unknown)")
```

`db_column`

Field.db_column

Имя столбца базы данных, используемого для этого поля. Если оно не задано, Django использует имя поля.

Если имя столбца базы данных является зарезервированным словом SQL или содержит символы, недопустимые в именах переменных Python, в частности дефис, это не проблема. Django автоматически заключает имена столбцов и таблиц в кавычки.

`db_comment`

Field.db_comment

Комментарий к столбцу базы данных, используемому для этого поля. Он полезен для документирования полей для тех, у кого есть непосредственный доступ к базе данных и кто может не просматривать ваш код Django. Например:

pub_date = models.DateTimeField(
    db_comment="Date and time when the article was published",
)

`db_default`

Field.db_default

Значение по умолчанию для этого поля, вычисляемое базой данных. Это может быть литеральное значение или функция базы данных, например Now:

created = models.DateTimeField(db_default=Now())

Можно использовать более сложные выражения, если они составлены из литеральных значений и функций базы данных:

month_due = models.DateField(
    db_default=TruncMonth(
        Now() + timedelta(days=90),
        output_field=models.DateField(),
    )
)

Значения по умолчанию в базе данных не могут ссылаться на другие поля или модели. Например, следующий код недопустим:

end = models.IntegerField(db_default=F("start") + 50)

Если заданы и db_default, и Field.default, при создании экземпляров в коде Python приоритет будет у default. db_default всё равно будет задано на уровне базы данных и будет использоваться при вставке строк в обход ORM или при добавлении нового поля в миграции.

Если для поля задано db_default, но не задано default и полю не присвоено значение, для этого поля в несохранённых экземплярах модели будет возвращаться объект DatabaseDefault. Фактическое значение поля определяется базой данных при сохранении экземпляра модели.

`db_index`

Field.db_index

Если задано True, для этого поля будет создан индекс базы данных.

Вместо этого используйте параметр indexes.

По возможности используйте параметр Meta.indexes. Почти во всех случаях indexes предоставляет больше возможностей, чем db_index. В будущем db_index может быть объявлен устаревшим.

`db_tablespace`

Field.db_tablespace [исходный код]

Имя табличного пространства базы данных, используемого для индекса этого поля, если поле индексируется. По умолчанию используется параметр DEFAULT_INDEX_TABLESPACE проекта, если он задан, или db_tablespace модели, если оно задано. Если серверная часть не поддерживает табличные пространства для индексов, этот параметр игнорируется.

`default`

Field.default

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

Значение по умолчанию не может быть изменяемым объектом (экземпляром модели, list, set и т. д.), так как в качестве значения по умолчанию для всех новых экземпляров модели будет использоваться ссылка на один и тот же экземпляр этого объекта. Вместо этого оберните нужное значение по умолчанию в вызываемый объект. Например, если для JSONField нужно указать значение dict по умолчанию, используйте функцию:

def contact_default():
    return {"email": "to1@example.com"}


contact_info = JSONField("ContactInfo", default=contact_default)

lambda нельзя использовать для таких параметров полей, как default, поскольку их невозможно сериализовать в миграциях. Другие ограничения описаны в соответствующей документации.

Для полей, таких как ForeignKey, которые указывают на экземпляры модели, значениями по умолчанию должны быть значения поля, на которое они ссылаются (pk, если не задано to_field), а не экземпляры модели.

Значение по умолчанию используется при создании новых экземпляров модели, если для поля не указано значение. Для поля первичного ключа значение по умолчанию также используется, если полю присвоено None.

Значение по умолчанию можно также задать на уровне базы данных с помощью Field.db_default.

`editable`

Field.editable

Если задано False, поле не будет отображаться в административном интерфейсе или любой другой ModelForm. Оно также будет пропускаться при проверке модели. По умолчанию — True.

`error_messages`

Field.error_messages [исходный код]

Аргумент error_messages позволяет переопределить сообщения по умолчанию, которые вызывает поле. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые нужно переопределить.

Ключи сообщений об ошибках включают null, blank, invalid, invalid_choice, unique и unique_for_date. Дополнительные ключи сообщений об ошибках для каждого поля указаны ниже в разделе Типы полей.

Эти сообщения об ошибках часто не передаются формам. См. Рекомендации по использованию error_messages модели.

`help_text`

Field.help_text

Дополнительный текст «справки», отображаемый вместе с виджетом формы. Он полезен для документирования, даже если поле не используется в форме.

Обратите внимание, что это значение не экранируется как HTML в автоматически создаваемых формах. Поэтому при желании в help_text можно включить HTML. Например:

help_text = "Please use the following format: <em>YYYY-MM-DD</em>."

В качестве альтернативы можно использовать обычный текст и django.utils.html.escape() для экранирования специальных символов HTML. Чтобы избежать атаки межсайтового скриптинга, не забывайте экранировать справочный текст, который может поступать от недоверенных пользователей.

`primary_key`

Field.primary_key

Если задано True, это поле является первичным ключом модели.

Если в модели ни для одного поля не указано primary_key=True и составной первичный ключ не определён, Django автоматически добавит поле для хранения первичного ключа. Поэтому не нужно задавать primary_key=True ни для одного из полей, если только вы не хотите переопределить поведение первичного ключа по умолчанию. Тип автоматически создаваемых полей первичного ключа можно указать для каждого приложения в AppConfig.default_auto_field или глобально в параметре DEFAULT_AUTO_FIELD. Подробнее см. Автоматические поля первичного ключа.

primary_key=True подразумевает null=False и unique=True. Для одной модели только у одного поля может быть задано primary_key=True. Составные первичные ключи необходимо определять с помощью CompositePrimaryKey, а не устанавливать этот флаг в True для всех полей, чтобы сохранить этот инвариант.

Поле первичного ключа доступно только для чтения. Если изменить значение первичного ключа существующего объекта и сохранить его, будет создан новый объект, а старый останется без изменений.

Значение поля первичного ключа устанавливается в None при удалении объекта с помощью deleting.

Изменено в Django 5.2:

Добавлено поле CompositePrimaryKey.

`unique`

Field.unique [исходный код]

Если задано True, это поле должно быть уникальным во всей таблице.

Уникальность обеспечивается на уровне базы данных и при проверке модели. Если попытаться сохранить модель с дублирующимся значением в поле unique, метод save() модели вызовет исключение django.db.IntegrityError.

Этот параметр допустим для всех типов полей, кроме ManyToManyField и OneToOneField.

Обратите внимание: если для unique задано True, указывать db_index не нужно, так как unique подразумевает создание индекса.

`unique_for_date`

Field.unique_for_date

Укажите здесь имя DateField или DateTimeField, чтобы потребовать уникальности этого поля для значения поля даты.

Например, если у вас есть поле title, для которого задано unique_for_date="pub_date", Django не позволит создать две записи с одинаковыми значениями title и pub_date.

Обратите внимание: если указать здесь DateTimeField, будет учитываться только дата, без времени. Кроме того, если USE_TZ задано в True, проверка будет выполняться в текущем часовом поясе на момент сохранения объекта.

Это ограничение проверяется методом Model.validate_unique() при проверке модели, но не на уровне базы данных. Если какое-либо ограничение unique_for_date включает поля, не входящие в ModelForm (например, если одно из полей указано в exclude или для него задано editable=False), метод Model.validate_unique() пропустит проверку этого ограничения.

`unique_for_month`

Field.unique_for_month

Аналогично unique_for_date, но требует уникальности поля относительно месяца.

`unique_for_year`

Field.unique_for_year

Аналогично unique_for_date и unique_for_month.

`verbose_name`

Field.verbose_name

Понятное пользователю имя поля. Если подробное имя не задано, Django автоматически создаст его на основе имени атрибута поля, заменив подчёркивания пробелами. См. Подробные имена полей.

`validators`

Field.validators [исходный код]

Список валидаторов, запускаемых для этого поля. Подробнее см. в документации по валидаторам.

Типы полей

`AutoField`

class AutoField(**options) [исходный код]

IntegerField, который автоматически увеличивается в соответствии с доступными идентификаторами. Обычно вам не потребуется использовать его напрямую: поле первичного ключа автоматически добавляется в модель, если не указать иное. См. раздел Автоматические поля первичного ключа.

`BigAutoField`

class BigAutoField(**options) [исходный код]

64-разрядное целое число, похожее на AutoField, но гарантированно вмещающее числа от 1 до 9223372036854775807.

`BigIntegerField`

class BigIntegerField(**options) [исходный код]

64-разрядное целое число, похожее на IntegerField, но гарантированно вмещающее числа от -9223372036854775808 до 9223372036854775807. Виджет формы по умолчанию для этого поля — NumberInput.

`BinaryField`

class BinaryField(max_length=None, **options) [исходный код]

Поле для хранения необработанных двоичных данных. Ему можно присвоить bytes, bytearray или memoryview.

По умолчанию BinaryField устанавливает для editable значение False, и в этом случае поле нельзя включить в ModelForm.

BinaryField.max_length: Необязательный параметр. Максимальная длина поля (в байтах). Максимальная длина проверяется средствами валидации Django с помощью MaxLengthValidator.

Неправильное использование BinaryField

Возможно, вы подумаете о хранении файлов в базе данных, однако в 99% случаев это плохое решение. Это поле не является заменой правильной обработки статических файлов.

`BooleanField`

class BooleanField(**options) [исходный код]

Поле со значением «истина» или «ложь».

Виджет формы по умолчанию для этого поля — CheckboxInput или NullBooleanSelect, если задано null=True.

Значение по умолчанию для BooleanField — None, если не задано Field.default.

`CompositePrimaryKey`

Добавлено в Django 5.2.

class CompositePrimaryKey(*field_names, **options) [исходный код]

Виртуальное поле для определения составного первичного ключа.

Это поле необходимо определить как атрибут pk модели. Если оно задано, Django создаст базовую таблицу модели с составным первичным ключом.

Аргумент *field_names — это список позиционных имён полей, составляющих первичный ключ.

Подробнее см. раздел Составные первичные ключи.

`CharField`

class CharField(max_length=None, **options) [исходный код]

Строковое поле для строк от небольшого до большого размера.

Для больших объёмов текста используйте TextField.

Виджет формы по умолчанию для этого поля — TextInput.

У CharField есть следующие дополнительные аргументы:

CharField.max_length: Максимальная длина поля (в символах). Значение max_length проверяется на уровне базы данных и средствами валидации Django с помощью MaxLengthValidator. Оно обязательно для всех бэкендов баз данных, включённых в Django, кроме PostgreSQL и SQLite, которые поддерживают столбцы VARCHAR неограниченной длины.

Примечание

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

Изменено в Django 5.2:
В SQLite добавлена поддержка столбцов VARCHAR неограниченной длины.

CharField.db_collation: Необязательный параметр. Имя параметра сортировки поля в базе данных.

Примечание

Имена параметров сортировки не стандартизированы. Поэтому этот параметр не будет переносимым между разными бэкендами баз данных.

Oracle

Oracle поддерживает параметры сортировки, только если параметру инициализации базы данных MAX_STRING_SIZE присвоено значение EXTENDED.

`DateField`

class DateField(auto_now=False, auto_now_add=False, **options) [исходный код]

Дата, представленная в Python экземпляром datetime.date. Имеет несколько дополнительных необязательных аргументов:

DateField.auto_now

Автоматически устанавливает текущую дату каждый раз, когда сохраняется объект. Полезно для отметок времени «последнего изменения». Обратите внимание, что всегда используется текущая дата; это не просто значение по умолчанию, которое можно переопределить.

Поле автоматически обновляется только при вызове Model.save(). Оно не обновляется при изменении других полей другими способами, например с помощью QuerySet.update(), хотя при таком обновлении можно указать для поля собственное значение.

DateField.auto_now_add

Автоматически устанавливает текущую дату при первом создании объекта. Полезно для создания отметок времени. Обратите внимание, что всегда используется текущая дата; это не просто значение по умолчанию, которое можно переопределить. Поэтому даже если при создании объекта задать значение для этого поля, оно будет проигнорировано. Если вы хотите иметь возможность изменять это поле, вместо auto_now_add=True задайте следующее:

Для DateField: default=date.today — из datetime.date.today()
Для DateTimeField: default=timezone.now — из django.utils.timezone.now()

Виджет формы по умолчанию для этого поля — DateInput. В административном интерфейсе добавляются календарь на JavaScript и кнопка быстрого выбора «Сегодня». Также включён дополнительный ключ сообщения об ошибке invalid_date.

Параметры auto_now_add, auto_now и default взаимоисключающие. Любое сочетание этих параметров приведёт к ошибке.

Примечание

В текущей реализации установка auto_now или auto_now_add в значение True приведёт к тому, что для поля будут установлены editable=False и blank=True.

Примечание

Параметры auto_now и auto_now_add всегда используют дату в часовом поясе по умолчанию на момент создания или обновления. Если вам нужно другое поведение, можно задать собственное вызываемое значение по умолчанию или переопределить save() вместо использования auto_now или auto_now_add; либо использовать DateTimeField вместо DateField и самостоятельно определить обработку преобразования даты и времени в дату при отображении.

Предупреждение

Всегда используйте DateField с экземпляром datetime.date.

Если у вас есть экземпляр datetime.datetime, рекомендуется сначала преобразовать его в datetime.date. В противном случае DateField применит к datetime.datetime часовой пояс по умолчанию из раздела часовой пояс по умолчанию и преобразует его в экземпляр datetime.date, удалив компонент времени. Это относится как к хранению, так и к сравнению.

`DateTimeField`

class DateTimeField(auto_now=False, auto_now_add=False, **options) [исходный код]

Дата и время, представленные в Python экземпляром datetime.datetime. Принимает те же дополнительные аргументы, что и DateField.

Виджет формы по умолчанию для этого поля — единый DateTimeInput. В административном интерфейсе используются два отдельных виджета TextInput с быстрыми действиями на JavaScript.

Предупреждение

Всегда используйте DateTimeField с экземпляром datetime.datetime.

Если у вас есть экземпляр datetime.date, рекомендуется сначала преобразовать его в datetime.datetime. В противном случае DateTimeField будет использовать полночь в часовом поясе по умолчанию в качестве компонента времени. Это относится как к хранению, так и к сравнению. Чтобы сравнить часть даты у DateTimeField с экземпляром datetime.date, используйте поиск date.

`DecimalField`

class DecimalField(max_digits=None, decimal_places=None, **options) [исходный код]

Десятичное число с фиксированной точностью, представленное в Python экземпляром Decimal. Проверка введённых данных выполняется с помощью DecimalValidator.

Имеет следующие обязательные аргументы:

DecimalField.max_digits: Максимальное количество цифр, допустимое в числе. Это значение должно быть больше или равно decimal_places.

DecimalField.decimal_places: Количество десятичных знаков, сохраняемых в числе.

Например, чтобы хранить числа до 999.99 с точностью до 2 десятичных знаков, используйте:

models.DecimalField(..., max_digits=5, decimal_places=2)

А чтобы хранить числа примерно до миллиарда с точностью до 10 десятичных знаков:

models.DecimalField(..., max_digits=19, decimal_places=10)

Виджетом формы по умолчанию для этого поля является NumberInput, если localize имеет значение False, и TextInput в противном случае.

Примечание

Подробнее о различиях между классами FloatField и DecimalField см. в разделе FloatField и DecimalField. Также учитывайте ограничения SQLite для десятичных полей.

`DurationField`

class DurationField(**options) [исходный код]

Поле для хранения промежутков времени, представляемых в Python типом timedelta. В PostgreSQL используется тип данных interval, а в Oracle — INTERVAL DAY(9) TO SECOND(6). В остальных случаях используется bigint микросекунд.

Примечание

Арифметические операции с DurationField работают в большинстве случаев. Однако во всех базах данных, кроме PostgreSQL, сравнение значения DurationField с результатом арифметических операций над экземплярами DateTimeField работает не так, как ожидается.

`EmailField`

class EmailField(max_length=254, **options) [исходный код]

CharField, которое проверяет корректность адреса электронной почты с помощью EmailValidator.

`FileField`

class FileField(upload_to='', storage=None, max_length=100, **options) [исходный код]

Поле для загрузки файлов.

Примечание

Аргумент primary_key не поддерживается, и его использование приведет к ошибке.

Поддерживаются следующие необязательные аргументы:

FileField.upload_to

Этот атрибут позволяет задать каталог загрузки и имя файла; задать их можно двумя способами. В обоих случаях значение передается методу Storage.save().

Если указать строковое значение или объект Path, оно может содержать форматирование strftime(), которое будет заменено датой и временем загрузки файла (чтобы загружаемые файлы не заполняли один и тот же каталог). Например:

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to="uploads/")
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to="uploads/%Y/%m/%d/")

Если используется хранилище по умолчанию FileSystemStorage, строковое значение будет добавлено к пути MEDIA_ROOT, чтобы сформировать расположение файлов на локальной файловой системе. Если используется другое хранилище, обратитесь к его документации, чтобы узнать, как оно обрабатывает upload_to.

Значение upload_to также может быть вызываемым объектом, например функцией. Она будет вызвана для получения пути загрузки, включая имя файла. Этот вызываемый объект должен принимать два аргумента и возвращать путь в стиле Unix (с прямыми косыми чертами), который будет передан системе хранения. Это два аргумента:

Аргумент	Описание
`instance`	Экземпляр модели, в которой определено поле `FileField`. Точнее, это конкретный экземпляр, к которому прикрепляется текущий файл. В большинстве случаев этот объект еще не сохранен в базе данных, поэтому при использовании стандартного `AutoField` значение его поля первичного ключа может быть еще не задано.
`filename`	Имя, первоначально заданное файлу. Оно может учитываться или не учитываться при определении конечного пути назначения.

Аргумент

Описание

instance

Экземпляр модели, в которой определено поле FileField. Точнее, это конкретный экземпляр, к которому прикрепляется текущий файл.

В большинстве случаев этот объект еще не сохранен в базе данных, поэтому при использовании стандартного AutoField значение его поля первичного ключа может быть еще не задано.

filename

Имя, первоначально заданное файлу. Оно может учитываться или не учитываться при определении конечного пути назначения.

Например:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return "user_{0}/{1}".format(instance.user.id, filename)


class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storage: Объект хранилища или вызываемый объект, возвращающий объект хранилища. Он отвечает за хранение и получение файлов. Подробности о том, как предоставить этот объект, см. в разделе Управление файлами.

Для этого поля по умолчанию используется виджет формы ClearableFileInput.

Чтобы использовать в модели FileField или ImageField (см. ниже), выполните несколько шагов:

В файле настроек задайте MEDIA_ROOT как полный путь к каталогу, в котором Django будет хранить загруженные файлы. (Для повышения производительности эти файлы не хранятся в базе данных.) Задайте MEDIA_URL как базовый общедоступный URL этого каталога. Убедитесь, что у учетной записи пользователя веб-сервера есть разрешение на запись в этот каталог.
Добавьте в модель FileField или ImageField, задав параметр upload_to, чтобы указать подкаталог MEDIA_ROOT для загружаемых файлов.
В базе данных будет храниться только путь к файлу (относительно MEDIA_ROOT). Скорее всего, вам пригодится предоставляемый Django атрибут url. Например, если ваше поле ImageField называется mug_shot, в шаблоне можно получить абсолютный путь к изображению с помощью {{ object.mug_shot.url }}.

Предположим, что для MEDIA_ROOT задано значение '/home/media', а для upload_to — 'photos/%Y/%m/%d'. Часть '%Y/%m/%d' значения upload_to использует форматирование strftime(); '%Y' — это год из четырех цифр, '%m' — месяц из двух цифр, а '%d' — день из двух цифр. Если загрузить файл 15 января 2007 года, он будет сохранен в каталоге /home/media/photos/2007/01/15.

Чтобы получить имя загруженного файла на диске или его размер, можно использовать атрибуты name и size соответственно. Дополнительные сведения о доступных атрибутах и методах см. в справочнике по классу File и в тематическом руководстве Управление файлами.

Примечание

Файл сохраняется при сохранении модели в базе данных, поэтому фактическое имя файла на диске нельзя считать окончательным до сохранения модели.

Относительный URL загруженного файла можно получить с помощью атрибута url. Внутри он вызывает метод url() базового класса Storage.

Обратите внимание: при работе с загруженными файлами следует тщательно проверять, куда вы их загружаете и какого они типа, чтобы избежать уязвимостей. Проверяйте все загружаемые файлы, чтобы убедиться, что они действительно являются тем, чем вы их считаете. Например, если без проверки разрешить загружать файлы в каталог внутри корневого каталога веб-сервера, кто-нибудь может загрузить CGI- или PHP-скрипт и выполнить его, перейдя по URL на вашем сайте. Не допускайте этого.

Также учтите, что даже загруженный HTML-файл может представлять угрозу безопасности, эквивалентную атаке XSS или CSRF, поскольку он может выполняться браузером (но не сервером).

Экземпляры FileField создаются в базе данных как столбцы varchar с максимальной длиной 100 символов по умолчанию. Как и для других полей, максимальную длину можно изменить с помощью аргумента max_length.

`FileField` и `FieldFile`

class FieldFile [исходный код]

При обращении к FileField модели вы получаете экземпляр FieldFile, который служит прокси для доступа к базовому файлу.

API класса FieldFile повторяет API класса File, но с одним важным отличием: объект, обернутый этим классом, не обязательно является оберткой над встроенным файловым объектом Python. Вместо этого он представляет собой обертку над результатом метода Storage.open(), которым может быть объект File или реализация API File пользовательским хранилищем.

Помимо API, унаследованного от File, например read() и write(), класс FieldFile включает несколько методов для взаимодействия с базовым файлом:

Предупреждение

Два метода этого класса — save() и delete() — по умолчанию сохраняют в базе данных объект модели, связанный с FieldFile.

FieldFile.name

Имя файла, включая относительный путь от корня Storage, связанного с FileField.

FieldFile.path [исходный код]

Свойство только для чтения, позволяющее получить путь к файлу в локальной файловой системе путем вызова метода path() базового класса Storage.

FieldFile.size [исходный код]

Результат вызова базового метода Storage.size().

FieldFile.url [исходный код]

Свойство только для чтения, позволяющее получить относительный URL файла путем вызова метода url() базового класса Storage.

FieldFile.open(mode='rb') [исходный код]

Открывает или повторно открывает файл, связанный с этим экземпляром, в указанном режиме mode. В отличие от стандартного метода Python open(), этот метод не возвращает файловый дескриптор.

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

FieldFile.close() [исходный код]

Работает как стандартный метод Python file.close() и закрывает файл, связанный с этим экземпляром.

FieldFile.save(name, content, save=True) [исходный код]

Этот метод принимает имя файла и его содержимое, передает их классу хранилища поля, а затем связывает сохраненный файл с полем модели. Если вы хотите вручную связать данные файла с экземплярами FileField в модели, для сохранения этих данных файла используется метод save().

Метод принимает два обязательных аргумента: name — имя файла, и content — объект, содержащий содержимое файла. Необязательный аргумент save определяет, нужно ли сохранять экземпляр модели после изменения файла, связанного с этим полем. По умолчанию задано значение True.

Обратите внимание: аргумент content должен быть экземпляром django.core.files.File, а не встроенным файловым объектом Python. Создать объект File на основе существующего файлового объекта Python можно так:

from django.core.files import File

# Open an existing file using Python's built-in open()
f = open("/path/to/hello.world")
myfile = File(f)

Также его можно создать на основе строки Python следующим образом:

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

Дополнительные сведения см. в разделе Управление файлами.

FieldFile.delete(save=True) [исходный код]

Удаляет файл, связанный с этим экземпляром, и очищает все атрибуты поля. Примечание: этот метод закроет файл, если он открыт на момент вызова delete().

Необязательный аргумент save определяет, нужно ли сохранять экземпляр модели после удаления файла, связанного с этим полем. По умолчанию задано значение True.

Обратите внимание, что при удалении модели связанные с ней файлы не удаляются. Если нужно очистить оставшиеся без привязки файлы, это придется сделать самостоятельно (например, с помощью пользовательской команды управления, которую можно запускать вручную или периодически по расписанию, например через cron).

`FilePathField`

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options) [исходный код]

Поле CharField, варианты выбора которого ограничены именами файлов в указанном каталоге файловой системы. Имеет несколько специальных аргументов, первый из которых является обязательным:

FilePathField.path

Обязательный аргумент. Абсолютный путь в файловой системе к каталогу, из которого это поле FilePathField должно получать варианты выбора. Пример: "/home/images".

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

import os
from django.conf import settings
from django.db import models


def images_path():
    return os.path.join(settings.LOCAL_FILE_DIR, "images")


class MyModel(models.Model):
    file = models.FilePathField(path=images_path)

FilePathField.match: Необязательный аргумент. Строка с регулярным выражением, которое поле FilePathField будет использовать для фильтрации имен файлов. Обратите внимание: регулярное выражение применяется к базовому имени файла, а не к полному пути. Пример: "foo.*\.txt$" — ему будет соответствовать файл с именем foo23.txt, но не bar.txt и не foo23.png.

FilePathField.recursive: Необязательный аргумент. Значение True или False. По умолчанию — False. Определяет, следует ли включать все подкаталоги path.

FilePathField.allow_files: Необязательный аргумент. Значение True или False. По умолчанию — True. Определяет, следует ли включать файлы из указанного расположения. Значение этого аргумента или аргумента allow_folders должно быть равно True.

FilePathField.allow_folders: Необязательный аргумент. Значение True или False. По умолчанию — False. Определяет, следует ли включать папки из указанного расположения. Значение этого аргумента или аргумента allow_files должно быть равно True.

Следует учесть, что match применяется к базовому имени файла, а не к полному пути. Поэтому этот пример:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…соответствует /home/images/foo.png, но не /home/images/foo/bar.png, поскольку match применяется к базовым именам файлов (foo.png и bar.png).

Экземпляры FilePathField создаются в базе данных как столбцы varchar с максимальной длиной 100 символов по умолчанию. Как и для других полей, максимальную длину можно изменить с помощью аргумента max_length.

`FloatField`

class FloatField(**options) [исходный код]

Число с плавающей точкой, представленное в Python экземпляром float.

В качестве виджета формы по умолчанию для этого поля используется NumberInput, если localize равно False, и TextInput в противном случае.

FloatField и DecimalField

Класс FloatField иногда путают с классом DecimalField. Хотя оба класса представляют вещественные числа, делают они это по-разному. Внутри FloatField использует тип Python float, а DecimalField — тип Python Decimal. Сведения о различиях между ними см. в документации Python по модулю decimal.

`GeneratedField`

class GeneratedField(*, expression, output_field, db_persist, **kwargs) [исходный код]

Поле, значение которого всегда вычисляется на основе других полей модели. Это поле обслуживается и обновляется самой базой данных. Использует синтаксис SQL GENERATED ALWAYS.

Существует два вида генерируемых столбцов: хранимые и виртуальные. Значение хранимого генерируемого столбца вычисляется при его записи (вставке или обновлении), и он занимает место в хранилище, как обычный столбец. Виртуальный генерируемый столбец не занимает места в хранилище; его значение вычисляется при чтении. Поэтому виртуальный генерируемый столбец похож на представление, а хранимый — на материализованное представление.

GeneratedField.expression

Выражение Expression, используемое базой данных для автоматического задания значения поля при каждом изменении модели.

Выражения должны быть детерминированными и ссылаться только на поля модели (в той же таблице базы данных). Генерируемые поля не могут ссылаться на другие генерируемые поля. Бэкенды баз данных могут накладывать дополнительные ограничения.

GeneratedField.output_field: Экземпляр поля модели, задающий тип данных поля.

GeneratedField.db_persist

Определяет, должен ли столбец базы данных занимать место в хранилище, как обычный столбец. Если задано значение False, столбец является виртуальным и не занимает места в хранилище базы данных.

PostgreSQL поддерживает только сохраняемые столбцы. Oracle поддерживает только виртуальные столбцы.

Ограничения баз данных

Для генерируемых полей существует множество ограничений, специфичных для конкретных баз данных. Django их не проверяет, поэтому база данных может выдать ошибку. Например, PostgreSQL требует, чтобы функции и операторы, на которые ссылается генерируемый столбец, были помечены как IMMUTABLE.

Всегда проверяйте, поддерживается ли expression вашей базой данных. См. документацию MariaDB, MySQL, Oracle, PostgreSQL или SQLite.

Изменено в Django 6.0:

Теперь значения GeneratedField автоматически обновляются из базы данных на бэкендах, которые это поддерживают (SQLite, PostgreSQL и Oracle), а на остальных бэкендах помечаются как отложенные.

`GenericIPAddressField`

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options) [исходный код]

Адрес IPv4 или IPv6 в строковом формате (например, 192.0.2.30 или 2a02:42fe::4). Виджет формы по умолчанию для этого поля — TextInput.

Нормализация адреса IPv6 соответствует разделу 2.2 RFC 4291, раздел 2.2, включая использование формата IPv4, предложенного в пункте 3 этого раздела, например ::ffff:192.0.2.0. Например, 2001:0::0:01 будет нормализован в 2001::1, а ::ffff:0a0a:0a0a — в ::ffff:10.10.10.10. Все символы преобразуются в нижний регистр.

GenericIPAddressField.protocol: Ограничивает допустимые значения указанным протоколом. Допустимые значения: 'both' (по умолчанию), 'IPv4' или 'IPv6'. Сравнение не учитывает регистр.

GenericIPAddressField.unpack_ipv4: Распаковывает адреса IPv4, отображённые в IPv6, например ::ffff:192.0.2.1. Если этот параметр включён, такой адрес будет распакован в 192.0.2.1. По умолчанию отключён. Можно использовать, только если для protocol задано значение 'both'.

Если вы допускаете пустые значения, необходимо также допускать значения null, поскольку пустые значения хранятся как null.

`ImageField`

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options) [исходный код]

Наследует все атрибуты и методы FileField, но также проверяет, что загруженный объект является допустимым изображением.

Помимо специальных атрибутов, доступных для FileField, ImageField также имеет атрибуты height и width.

Для удобства выполнения запросов по этим атрибутам ImageField имеет следующие необязательные аргументы:

ImageField.height_field: Имя поля модели, которое автоматически заполняется высотой изображения при каждом присваивании объекта изображения.

ImageField.width_field: Имя поля модели, которое автоматически заполняется шириной изображения при каждом присваивании объекта изображения.

Требуется библиотека pillow.

Экземпляры ImageField создаются в базе данных как столбцы varchar с максимальной длиной 100 символов по умолчанию. Как и для других полей, максимальную длину можно изменить с помощью аргумента max_length.

Виджет формы по умолчанию для этого поля — ClearableFileInput.

`IntegerField`

class IntegerField(**options) [исходный код]

Целое число. Допустимы только значения в определённых пределах (зависящих от базы данных). Значения от -2147483648 до 2147483647 совместимы со всеми базами данных, поддерживаемыми Django.

Для проверки введённых данных с учётом значений, поддерживаемых базой данных по умолчанию, используются MinValueValidator и MaxValueValidator.

`JSONField`

class JSONField(encoder=None, decoder=None, **options) [исходный код]

Поле для хранения данных в формате JSON. В Python данные представлены в собственных типах Python: словарях, списках, строках, числах, логических значениях и None.

JSONField поддерживается в MariaDB, MySQL, Oracle, PostgreSQL и SQLite (с включённым расширением JSON1).

JSONField.encoder

Необязательный подкласс json.JSONEncoder для сериализации типов данных, не поддерживаемых стандартным сериализатором JSON (например, datetime.datetime или UUID). Например, можно использовать класс DjangoJSONEncoder.

По умолчанию — json.JSONEncoder.

JSONField.decoder

Необязательный подкласс json.JSONDecoder для десериализации значения, полученного из базы данных. Значение будет иметь формат, выбранный пользовательским кодировщиком (чаще всего это строка). При десериализации может потребоваться учитывать, что вы не можете быть уверены в типе входных данных. Например, существует риск вернуть datetime, которое на самом деле было строкой, случайно имеющей тот же формат, что и выбранный для datetime.

По умолчанию — json.JSONDecoder.

Сведения о запросах к JSONField в базе данных см. в разделе Запросы к JSONField.

Значение по умолчанию

Если вы задаёте для поля default, убедитесь, что это вызываемый объект, например класс dict или функция, возвращающая новый объект при каждом вызове. Неправильное использование изменяемого объекта, например default={} или default=[], создаёт изменяемое значение по умолчанию, совместно используемое всеми экземплярами.

Индексация

Index и Field.db_index создают B-tree-индекс, который не особенно полезен при запросах к JSONField. Только в PostgreSQL можно использовать GinIndex, который для этого подходит лучше.

Пользователям PostgreSQL

В PostgreSQL есть два встроенных типа данных на основе JSON: json и jsonb. Главное различие между ними заключается в способе хранения и выполнения запросов. Поле json в PostgreSQL хранится в исходном строковом представлении JSON и при запросах по ключам должно декодироваться на лету. Поле jsonb хранится с учётом фактической структуры JSON, что позволяет создавать индексы. Компромисс заключается в небольших дополнительных затратах при записи в поле jsonb. JSONField использует jsonb.

Пользователям Oracle

Oracle Database не поддерживает хранение скалярных значений JSON. Поддерживаются только объекты и массивы JSON (представленные в Python с помощью dict и list).

`PositiveBigIntegerField`

class PositiveBigIntegerField(**options) [исходный код]

Как PositiveIntegerField, но допускает только значения ниже определённого предела (зависящего от базы данных). Значения от 0 до 9223372036854775807 совместимы со всеми базами данных, поддерживаемыми Django.

`PositiveIntegerField`

class PositiveIntegerField(**options) [исходный код]

Как IntegerField, но значение должно быть положительным или равным нулю (0). Допускаются только значения ниже определённого предела (зависящего от базы данных). Значения от 0 до 2147483647 совместимы со всеми базами данных, поддерживаемыми Django. Значение 0 принимается для обратной совместимости.

`PositiveSmallIntegerField`

class PositiveSmallIntegerField(**options) [исходный код]

Как PositiveIntegerField, но допускает только значения ниже определённого предела (зависящего от базы данных). Значения от 0 до 32767 совместимы со всеми базами данных, поддерживаемыми Django.

`SlugField`

class SlugField(max_length=50, **options) [исходный код]

Slug — термин из газетного дела. Slug — это короткая метка для чего-либо, состоящая только из букв, цифр, подчёркиваний или дефисов. Обычно их используют в URL.

Как и для CharField, можно указать max_length (ознакомьтесь также с примечанием о переносимости баз данных и max_length в этом разделе). Если max_length не указан, Django использует длину по умолчанию 50.

Автоматически устанавливает для Field.db_index значение True.

Часто бывает полезно автоматически заполнять SlugField на основе значения другого поля. Это можно настроить автоматически в административном интерфейсе с помощью prepopulated_fields.

Для проверки используются validate_slug или validate_unicode_slug.

SlugField.allow_unicode: Если задано значение True, поле принимает символы Unicode в дополнение к буквам ASCII. По умолчанию — False.

`SmallAutoField`

class SmallAutoField(**options) [исходный код]

Как AutoField, но допускает только значения ниже определённого предела (зависящего от базы данных). Значения от 1 до 32767 совместимы со всеми базами данных, поддерживаемыми Django.

`SmallIntegerField`

class SmallIntegerField(**options) [исходный код]

Как IntegerField, но допускает только значения ниже определённого предела (зависящего от базы данных). Значения от -32768 до 32767 совместимы со всеми базами данных, поддерживаемыми Django.

`TextField`

class TextField(**options) [исходный код]

Поле для большого объёма текста. Виджет формы по умолчанию для этого поля — Textarea.

Если указать атрибут max_length, он будет отражён в виджете Textarea автоматически созданного поля формы. Однако на уровне модели или базы данных он не применяется. Для этого используйте CharField.

TextField.db_collation: Необязательный параметр. Название сортировки поля в базе данных.

Примечание

Названия сортировок не стандартизированы. Поэтому этот параметр не будет переносимым между разными серверными частями баз данных.

Oracle

Oracle не поддерживает сортировки для TextField.

`TimeField`

class TimeField(auto_now=False, auto_now_add=False, **options) [исходный код]

Время, представленное в Python экземпляром datetime.time. Поддерживает те же параметры автоматического заполнения, что и DateField.

Виджет формы по умолчанию для этого поля — TimeInput. В административном интерфейсе добавлены некоторые сочетания клавиш JavaScript.

`URLField`

class URLField(max_length=200, **options) [исходный код]

CharField для URL, проверяемого с помощью URLValidator.

Виджет формы по умолчанию для этого поля — URLInput.

Как и все подклассы CharField, URLField принимает необязательный аргумент max_length. Если не указать max_length, будет использовано значение по умолчанию 200.

`UUIDField`

class UUIDField(**options) [исходный код]

Поле для хранения универсальных уникальных идентификаторов. Использует класс Python UUID. При использовании в PostgreSQL и MariaDB 10.7+ данные хранятся в типе данных uuid, в противном случае — в char(32).

Универсальные уникальные идентификаторы — хорошая альтернатива AutoField для primary_key. База данных не будет генерировать UUID за вас, поэтому рекомендуется использовать default:

import uuid
from django.db import models


class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

Обратите внимание, что в default передаётся вызываемый объект (без скобок), а не экземпляр UUID.

Поиск в PostgreSQL и MariaDB 10.7+

Использование поисковых выражений iexact, contains, icontains, startswith, istartswith, endswith или iendswith в PostgreSQL не работает для значений без дефисов, поскольку PostgreSQL и MariaDB 10.7+ хранят их в виде типа данных uuid с дефисами.

Поля отношений

Django также определяет набор полей, представляющих отношения.

`ForeignKey`

class ForeignKey(to, on_delete, **options) [исходный код]

Отношение «многие к одному». Требует два позиционных аргумента: класс, с которым связана модель, и параметр on_delete:

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()


class Car(models.Model):
    manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)

Первый позиционный аргумент может быть конкретным классом модели или отложенной ссылкой на класс модели. Также поддерживаются рекурсивные отношения, в которых модель связана сама с собой.

Подробную информацию о втором позиционном аргументе см. в разделе ForeignKey.on_delete.

Для ForeignKey автоматически создаётся индекс базы данных. Его можно отключить, задав для db_index значение False. Возможно, вы захотите избежать накладных расходов на индекс, если создаёте внешний ключ для обеспечения согласованности, а не для соединений, или если собираетесь создать альтернативный индекс, например частичный индекс или индекс по нескольким столбцам.

Представление в базе данных

Внутри Django добавляет "_id" к имени поля, чтобы сформировать имя его столбца в базе данных. В приведённом выше примере таблица базы данных для модели Car будет содержать столбец manufacturer_id. Это имя можно изменить явно, указав db_column, однако вашему коду никогда не придётся работать с именем столбца в базе данных (если только вы не пишете собственный SQL). Вы всегда будете работать с именами полей объекта модели.

Аргументы

ForeignKey принимает другие аргументы, определяющие особенности работы отношения.

ForeignKey.on_delete

Когда объект, на который ссылается ForeignKey, удаляется, Django эмулирует поведение ограничения SQL, заданного аргументом on_delete. Например, если у вас есть допускающий значение null ForeignKey и вы хотите, чтобы при удалении объекта, на который он ссылается, ему присваивалось значение null:

user = models.ForeignKey(
    User,
    models.SET_NULL,
    blank=True,
    null=True,
)

on_delete не создаёт ограничение SQL в базе данных. Поддержка каскадных действий на уровне базы данных может быть реализована позднее.

Допустимые значения для on_delete находятся в django.db.models:

CASCADE [исходный код]

Каскадное удаление. Django эмулирует поведение ограничения SQL ON DELETE CASCADE и также удаляет объект, содержащий внешний ключ.

Метод Model.delete() для связанных моделей не вызывается, но для всех удалённых объектов отправляются сигналы pre_delete и post_delete.
PROTECT [исходный код]

Запрещает удаление объекта, на который есть ссылка, вызывая исключение ProtectedError — подкласс django.db.IntegrityError.
RESTRICT [исходный код]
Запрещает удаление объекта, на который есть ссылка, вызывая исключение RestrictedError (подкласс django.db.IntegrityError). В отличие от PROTECT, удаление объекта, на который есть ссылка, разрешено, если он также ссылается на другой объект, удаляемый в ходе той же операции, но через отношение CASCADE.

Рассмотрим следующий набор моделей:
```
class Artist(models.Model):
    name = models.CharField(max_length=10)


class Album(models.Model):
    artist = models.ForeignKey(Artist, on_delete=models.CASCADE)


class Song(models.Model):
    artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
    album = models.ForeignKey(Album, on_delete=models.RESTRICT)
```
Artist можно удалить, даже если это означает удаление Album, на который ссылается Song, поскольку Song также ссылается на Artist через каскадное отношение. Например:
```
>>> artist_one = Artist.objects.create(name="artist one")
>>> artist_two = Artist.objects.create(name="artist two")
>>> album_one = Album.objects.create(artist=artist_one)
>>> album_two = Album.objects.create(artist=artist_two)
>>> song_one = Song.objects.create(artist=artist_one, album=album_one)
>>> song_two = Song.objects.create(artist=artist_one, album=album_two)
>>> album_one.delete()
# Raises RestrictedError.
>>> artist_two.delete()
# Raises RestrictedError.
>>> artist_one.delete()
(4, {'Song': 2, 'Album': 1, 'Artist': 1})
```
SET_NULL [исходный код]

Устанавливает для ForeignKey значение null; это возможно, только если null имеет значение True.
SET_DEFAULT [исходный код]

Устанавливает для ForeignKey значение по умолчанию; для ForeignKey должно быть задано значение по умолчанию.
SET() [исходный код]
Устанавливает для ForeignKey значение, переданное в SET(), либо, если передана вызываемая функция, результат её вызова. В большинстве случаев необходимо передать вызываемую функцию, чтобы избежать выполнения запросов при импорте models.py:
```
from django.conf import settings
from django.contrib.auth import get_user_model
from django.db import models


def get_sentinel_user():
    return get_user_model().objects.get_or_create(username="deleted")[0]


class MyModel(models.Model):
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.SET(get_sentinel_user),
    )
```
DO_NOTHING [исходный код]

Не выполняет никаких действий. Если ваша база данных обеспечивает ссылочную целостность, это приведёт к возникновению исключения IntegrityError, если вы вручную не добавите SQL-ограничение ON DELETE для поля базы данных.

ForeignKey.limit_choices_to

Ограничивает доступные варианты для этого поля, когда оно отображается в ModelForm или в административной панели (по умолчанию для выбора доступны все объекты из набора запросов). Можно использовать словарь, объект Q или вызываемую функцию, возвращающую словарь либо объект Q.

Например:

staff_member = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    limit_choices_to={"is_staff": True},
)

заставляет соответствующее поле в ModelForm отображать только экземпляры User, у которых есть is_staff=True. Это может быть полезно в административной панели Django.

Форма с вызываемой функцией может быть полезна, например, при использовании модуля Python datetime для ограничения выбора диапазоном дат. Например:

def limit_pub_date_choices():
    return {"pub_date__lte": datetime.date.today()}


limit_choices_to = limit_pub_date_choices

Если limit_choices_to — это объект Q object или возвращает его, что удобно для сложных запросов, это повлияет на доступные варианты в административной панели, только если поле не указано в raw_id_fields в ModelAdmin модели.

Примечание

Если для limit_choices_to используется вызываемая функция, она вызывается каждый раз при создании новой формы. Она также может вызываться при проверке модели, например командами управления или административной панелью. Административная панель несколько раз создаёт наборы запросов для проверки введённых данных формы в различных крайних случаях, поэтому существует вероятность, что ваша функция будет вызвана несколько раз.

ForeignKey.related_name

Имя отношения, используемое для обратной ссылки от связанного объекта к этому объекту. Это также значение по умолчанию для related_query_name (имени, используемого для обратного фильтра в целевой модели). Полное объяснение и пример см. в документации по связанным объектам. Обратите внимание, что это значение необходимо задавать при определении отношений в абстрактных моделях; при этом доступен специальный синтаксис.

Если вы не хотите, чтобы Django создавал обратное отношение, задайте для related_name значение '+' или добавьте в его конец '+'. Например, это гарантирует, что у модели User не будет обратного отношения к этой модели:

user = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    related_name="+",
)

ForeignKey.related_query_name

Имя, используемое для обратного фильтра в целевой модели. По умолчанию используется значение related_name или, если оно задано, default_related_name; в противном случае используется имя модели:

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(
        Article,
        on_delete=models.CASCADE,
        related_name="tags",
        related_query_name="tag",
    )
    name = models.CharField(max_length=255)


# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")

Как и related_name, related_query_name поддерживает подстановку метки приложения и имени класса с помощью специального синтаксиса.

ForeignKey.to_field: Поле связанного объекта, на которое указывает отношение. По умолчанию Django использует первичный ключ связанного объекта. Если вы ссылаетесь на другое поле, оно должно иметь unique=True.

ForeignKey.db_constraint

Определяет, следует ли создавать ограничение в базе данных для этого внешнего ключа. По умолчанию задано значение True, которое почти наверняка вам и нужно; значение False может серьёзно навредить целостности данных. Тем не менее, вот несколько случаев, когда это может понадобиться:

У вас есть некорректные устаревшие данные.
Вы используете сегментирование базы данных.

Если задано значение False, обращение к несуществующему связанному объекту вызовет его исключение DoesNotExist.

ForeignKey.swappable

Управляет поведением системы миграций, если этот ForeignKey указывает на заменяемую модель. Если задано значение True (по умолчанию), то, когда ForeignKey указывает на модель, соответствующую текущему значению settings.AUTH_USER_MODEL (или другой настройки заменяемой модели), отношение будет сохранено в миграции со ссылкой на настройку, а не непосредственно на модель.

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

Значение False не позволяет ссылаться на заменяемую модель, даже если она заменена: False означает, что миграции, созданные с этим ForeignKey, всегда будут ссылаться на указанную вами модель (поэтому они безусловно завершатся ошибкой, если пользователь попытается запустить их с моделью User, которую вы не поддерживаете, например).

Если вы не уверены, оставьте значение по умолчанию — True.

`ManyToManyField`

class ManyToManyField(to, **options) [исходный код]

Отношение «многие ко многим». Требует один позиционный аргумент: класс, с которым связана модель. Он работает точно так же, как и для ForeignKey, в том числе поддерживает рекурсивные и отложенные отношения.

Связанные объекты можно добавлять, удалять или создавать с помощью RelatedManager поля.

Представление в базе данных

Внутри Django создаёт промежуточную таблицу соединения для представления отношения «многие ко многим». По умолчанию имя этой таблицы формируется из имени поля «многие ко многим» и имени таблицы модели, которой оно принадлежит. Поскольку некоторые базы данных не поддерживают имена таблиц длиннее определённого предела, такие имена автоматически усекаются, а для обеспечения уникальности используется хеш, например author_books_9cdf. Имя таблицы соединения можно задать вручную с помощью параметра db_table.

Аргументы

ManyToManyField принимает дополнительные аргументы — все необязательные, — которые управляют работой отношения.

ManyToManyField.related_name: То же, что и ForeignKey.related_name.

ManyToManyField.related_query_name: То же, что и ForeignKey.related_query_name.

ManyToManyField.limit_choices_to: То же, что и ForeignKey.limit_choices_to.

ManyToManyField.symmetrical

Используется только при определении ManyToManyField для самой себя. Рассмотрим следующую модель:

from django.db import models


class Person(models.Model):
    friends = models.ManyToManyField("self")

При обработке этой модели Django определяет, что она содержит ManyToManyField, ссылающееся на неё саму, и поэтому не добавляет атрибут person_set в класс Person. Вместо этого предполагается, что ManyToManyField симметрично: если я ваш друг, то и вы мой друг.

Если вам не нужна симметрия в отношениях «многие ко многим» с self, задайте для symmetrical значение False. Это заставит Django добавить дескриптор для обратного отношения, позволяя задавать ManyToManyField как несимметричные.

ManyToManyField.through

Django автоматически создаёт таблицу для управления отношениями «многие ко многим». Однако, если вы хотите задать промежуточную таблицу вручную, можно использовать параметр through, указав модель Django, представляющую нужную промежуточную таблицу.

Модель through можно указать непосредственно классом модели или отложенной ссылкой на него.

Чаще всего этот параметр используют, когда нужно связать дополнительные данные с отношением «многие ко многим».

Примечание

Для рекурсивных отношений с использованием промежуточной модели невозможно определить имена обратных аксессоров, поскольку они совпадали бы. Необходимо задать related_name хотя бы для одного из них. Если вы не хотите, чтобы Django создавал обратное отношение, задайте для related_name значение '+'.

Порядок внешних ключей в промежуточных моделях

При определении асимметричного отношения «многие ко многим» модели с самой собой с использованием промежуточной модели и без указания through_fields первый внешний ключ промежуточной модели будет считаться исходной стороной ManyToManyField, а второй — целевой стороной. Например:

from django.db import models


class Manufacturer(models.Model):
    name = models.CharField(max_length=255)
    clients = models.ManyToManyField(
        "self", symmetrical=False, related_name="suppliers", through="Supply"
    )


class Supply(models.Model):
    supplier = models.ForeignKey(
        Manufacturer, models.CASCADE, related_name="supplies_given"
    )
    client = models.ForeignKey(
        Manufacturer, models.CASCADE, related_name="supplies_received"
    )
    product = models.CharField(max_length=255)

Здесь модель Manufacturer определяет отношение «многие ко многим» с clients в роли поставщика. Поэтому внешний ключ supplier (исходный) должен идти перед внешним ключом client (целевым) в промежуточной модели Supply.

Указание through_fields=("supplier", "client") в ManyToManyField делает порядок внешних ключей модели through несущественным.

Если вы не указали явную модель through, всё равно существует неявный класс модели through, с помощью которого можно напрямую обращаться к таблице, созданной для хранения связи. Он содержит три поля для связи моделей, первичный ключ и два внешних ключа. Для двух внешних ключей задано уникальное ограничение.

Если исходная и целевая модели различаются, создаются следующие поля:

id: первичный ключ отношения.
<containing_model>_id: id модели, объявляющей ManyToManyField.
<other_model>_id: id модели, на которую указывает ManyToManyField.

Если ManyToManyField указывает на ту же модель, с которой начинается, создаются следующие поля:

id: первичный ключ отношения.
from_<model>_id: id экземпляра, указывающего на модель (то есть исходного экземпляра).
to_<model>_id: id экземпляра, на который указывает отношение (то есть целевого экземпляра модели).

Этот класс можно использовать для запросов связанных записей для заданного экземпляра модели так же, как обычную модель:

Model.m2mfield.through.objects.all()

ManyToManyField.through_fields

Используется только при указании пользовательской промежуточной модели. Обычно Django автоматически определяет, какие поля промежуточной модели следует использовать для создания отношения «многие ко многим». Однако рассмотрим следующие модели:

from django.db import models


class Person(models.Model):
    name = models.CharField(max_length=50)


class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(
        Person,
        through="Membership",
        through_fields=("group", "person"),
    )


class Membership(models.Model):
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    inviter = models.ForeignKey(
        Person,
        on_delete=models.CASCADE,
        related_name="membership_invites",
    )
    invite_reason = models.CharField(max_length=64)

У Membership есть два внешних ключа к Person (person и inviter), из-за чего отношение становится неоднозначным и Django не может определить, какой из них использовать. В этом случае необходимо явно указать, какие внешние ключи Django должен использовать, с помощью through_fields, как в приведённом выше примере.

through_fields принимает кортеж из двух элементов ('field1', 'field2'), где field1 — имя внешнего ключа к модели, в которой определено ManyToManyField (в данном случае group), а field2 — имя внешнего ключа к целевой модели (в данном случае person).

Если промежуточная модель содержит более одного внешнего ключа к любой из моделей (или даже к обеим моделям), участвующим в отношении «многие ко многим», необходимо указать through_fields. Это также относится к рекурсивным отношениям, использующим промежуточную модель, если у неё более двух внешних ключей к этой модели или если вы хотите явно указать, какие именно два ключа следует использовать Django.

ManyToManyField.db_table: Имя таблицы для хранения данных отношения «многие ко многим». Если оно не указано, Django использует имя по умолчанию, основанное на имени таблицы модели, определяющей отношение, и имени самого поля.

ManyToManyField.db_constraint

Определяет, следует ли создавать ограничения в базе данных для внешних ключей промежуточной таблицы. По умолчанию задано значение True, которое почти наверняка вам и нужно; значение False может серьёзно навредить целостности данных. Тем не менее, вот несколько случаев, когда это может понадобиться:

У вас есть некорректные устаревшие данные.
Вы используете сегментирование базы данных.

Одновременная передача db_constraint и through приводит к ошибке.

ManyToManyField.swappable

Управляет поведением системы миграций, если этот ManyToManyField указывает на заменяемую модель. Если задано значение True (по умолчанию), то, когда ManyToManyField указывает на модель, соответствующую текущему значению settings.AUTH_USER_MODEL (или другой настройки заменяемой модели), отношение будет сохранено в миграции со ссылкой на настройку, а не непосредственно на модель.

Если вы не уверены, оставьте значение по умолчанию — True.

ManyToManyField не поддерживает validators.

null не влияет на работу, поскольку на уровне базы данных невозможно потребовать наличие отношения.

`OneToOneField`

class OneToOneField(to, on_delete, parent_link=False, **options) [исходный код]

Связь «один к одному». Концептуально она похожа на ForeignKey с параметром unique=True, но обратная сторона связи напрямую возвращает один объект.

Чаще всего она полезна в качестве первичного ключа модели, которая тем или иным образом «расширяет» другую модель; например, наследование от нескольких таблиц реализуется добавлением неявной связи «один к одному» от дочерней модели к родительской.

Требуется один позиционный аргумент: класс, с которым будет связана модель. Это работает точно так же, как и для ForeignKey, включая все параметры для рекурсивных и отложенных связей.

Если не указать аргумент related_name для OneToOneField, Django будет использовать в качестве значения по умолчанию имя текущей модели в нижнем регистре.

Для следующего примера:

from django.conf import settings
from django.db import models


class MySpecialUser(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="supervisor_of",
    )

итоговая модель User будет иметь следующие атрибуты:

>>> user = User.objects.get(pk=1)
>>> hasattr(user, "myspecialuser")
True
>>> hasattr(user, "supervisor_of")
True

При обращении к обратной связи возникает исключение RelatedObjectDoesNotExist, если в связанной таблице нет записи. Это подкласс исключения Model.DoesNotExist целевой модели; к нему можно обратиться как к атрибуту обратного средства доступа. Например, если пользователю не назначен руководитель через MySpecialUser:

try:
    user.supervisor_of
except User.supervisor_of.RelatedObjectDoesNotExist:
    pass

Кроме того, OneToOneField принимает все дополнительные аргументы, поддерживаемые ForeignKey, а также один дополнительный аргумент:

OneToOneField.parent_link: Если параметр True указан и используется в модели, наследующей другую конкретную модель, это означает, что данное поле следует использовать как связь с родительским классом вместо дополнительного поля OneToOneField, которое обычно неявно создаётся при наследовании.

Примеры использования OneToOneField см. в разделе Связи «один к одному».

Отложенные связи

Отложенные связи позволяют ссылаться на модели по их именам (в виде строк) или создавать рекурсивные связи. Для отложенной ссылки на модели можно использовать строки в качестве первого аргумента любого поля связи. Такая ссылка может быть рекурсивной, относительной или абсолютной.

Рекурсивные

Чтобы определить связь, в которой модель ссылается на саму себя, используйте "self" в качестве первого аргумента поля связи:

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

При использовании в абстрактной модели рекурсивная связь разрешается так, что каждый конкретный подкласс ссылается на себя.

Относительные

Если связь требуется создать с ещё не определённой моделью, на неё можно сослаться по имени, а не по объекту модели:

from django.db import models


class Car(models.Model):
    manufacturer = models.ForeignKey(
        "Manufacturer",
        on_delete=models.CASCADE,
    )


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

Связи, определённые таким образом в абстрактных моделях, разрешаются при наследовании модели конкретной моделью и не являются относительными к app_label абстрактной модели:

products/models.py

from django.db import models


class AbstractCar(models.Model):
    manufacturer = models.ForeignKey("Manufacturer", on_delete=models.CASCADE)

    class Meta:
        abstract = True

production/models.py

from django.db import models
from products.models import AbstractCar


class Manufacturer(models.Model):
    name = models.TextField()


class Car(AbstractCar):
    pass

В этом примере связь Car.manufacturer будет разрешена как production.Manufacturer, поскольку она указывает на конкретную модель, определённую в файле production/models.py.

Повторно используемые модели с относительными ссылками

Относительные ссылки позволяют создавать повторно используемые абстрактные модели со связями, которые могут разрешаться в разные реализации указанных моделей в различных подклассах разных приложений.

Абсолютные

В абсолютных ссылках модель указывается с помощью её app_label и имени класса, что позволяет ссылаться на модели из разных приложений. Этот тип отложенной связи также может помочь разрешить циклические импорты.

Например, если модель Manufacturer определена в другом приложении под названием thirdpartyapp, на неё можно сослаться так:

class Car(models.Model):
    manufacturer = models.ForeignKey(
        "thirdpartyapp.Manufacturer",
        on_delete=models.CASCADE,
    )

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

Справочник по API полей

class Field [исходный код]

Field — это абстрактный класс, представляющий столбец таблицы базы данных. Django использует поля для создания таблицы базы данных (db_type()), преобразования типов Python в типы базы данных (get_prep_value()) и обратно (from_db_value()).

Таким образом, поле — это важная составляющая различных API Django, в частности, models и querysets.

В моделях поле создаётся как атрибут класса и представляет отдельный столбец таблицы; см. раздел Модели. У поля есть такие атрибуты, как null и unique, а также методы, которые Django использует для преобразования значения поля в значения, специфичные для базы данных.

Field является подклассом RegisterLookupMixin, поэтому для него можно зарегистрировать как Transform, так и Lookup, чтобы использовать их в QuerySet (например, field_name__exact="foo"). Все встроенные условия поиска зарегистрированы по умолчанию.

Все встроенные поля Django, например CharField, являются отдельными реализациями Field. Если вам нужно пользовательское поле, можно создать подкласс любого встроенного поля или написать Field с нуля. В обоих случаях см. раздел Создание пользовательских полей модели.

description

Подробное описание поля, например для приложения django.contrib.admindocs.

Описание может иметь следующий формат:

description = _("String (up to %(max_length)s)")

где аргументы подставляются из __dict__ поля.

descriptor_class: Класс, реализующий протокол дескрипторов, который создаётся и назначается атрибуту экземпляра модели. Конструктор должен принимать один аргумент — экземпляр Field. Переопределение этого атрибута класса позволяет настроить поведение получения и установки значения.

Для преобразования Field в тип, специфичный для базы данных, Django предоставляет несколько методов:

get_internal_type() [исходный код]

Возвращает строку с названием этого поля для внутренних нужд бэкенда. По умолчанию возвращается имя класса.

Примеры использования в пользовательских полях см. в разделе Имитация встроенных типов полей.

db_type(connection) [исходный код]

Возвращает тип данных столбца базы данных для Field с учётом connection.

Примеры использования в пользовательских полях см. в разделе Пользовательские типы данных базы данных.

rel_db_type(connection) [исходный код]

Возвращает тип данных столбца базы данных для таких полей, как ForeignKey и OneToOneField, которые ссылаются на Field, с учётом connection.

Примеры использования в пользовательских полях см. в разделе Пользовательские типы данных базы данных.

Есть три основных ситуации, в которых Django необходимо взаимодействовать с бэкендом базы данных и полями:

при выполнении запроса к базе данных (значение Python -> значение бэкенда базы данных)
при загрузке данных из базы данных (значение бэкенда базы данных -> значение Python)
при сохранении в базе данных (значение Python -> значение бэкенда базы данных)

При выполнении запроса используются get_db_prep_value() и get_prep_value():

get_prep_value(value) [исходный код]

value — это текущее значение атрибута модели; метод должен возвращать данные в формате, подготовленном для использования в качестве параметра запроса.

Примеры использования см. в разделе Преобразование объектов Python в значения запроса.

get_db_prep_value(value, connection, prepared=False) [исходный код]

Преобразует value в значение, специфичное для бэкенда. По умолчанию возвращает value, если prepared=True, и get_prep_value(), если False.

Примеры использования см. в разделе Преобразование значений запроса в значения базы данных.

При загрузке данных используется from_db_value():

from_db_value(value, expression, connection)

Преобразует значение, полученное из базы данных, в объект Python. Это обратная операция по отношению к get_prep_value().

Для большинства встроенных полей этот метод не используется, поскольку бэкенд базы данных уже возвращает правильный тип Python или выполняет преобразование самостоятельно.

expression совпадает с self.

Примеры использования см. в разделе Преобразование значений в объекты Python.

Примечание

В целях повышения производительности from_db_value не реализован как пустая операция для полей, которым он не требуется (то есть для всех полей Django). Поэтому вы не можете вызывать super в своём определении.

При сохранении используются pre_save() и get_db_prep_save():

get_db_prep_save(value, connection) [исходный код]: То же, что и get_db_prep_value(), но вызывается, когда значение поля нужно сохранить в базе данных. По умолчанию возвращает get_db_prep_value().

pre_save(model_instance, add) [исходный код]

Метод, вызываемый перед get_db_prep_save() для подготовки значения перед сохранением (например, для DateField.auto_now).

model_instance — это экземпляр, которому принадлежит данное поле, а add указывает, сохраняется ли экземпляр в базе данных впервые.

Метод должен возвращать значение соответствующего атрибута из model_instance для этого поля. Имя атрибута содержится в self.attname (оно задаётся методом Field).

Примеры использования см. в разделе Предварительная обработка значений перед сохранением.

Часто значения полей поступают в другом типе — например, при десериализации или из форм.

to_python(value) [исходный код]

Преобразует значение в объект Python правильного типа. Этот метод является обратным по отношению к value_to_string(), а также вызывается в clean().

Примеры использования см. в разделе Преобразование значений в объекты Python.

Помимо сохранения в базе данных, поле должно уметь сериализовать своё значение:

value_from_object(obj) [исходный код]

Возвращает значение поля для заданного экземпляра модели.

Этот метод часто используется методом value_to_string().

value_to_string(obj) [исходный код]

Преобразует obj в строку. Используется для сериализации значения поля.

Примеры использования см. в разделе Преобразование данных поля для сериализации.

При использовании model forms объекту Field необходимо знать, каким полем формы следует его представить:

formfield(form_class=None, choices_form_class=None, **kwargs) [исходный код]

Возвращает поле формы django.forms.Field по умолчанию для ModelForm.

Если переопределённый метод formfield() возвращает None, это поле исключается из ModelForm.

По умолчанию, если и form_class, и choices_form_class имеют значение None, используется CharField. Если у поля есть choices, а choices_form_class не задан, используется TypedChoiceField.

Примеры использования см. в разделе Указание поля формы для поля модели.

deconstruct() [исходный код]

Возвращает кортеж из четырёх элементов с данными, достаточными для повторного создания поля:

Имя поля в модели.
Путь импорта поля (например, "django.db.models.IntegerField"). Следует использовать наиболее переносимую версию, поэтому менее конкретный вариант может быть предпочтительнее.
Список позиционных аргументов.
Словарь именованных аргументов.

Этот метод необходимо добавить в поля, созданные до версии 1.7, чтобы перенести их данные с помощью миграций.

Регистрация и получение условий поиска

Field реализует API регистрации условий поиска. Этот API позволяет настраивать доступные для класса поля и его экземпляров условия поиска, а также способ получения условий поиска из поля.

Справочник по атрибутам полей

Каждый экземпляр Field содержит несколько атрибутов, позволяющих анализировать его поведение. Используйте эти атрибуты вместо проверок isinstance, если нужно написать код, зависящий от функциональности поля. Их можно использовать вместе с API Model._meta, чтобы сузить поиск конкретных типов полей. Пользовательские поля модели должны реализовывать эти флаги.

Атрибуты полей

Field.auto_created: Логический флаг, указывающий, было ли поле создано автоматически, например OneToOneField, используемое при наследовании моделей.

Field.concrete: Логический флаг, указывающий, связан ли столбец базы данных с полем.

Field.hidden: Логический флаг, указывающий, является ли поле скрытым и должно ли оно по умолчанию исключаться из результатов Options.get_fields(). Например, таково обратное поле для ForeignKey, у которого related_name начинается с '+'.

Field.is_relation: Логический флаг, указывающий, содержит ли поле ссылки на одну или несколько других моделей, необходимые для его работы (например, ForeignKey, ManyToManyField, OneToOneField и т. д.).

Field.model: Возвращает модель, в которой определено поле. Если поле определено в суперклассе модели, model будет ссылаться на суперкласс, а не на класс экземпляра.

Атрибуты полей со связями

Эти атрибуты используются для получения сведений о кратности и других характеристиках связи. Они присутствуют у всех полей, однако булевы значения (вместо None) у них будут только в том случае, если поле является типом связи (Field.is_relation=True).

Field.many_to_many: Логический флаг, равный True, если поле имеет связь «многие ко многим», и False в противном случае. Единственное поле Django, для которого это значение равно True, — ManyToManyField.

Field.many_to_one: Логический флаг, равный True, если поле имеет связь «многие к одному», например ForeignKey, и False в противном случае.

Field.one_to_many: Логический флаг, равный True, если поле имеет связь «один ко многим», например GenericRelation или обратную связь для ForeignKey, и False в противном случае.

Field.one_to_one: Логический флаг, равный True, если поле имеет связь «один к одному», например OneToOneField, и False в противном случае.

Field.related_model: Указывает модель, с которой связано поле. Например, Author в ForeignKey(Author, on_delete=models.CASCADE). Значение related_model для GenericForeignKey всегда равно None.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/6.0/ref/models/fields/

Справочник по полям модели

Параметры полей

null

blank

choices

Типы перечислений

db_column

db_comment

db_default

db_index

db_tablespace

default

editable

error_messages

help_text

primary_key

unique

unique_for_date

unique_for_month

unique_for_year

verbose_name

validators

Типы полей

AutoField

BigAutoField

BigIntegerField

BinaryField

BooleanField

CompositePrimaryKey

CharField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FileField и FieldFile

FilePathField

FloatField

GeneratedField

GenericIPAddressField

ImageField

IntegerField

JSONField

PositiveBigIntegerField

PositiveIntegerField

PositiveSmallIntegerField

SlugField

SmallAutoField

SmallIntegerField

TextField

TimeField

URLField

UUIDField

Поля отношений

ForeignKey

Представление в базе данных

Аргументы

ManyToManyField

Представление в базе данных

Аргументы

OneToOneField

Отложенные связи

Рекурсивные

Относительные

Абсолютные

Справочник по API полей

Регистрация и получение условий поиска

Справочник по атрибутам полей

Атрибуты полей

Атрибуты полей со связями

`null`

`blank`

`choices`

`db_column`

`db_comment`

`db_default`

`db_index`

`db_tablespace`

`default`

`editable`

`error_messages`

`help_text`

`primary_key`

`unique`

`unique_for_date`

`unique_for_month`

`unique_for_year`

`verbose_name`

`validators`

`AutoField`

`BigAutoField`

`BigIntegerField`

`BinaryField`

`BooleanField`

`CompositePrimaryKey`

`CharField`

`DateField`

`DateTimeField`

`DecimalField`

`DurationField`

`EmailField`

`FileField`

`FileField` и `FieldFile`

`FilePathField`

`FloatField`

`GeneratedField`

`GenericIPAddressField`

`ImageField`

`IntegerField`

`JSONField`

`PositiveBigIntegerField`

`PositiveIntegerField`

`PositiveSmallIntegerField`

`SlugField`

`SmallAutoField`

`SmallIntegerField`

`TextField`

`TimeField`

`URLField`

`UUIDField`

`ForeignKey`

`ManyToManyField`

`OneToOneField`