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

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

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.

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)

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

Добавлена поддержка pathlib.Path.

FileField.storage

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

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

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

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

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

FieldFile.name

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

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)

A 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)

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

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 данные представлены в своём собственном формате: словари, списки, строки, числа, булевы значения и None.

JSONField поддерживается в MariaDB 10.2.7+, MySQL 5.7.8+, Oracle, PostgreSQL и SQLite 3.9.0+ (с включенным расширением 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, поле принимает символы 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 для этого.

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

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

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

from django.db import models

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

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

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

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

Разрешено указание symmetrical=True для рекурсивных отношений «многие ко многим» с использованием промежуточной модели.

ManyToManyField.through

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

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

Примечание

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

Примечание

Рекурсивные отношения, использующие промежуточную модель и определенные как симметричные (то есть, с symmetrical=True, что является значением по умолчанию), не могут определить имена обратных аксессоров, так как они будут одинаковыми. Вам нужно установить 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

Новое в Django 3.0.

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

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

get_internal_type()

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

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

db_type(connection)

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

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

rel_db_type(connection)

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

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

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

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

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

get_prep_value(value)

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

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

get_db_prep_value(value, connection, prepared=False)

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

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

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

from_db_value(value, expression, connection)

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

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

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

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

Примечание

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

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

get_db_prep_save(value, connection)

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

pre_save(model_instance, add)

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

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

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

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

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

to_python(value)

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

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

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

value_from_object(obj)

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

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

value_to_string(obj)

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

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

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

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

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

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

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

deconstruct()

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

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

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

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

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