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

В этом документе содержатся все 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 [source]

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

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

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 перечисления Функциональный 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 [source]

Имя пространства таблиц базы данных для использования для индекса этого поля, если это поле индексировано. Значение по умолчанию — настройка проекта 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 [source]

Аргумент 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 [source]

Если 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 [source]

Список валидаторов для этого поля. Для получения дополнительной информации см. документацию по валидаторам.

Типы полей моделей

AutoField

class AutoField(**options) [source]

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

BigAutoField

class BigAutoField(**options) [source]

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

BigIntegerField

class BigIntegerField(**options) [source]

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

BinaryField

class BinaryField(max_length=None, **options) [source]

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

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

BinaryField.max_length

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

BooleanField

class BooleanField(**options) [source]

Поле логического типа (истина/ложь).

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

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

CharField

class CharField(max_length=None, **options) [source]

Строковое поле для строк небольшой и большой длины.

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

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

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

CharField.max_length

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

Примечание

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

CharField.db_collation

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

Примечание

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

Oracle

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

DateField

class DateField(auto_now=False, auto_now_add=False, **options) [source]

Дата, представленная в 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) [source]

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

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

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

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options) [source]

Десятичное число с фиксированной точностью, представленное в 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) [source]

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

EmailField

class EmailField(max_length=254, **options) [source]

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

FileField

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

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

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

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 [source]

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

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

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

FieldFile.name

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

FieldFile.path [source]

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

FieldFile.size [source]

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

FieldFile.url [source]

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

FieldFile.open(mode='rb') [source]

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

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

FieldFile.close() [source]

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

FieldFile.save(name, content, save=True) [source]

Этот метод принимает имя файла и содержимое файла и передает их классу хранилища для поля, а затем связывает сохранённый файл с полем модели. Если вы хотите вручную связать данные файла с экземплярами 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) [source]

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

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

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

FilePathField

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options) [source]

Поле 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) [source]

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

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

GeneratedField

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

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

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

GeneratedField.expression

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

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

GeneratedField.output_field

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

GeneratedField.db_persist

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

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

GenericIPAddressField

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

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

Нормализация адресов IPv6 соответствует RFC 4291#section-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) [source]

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

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

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

ImageField.height_field

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

ImageField.width_field

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

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

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

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

IntegerField

class IntegerField(**options) [source]

Целое число. Значения от -2147483648 до 2147483647 безопасны во всех базах данных, поддерживаемых Django.

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

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

JSONField

class JSONField(encoder=None, decoder=None, **options) [source]

Поле для хранения данных, закодированных в формате 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) [source]

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

PositiveIntegerField

class PositiveIntegerField(**options) [source]

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options) [source]

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

SlugField

class SlugField(max_length=50, **options) [source]

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) [source]

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

SmallIntegerField

class SmallIntegerField(**options) [source]

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

TextField

class TextField(**options) [source]

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

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

TextField.db_collation

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

Примечание

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

Oracle

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

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options) [source]

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

По умолчанию для этого поля используется виджет TimeInput. Админка добавляет некоторые JavaScript-короткоходы.

URLField

class URLField(max_length=200, **options) [source]

Поле CharField для URL-адреса, валидированное с помощью URLValidator.

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

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

UUIDField

class UUIDField(**options) [source]

Поле для хранения универсальных уникальных идентификаторов. Использует класс 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) [source]

Связь «многие ко одному». Требует двух позиционных аргументов: класс, к которому относится модель, и опцию 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 [source]

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

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

• PROTECT [source]

  Запрещает удаление связанного объекта, вызывая ProtectedError, подкласс django.db.IntegrityError.

• RESTRICT [source]

  Запрещает удаление связанного объекта, вызывая 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 [source]

  Установить ForeignKey в null; это возможно только если null равно True.

• SET_DEFAULT [source]

  Установить ForeignKey на его значение по умолчанию; значение по умолчанию для ForeignKey должно быть установлено.

• SET() [source]

  Установить 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 [source]

  Не выполнять никаких действий. Если ваш бэкэнд базы данных навязывает целостность ссылок, это приведёт к 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) [source]

Множественная связь «многие ко многим». Требует позиционного аргумента: класс, к которому относится модель, который работает точно так же, как и для 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

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

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

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) [source]

Отношение «один к одному». По сути, это аналогично 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 [source]

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

Таким образом, поле — это фундаментальный элемент различных API Django, в частности, models и querysets.

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

Поле является подклассом 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. Переопределение этого атрибута класса позволяет настраивать поведение get и set.

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

get_internal_type() [source]

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

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

db_type(connection) [source]

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

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

rel_db_type(connection) [source]

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

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

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

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

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

get_prep_value(value) [source]

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

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

get_db_prep_value(value, connection, prepared=False) [source]

Преобразует 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) [source]

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

pre_save(model_instance, add) [source]

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

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

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

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

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

to_python(value) [source]

Преобразует значение в соответствующий объект Python. Он действует как обратное преобразование value_to_string() и также вызывается в clean().

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

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

value_from_object(obj) [source]

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

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

value_to_string(obj) [source]

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

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

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

formfield(form_class=None, choices_form_class=None, **kwargs) [source]

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

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

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

deconstruct() [source]

Возвращает кортеж из 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

Флаг булевого типа, указывающий, скрыто ли поле и не должно ли оно возвращаться методом Options.get_fields() по умолчанию. Пример — обратное поле для ForeignKey с именем поля, начинающимся с '+'.

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). Модель для GenericForeignKey всегда None.