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

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

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

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

null

Field.null

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

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

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

blank

Field.blank

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

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

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, 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 элементов. См. ниже пример наследования для выбора с использованием более сложного типа данных. Если кортеж не задан или последний элемент не является (ленивой) строкой, 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 Functional API с оговоркой, что метки генерируются автоматически, как показано выше:

>>> 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 установлены, default будет иметь приоритет при создании экземпляров в коде Python. db_default по-прежнему будет установлено на уровне базы данных и будет использоваться при вставке строк за пределами ORM или при добавлении нового поля в миграцию.

db_index

Field.db_index

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

db_tablespace

Field.db_tablespace

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

default

Field.default

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

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

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. Дополнительные ключи сообщений об ошибках указаны для каждого поля в разделе Типы полей ниже.

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

help_text

Field.help_text

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

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

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. Только один первичный ключ разрешен для объекта.

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

Поле первичного ключа устанавливается в None при deleting объекта.

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.

BooleanField

class BooleanField(**options)

Поле «истина/ложь».

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

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

CharField

class CharField(max_length=None, **options)

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

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

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

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

CharField.max_length

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

Примечание

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

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

Добавлена поддержка колонок с неограниченной VARCHAR в PostgreSQL.

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 взаимоисключающие. Любая комбинация этих параметров приведет к ошибке.

DateTimeField

class DateTimeField(auto_now=False, auto_now_add=False, **options)

Дата и время, представленная в Python объектом datetime.datetime.

Принимает те же дополнительные аргументы, что и DateField.

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

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 в противном случае.

DurationField

class DurationField(**options)

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

EmailField

class EmailField(max_length=254, **options)

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

FileField

class FileField(upload_to='', storage=None, max_length=100, **options)

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

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

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	Имя файла, которое изначально было предоставлено файлу. Это может быть учтено или не учтено при определении конечного пути назначения.

Например:

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 (см. ниже) в модели требует нескольких шагов:

1. В файле настроек вам необходимо определить MEDIA_ROOT как полный путь к каталогу, в котором вы хотите, чтобы Django хранил загруженные файлы. (Для повышения производительности эти файлы не хранятся в базе данных.) Определите MEDIA_URL как базовый публичный URL этого каталога. Убедитесь, что этот каталог доступен для записи пользователем веб-сервера.
2. Добавьте FileField или ImageField в свою модель, определив параметр upload_to, чтобы указать подкаталог MEDIA_ROOT для использования загруженных файлов.
3. В вашу базу данных будет сохранён только путь к файлу (относительно MEDIA_ROOT). Скорее всего, вы захотите использовать удобный атрибут url, предоставляемый Django. Например, если ваше 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 включает несколько методов, которые могут использоваться для взаимодействия с базовым файлом:

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 в противном случае.

GeneratedField

class GeneratedField(expression, output_field, db_persist=None, **kwargs)

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

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

GeneratedField.expression

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

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

GeneratedField.output_field

Экземпляр поля модели для определения типа данных поля.

GeneratedField.db_persist

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

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

GenericIPAddressField

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)

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

Нормализация адресов IPv6 соответствует RFC 4291#section-2.2 разделу 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, отображаемые как ::ffff:192.0.2.1. Если этот параметр включен, указанный адрес будет распакован до 192.0.2.1. По умолчанию отключен. Может быть использован только при protocol установленном в 'both'.

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

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 для проверки ввода, основываясь на значениях, которые поддерживает база данных по умолчанию.

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

JSONField

class JSONField(encoder=None, decoder=None, **options)

Поле для хранения данных, закодированных в формате JSON. В 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.

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)

Псевдоним — термин из журналистики. Псевдоним — это короткий ярлык для чего-либо, содержащий только буквы, цифры, символы нижнего подчёркивания или дефисы. Обычно они используются в 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.

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

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

ForeignKey

class ForeignKey(to, on_delete, **options)

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

Для создания рекурсивного отношения — объекта, имеющего отношение «многие ко одному» к самому себе — используйте models.ForeignKey('self', on_delete=models.CASCADE).

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

from django.db import models


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


class Manufacturer(models.Model):
    # ...
    pass

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

from django.db import models


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

    class Meta:
        abstract = True

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


class Manufacturer(models.Model):
    pass


class Car(AbstractCar):
    pass


# Car.manufacturer will point to `production.Manufacturer` here.

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

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

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

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

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

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

Аргументы

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

ForeignKey.on_delete

Когда объект, на который ссылается ForeignKey, удаляется, Django эмулирует поведение SQL-ограничения, указанного в аргументе on_delete. Например, если у вас есть необязательный 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 и также удаляет объект, содержащий ForeignKey.

  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 отображает только Users с 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 модели, представляющей промежуточную таблицу, которую вы хотите использовать.

Наиболее распространенное применение этого параметра — это когда вы хотите связать дополнительные данные с отношением многие ко многим.

Примечание

Если вы не хотите иметь несколько ассоциаций между одними и теми же экземплярами, добавьте UniqueConstraint, включая поля from и to. Автоматически генерируемые Django таблицы «многие ко многим» включают в себя такое ограничение.

Примечание

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

Если вы не укажете явную модель 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 принимает 2-кортеж ('field1', 'field2'), где field1 — имя внешнего ключа к модели, на которой определён ManyToManyField (group в данном случае), и field2 — имя внешнего ключа к целевой модели (person в данном случае).

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

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

Ошибка передавать и db_constraint, и through.

ManyToManyField.swappable

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

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

В случае сомнений оставьте его по умолчанию — 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.

Справочник по 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"). Все field_name__exact="foo" по умолчанию зарегистрированы.

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

description

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

Описание может иметь вид:

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

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

descriptor_class

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

Для сопоставления 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.

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

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

deconstruct()

Возвращает 4-кортеж с достаточной информацией для реконструкции поля:

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

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

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

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

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

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

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

Field.auto_created

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

Field.concrete

Флаг булевого типа, указывающий, связано ли с полем поле базы данных.

Field.hidden

Флаг булевого типа, указывающий, используется ли поле для поддержки функциональности другого поля без скрытия (например, content_type и object_id поля, составляющие GenericForeignKey). Флаг hidden используется для выделения того, что составляет общедоступный подмножество полей в модели из всех полей в модели.

Примечание

Options.get_fields() по умолчанию исключает скрытые поля. Передайте include_hidden=True для возвращения скрытых полей в результатах.

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.