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

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

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

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, метод 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

Человекопонятное имя для поля. Если имя verbose name не задано, Django автоматически создаст его, используя имя атрибута поля, преобразуя символы нижнего подчеркивания в пробелы. Смотрите Имена полей verbose name.

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

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

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

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

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

DateTimeField

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

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

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

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)

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

Имеет два обязательных аргумента:

DecimalField.max_digits

Максимальное количество цифр, разрешенных в числе. Обратите внимание, что это число должно быть больше или равно decimal_places.

DecimalField.decimal_places

Количество десятичных знаков для хранения в числе.

Например, для хранения чисел до 999 с разрешением 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

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

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

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

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

ImageField

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)

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

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

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

ImageField.height_field

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

ImageField.width_field

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

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

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

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

IntegerField

class IntegerField(**options)

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

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

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

JSONField

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

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

PositiveBigIntegerField

class PositiveBigIntegerField(**options)

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

PositiveIntegerField

class PositiveIntegerField(**options)

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options)

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

SlugField

class SlugField(max_length=50, **options)

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

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

Подразумевается установка Field.db_index в True.

Часто полезно автоматически заполнять SlugField на основе значения другого поля. Это можно сделать автоматически в админке, используя prepopulated_fields.

Использует validate_slug или validate_unicode_slug для валидации.

SlugField.allow_unicode

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

SmallAutoField

class SmallAutoField(**options)

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

SmallIntegerField

class SmallIntegerField(**options)

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

TextField

class TextField(**options)

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

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

TextField.db_collation

Новое в 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, и вы хотите установить значение null, когда удаляется связанный объект:

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

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

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

• CASCADE

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

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

• PROTECT

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

• RESTRICT

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

  Рассмотрим набор моделей:

  class Artist(models.Model):
      name = models.CharField(max_length=10)
  
  class Album(models.Model):
      artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
  
  class Song(models.Model):
      artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
      album = models.ForeignKey(Album, on_delete=models.RESTRICT)
  

  Artist можно удалить, даже если это подразумевает удаление Album, на который ссылается Song, потому что Song также ссылается на Artist через каскадное отношение. Например:

  >>> artist_one = Artist.objects.create(name='artist one')
  >>> artist_two = Artist.objects.create(name='artist two')
  >>> album_one = Album.objects.create(artist=artist_one)
  >>> album_two = Album.objects.create(artist=artist_two)
  >>> song_one = Song.objects.create(artist=artist_one, album=album_one)
  >>> song_two = Song.objects.create(artist=artist_one, album=album_two)
  >>> album_one.delete()
  # Raises RestrictedError.
  >>> artist_two.delete()
  # Raises RestrictedError.
  >>> artist_one.delete()
  (4, {'Song': 2, 'Album': 1, 'Artist': 1})
  

• SET_NULL

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

• SET_DEFAULT

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

• SET()

  Установить ForeignKey на значение, переданное в SET(), или, если передана вызываемая функция, на результат ее вызова. В большинстве случаев потребуется передавать вызываемую функцию, чтобы избежать выполнения запросов во время импорта вашего файла models.py:

  from django.conf import settings
  from django.contrib.auth import get_user_model
  from django.db import models
  
  def get_sentinel_user():
      return get_user_model().objects.get_or_create(username='deleted')[0]
  
  class MyModel(models.Model):
      user = models.ForeignKey(
          settings.AUTH_USER_MODEL,
          on_delete=models.SET(get_sentinel_user),
      )
  

• DO_NOTHING

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

ForeignKey.limit_choices_to

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

Например:

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

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

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

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

limit_choices_to = limit_pub_date_choices

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

Примечание

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

ForeignKey.related_name

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

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

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

ForeignKey.related_query_name

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

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

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

Как и related_name, related_query_name поддерживает интерполяцию имени приложения и класса через определенный синтаксис.

ForeignKey.to_field

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

ForeignKey.db_constraint

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

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

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

ForeignKey.swappable

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

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

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

В случае сомнений оставьте значение по умолчанию True.

ManyToManyField

class ManyToManyField(to, **options)

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

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

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

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

Аргументы

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

ManyToManyField.related_name

Аналогично ForeignKey.related_name.

ManyToManyField.related_query_name

Аналогично ForeignKey.related_query_name.

ManyToManyField.limit_choices_to

Аналогично ForeignKey.limit_choices_to.

ManyToManyField.symmetrical

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

from django.db import models

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

Когда Django обрабатывает эту модель, он определяет, что у неё есть ManyToManyField на себя, и в результате не добавляет атрибут person_set к классу Person. Вместо этого ManyToManyField предполагается симметричным — то есть, если я твой друг, значит ты мой друг.

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

ManyToManyField.through

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

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

Примечание

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

Примечание

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

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

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

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

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

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

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

Model.m2mfield.through.objects.all()

ManyToManyField.through_fields

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

from django.db import models

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

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

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

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

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

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

Однозначное отношение. По концепции, это аналогично 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. Переопределение этого атрибута класса позволяет настраивать поведение получения и установки.

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

get_internal_type()

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

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

db_type(connection)

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

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

rel_db_type(connection)

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

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

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

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

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

get_prep_value(value)

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

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

get_db_prep_value(value, connection, prepared=False)

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

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

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

from_db_value(value, expression, connection)

Преобразует значение, возвращенное базой данных, в объект Python. Это обратное преобразование к get_prep_value().

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

expression эквивалентно self.

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

Примечание

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

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

get_db_prep_save(value, connection)

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

pre_save(model_instance, add)

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

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

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

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

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

to_python(value)

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

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

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

value_from_object(obj)

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

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

value_to_string(obj)

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

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

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

formfield(form_class=None, choices_form_class=None, **kwargs)

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

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

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

deconstruct()

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

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

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

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

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