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

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

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

Эти сообщения об ошибках часто не распространяются на формы. Смотрите Учитываемые моменты по отношению к model's 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-специальных символов. Убедитесь, что вы экранируете любой текст помощи, который может исходить от ненадежных пользователей, чтобы избежать атаки типа межсайтового скриптинга.

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

Человекопонятное имя для поля. Если имя не указано, 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.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

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

Примечание

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

Oracle

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

DateField

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

Дата, представленная в Python объектом datetime.date. Имеет несколько дополнительных, необязательных аргументов:

DateField.auto_now

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

Поле обновляется только при вызове Model.save(). Поле не обновляется при внесении изменений в другие поля другими способами, такими как QuerySet.update(), хотя вы можете указать пользовательское значение для поля в таком обновлении.

DateField.auto_now_add

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

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

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

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

DateTimeField

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

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

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

DecimalField

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

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

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

DecimalField.max_digits

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

DecimalField.decimal_places

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

Например, чтобы хранить числа до 999.99 с разрешением 2 десятичных знака, используйте:

models.DecimalField(..., max_digits=5, decimal_places=2)

А для хранения чисел до примерно одного миллиарда с разрешением 10 десятичных знаков:

models.DecimalField(..., max_digits=19, decimal_places=10)

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

DurationField

class DurationField(**options)

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

EmailField

class EmailField(max_length=254, **options)

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

FileField

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

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

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

FileField.upload_to

Это атрибут, позволяющий задать директорию загрузки и имя файла, и может быть задан двумя способами. В обоих случаях значение передаётся методу Storage.save().

Если вы укажете строковое значение или Path, оно может содержать strftime() форматирование, которое будет заменено датой/временем загрузки файла (чтобы загруженные файлы не заполнили заданную директорию). Например:

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to='uploads/')
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

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

upload_to также может быть вызываемым объектом, например, функцией. Это будет вызываться для получения пути загрузки, включая имя файла. Этот вызываемый объект должен принимать два аргумента и возвращать путь в стиле Unix (с косыми чертами) для передачи системе хранения. Два аргумента:

Аргумент	Описание
instance	Экземпляр модели, в которой определён FileField. Более конкретно, это конкретный экземпляр, к которому прикрепляется текущий файл. В большинстве случаев этот объект ещё не сохранён в базе данных, поэтому, если он использует стандартный AutoField, у него может ещё не быть значения для поля первичного ключа.
filename	Имя файла, которое было первоначально дано файлу. Это может быть или не быть учтено при определении конечного пути назначения.

Например:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return 'user_{0}/{1}'.format(instance.user.id, filename)

class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storage

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

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

Использование FileField или ImageField (см. ниже) в модели требует нескольких шагов:

1. В файле настроек вам нужно определить MEDIA_ROOT как полный путь к каталогу, в котором вы хотите, чтобы Django хранил загруженные файлы. (Для повышения производительности эти файлы не хранятся в базе данных.) Определите MEDIA_URL как базовый публичный URL этого каталога. Убедитесь, что этот каталог доступен для записи учетной записью веб-сервера.
2. Добавьте FileField или ImageField в свою модель, определив параметр upload_to для указания подкаталога MEDIA_ROOT для использования загруженных файлов.
3. Всё, что будет храниться в базе данных, — это путь к файлу (относительно MEDIA_ROOT). Скорее всего, вы захотите использовать удобный атрибут url, предоставленный Django. Например, если ваше ImageField называется mug_shot, вы можете получить абсолютный путь к своему изображению в шаблоне с помощью {{ object.mug_shot.url }}.

Например, предположим, что ваш MEDIA_ROOT установлен на '/home/media', а upload_to установлен на 'photos/%Y/%m/%d'. Часть '%Y/%m/%d' в upload_to имеет strftime() форматирование; '%Y' — это четырёхзначный год, '%m' — двузначный месяц, а '%d' — двузначный день. Если вы загрузите файл 15 января 2007 года, он будет сохранён в каталоге /home/media/photos/2007/01/15.

Если вам нужно получить имя файла на диске или размер файла, загруженного на сервер, вы можете использовать атрибуты name и size соответственно. Дополнительную информацию об имеющихся атрибутах и методах см. в справке по классу File и руководстве по теме Управление файлами.

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

Обратите внимание, что при работе с загруженными файлами необходимо тщательно следить за местом загрузки и типом файлов для предотвращения уязвимостей безопасности. Проверяйте все загружаемые файлы, чтобы убедиться, что они такие, как ожидается. Например, если вы бездумно позволите кому-то загружать файлы без проверки в каталог, который находится в корне документа вашего веб-сервера, то кто-то может загрузить скрипт CGI или PHP и выполнить этот скрипт, перейдя по его URL на вашем сайте. Не позволяйте этого делать.

Также обратите внимание, что даже загруженный HTML-файл, поскольку он может быть выполнен браузером (хотя и не сервером), может представлять угрозу безопасности, эквивалентную атакам XSS или CSRF.

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

FileField и FieldFile

class FieldFile

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

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

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

FieldFile.name

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

FieldFile.path

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

FieldFile.size

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

FieldFile.url

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

FieldFile.open(mode='rb')

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

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

FieldFile.close()

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

FieldFile.save(name, content, save=True)

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

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

Обратите внимание, что аргумент content должен быть экземпляром django.core.files.File, а не встроенного объекта файла Python. Вы можете создать File из существующего объекта файла Python так:

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/path/to/hello.world')
myfile = File(f)

Или вы можете создать его из строки Python так:

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

Дополнительная информация в Управление файлами.

FieldFile.delete(save=True)

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

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

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

FilePathField

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

CharField, у которого варианты ограничены именами файлов в определённом каталоге на файловой системе. Имеет некоторые специальные аргументы, первый из которых обязателен:

FilePathField.path

Обязательный. Абсолютный путь к каталогу в файловой системе, из которого этот FilePathField должен получать свои варианты. Пример: "/home/images".

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

import os
from django.conf import settings
from django.db import models

def images_path():
    return os.path.join(settings.LOCAL_FILE_DIR, 'images')

class MyModel(models.Model):
    file = models.FilePathField(path=images_path)

FilePathField.match

Необязательный. Регулярное выражение, как строка, которое FilePathField будет использовать для фильтрации имён файлов. Обратите внимание, что регулярное выражение будет применяться к имени файла, а не к полному пути. Пример: "foo.*\.txt$", который будет соответствовать файлу с именем foo23.txt, но не bar.txt или foo23.png.

FilePathField.recursive

Необязательный. Либо True или False. По умолчанию False. Указывает, должны ли включаться все подкаталоги path

FilePathField.allow_files

Необязательный. Либо True или False. По умолчанию True. Указывает, должны ли включаться файлы в указанном месте. Либо это, либо allow_folders должен быть True.

FilePathField.allow_folders

Необязательный. Либо True или False. По умолчанию False. Указывает, должны ли включаться папки в указанном месте. Либо это, либо allow_files должен быть True.

Единственная потенциальная проблема состоит в том, что match применяется к имени файла, а не к полному пути. Таким образом, этот пример:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…будет соответствовать /home/images/foo.png, но не /home/images/foo/bar.png, потому что match применяется к имени файла (foo.png и bar.png).

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

FloatField

class FloatField(**options)

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

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

GenericIPAddressField

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

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

Нормализация адресов IPv6 соответствует разделу 2.2 спецификации RFC 4291#section-2.2, включая использование формата IPv4, предложенного в пункте 3 этого раздела, например, ::ffff:192.0.2.0. Например, 2001:0::0:01 будет нормализовано до 2001::1, а ::ffff:0a0a:0a0a до ::ffff:10.10.10.10. Все символы преобразуются в нижний регистр.

GenericIPAddressField.protocol

Ограничивает допустимые входные данные указанным протоколом. Допустимые значения: 'both' (по умолчанию), 'IPv4' или 'IPv6'. Сопоставление нечувствительно к регистру.

GenericIPAddressField.unpack_ipv4

Распаковывает адреса IPv4, такие как ::ffff:192.0.2.1. Если этот параметр включен, указанный адрес будет распакован до 192.0.2.1. По умолчанию отключено. Может использоваться только при установке параметра protocol в 'both'.

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

SmallAutoField

class SmallAutoField(**options)

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

SmallIntegerField

class SmallIntegerField(**options)

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

TextField

class TextField(**options)

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

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

TextField.db_collation

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

Примечание

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

Oracle

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

TimeField

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

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

По умолчанию виджет формы для этого поля — TimeInput. В админке добавлены некоторые JavaScript-сокращения.

URLField

class URLField(max_length=200, **options)

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

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

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

UUIDField

class UUIDField(**options)

Поле для хранения универсально уникальных идентификаторов. Использует класс Python UUID. При использовании с PostgreSQL хранится в типе данных uuid, в противном случае в char(32).

Универсально уникальные идентификаторы — хорошая альтернатива AutoField для primary_key. База данных не генерирует UUID для вас, поэтому рекомендуется использовать default:

import uuid
from django.db import models

class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

Обратите внимание, что вызываемый объект (без скобок) передаётся в default, а не экземпляр UUID.

Связанные поля

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

ForeignKey

class ForeignKey(to, on_delete, **options)

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

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

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

from django.db import models

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

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

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

from django.db import models

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

    class Meta:
        abstract = True

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

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

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

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

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

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

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

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

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

Аргументы

ForeignKey принимает другие аргументы, определяющие детали работы взаимосвязи.

ForeignKey.on_delete

Когда объект, на который ссылается ForeignKey, удаляется, Django эмулирует поведение SQL-ограничения, указанного аргументом on_delete. Например, если у вас есть необязательный ForeignKey и вы хотите установить его в null при удалении связанного объекта:

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

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

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

• CASCADE

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

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

• PROTECT

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

• RESTRICT

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

  Рассмотрим следующую группу моделей:

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

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

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

• SET_NULL

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

• SET_DEFAULT

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

• SET()

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

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

• DO_NOTHING

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

ForeignKey.limit_choices_to

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

Например:

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

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

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

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

limit_choices_to = limit_pub_date_choices

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

Примечание

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

ForeignKey.related_name

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

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

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

ForeignKey.related_query_name

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

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

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

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

ForeignKey.to_field

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

ForeignKey.db_constraint

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

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

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

ForeignKey.swappable

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

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

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

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

ManyToManyField

class ManyToManyField(to, **options)

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

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

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

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

Аргументы

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

ManyToManyField.related_name

То же, что и ForeignKey.related_name.

ManyToManyField.related_query_name

То же, что и ForeignKey.related_query_name.

ManyToManyField.limit_choices_to

То же, что и ForeignKey.limit_choices_to.

ManyToManyField.symmetrical

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

from django.db import models

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

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

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

ManyToManyField.through

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

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

Примечание

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

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

get_internal_type()

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

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

db_type(connection)

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

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

rel_db_type(connection)

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

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

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

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

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

get_prep_value(value)

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

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

get_db_prep_value(value, connection, prepared=False)

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

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

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

from_db_value(value, expression, connection)

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

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

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

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

Примечание

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

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

get_db_prep_save(value, connection)

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

pre_save(model_instance, add)

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

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

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

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

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

to_python(value)

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

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

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

value_from_object(obj)

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

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

value_to_string(obj)

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

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

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

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

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

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

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

deconstruct()

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

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

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

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

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

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

Field.auto_created

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

Field.concrete

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

Field.hidden

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

Примечание

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

Field.is_relation

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

Field.model

Возвращает модель, в которой определено поле. Если поле определено в суперклассе модели, model будет ссылаться на суперкласс, а не на класс экземпляра.

Атрибуты для полей с отношениями

Эти атрибуты используются для запроса кардинальности и других подробностей отношения. Эти атрибуты присутствуют во всех полях, однако они будут иметь только булевые значения (а не None) если поле является типом отношения (Field.is_relation=True).

Field.many_to_many

Флаг булевого типа, который является True если поле имеет отношение «многие ко многим»; False в противном случае. Единственное поле в Django, где это True - это ManyToManyField.

Field.many_to_one

Флаг булевого типа, который является True если поле имеет отношение «многие к одному», например, ForeignKey; False в противном случае.

Field.one_to_many

Флаг булевого типа, который является True если поле имеет отношение «один ко многим», например, GenericRelation или обратное ForeignKey; False в противном случае.

Field.one_to_one

Флаг булевого типа, который является True если поле имеет отношение «один к одному», например, OneToOneField; False в противном случае.

Field.related_model

Указывает на модель, к которой относится поле. Например, Author в ForeignKey(Author, on_delete=models.CASCADE). related_model для GenericForeignKey всегда None.