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

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

Последовательность, состоящая из наборов ровно из двух элементов (например, [(A, B), (A, B) ...]), используемая в качестве вариантов для этого поля. Если варианты указаны, они применяются валидацией модели, а виджет формы по умолчанию будет выпадающим списком с этими вариантами вместо стандартного текстового поля.

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

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

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

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' в этом примере).

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

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

Если 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.choices,
        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) парой из двух элементов. См. ниже пример наследования вариантов с использованием более сложного типа данных. Если кортеж не предоставлен или последний элемент не является (ленивой) строкой, label автоматически генерируется из имени члена.
• Добавляется свойство .label к значениям, возвращающее удобочитаемое имя.
• Для классов перечислений добавляется ряд пользовательских свойств — .choices, .labels, .values, и .names — для упрощения доступа к этим отдельным частям перечисления. Используйте .choices в качестве подходящего значения для передачи в choices при определении поля.
• Использование 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.choices)

Также можно использовать функциональный 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_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.

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

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

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

unique

Field.unique

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

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

Этот параметр действителен для всех типов полей, кроме 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

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

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

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

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

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 имеет один дополнительный необязательный аргумент:

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.

Примечание

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

CharField.db_collation

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

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

Примечание

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

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

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

• Для 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 с разрешением 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=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

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

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

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

По умолчанию виджет формы для этого поля — 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 в противном случае.

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

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'.

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

JSONField

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

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

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

JSONField.encoder

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

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

JSONField.decoder

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

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

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

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

NullBooleanField

class NullBooleanField(**options)

Как BooleanField с null=True.

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, поле принимает символы Юникода в дополнение к символам 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

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

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

Примечание

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

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 хранится в типе данных 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

  Новое в Django 3.1.

  Запретить удаление связанного объекта, вызвав 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(), или, если передано вызываемый объект, в результат его вызова. В большинстве случаев для избежания выполнения запросов во время импорта моделей.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 admin.

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

def limit_pub_date_choices():
    return {'pub_date__lte': datetime.date.utcnow()}

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.

limit_choices_to не имеет эффекта, когда используется с ManyToManyField с настроенной промежуточной таблицей, указанной с помощью параметра through.

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

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:

>>> user.supervisor_of
Traceback (most recent call last):
    ...
RelatedObjectDoesNotExist: User has no supervisor_of.

Кроме того, 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"). Все встроенные операции поиска по умолчанию регистрируются по умолчанию.

Все встроенные поля 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 не реализован как no-op для полей, которые этого не требуют (все поля 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 содержит несколько атрибутов, которые позволяют просматривать его поведение. Используйте эти атрибуты вместо проверок 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.