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

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

>>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
>>> MedalType.choices
[('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')]
>>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD")
>>> Place.choices
[(1, 'First'), (2, 'Second'), (3, 'Third')]

Если вам требуется поддержка конкретного типа данных, отличного от int или str, вы можете наследоваться от Choices и требуемого конкретного типа данных, например, date для использования с DateField:

class MoonLandings(datetime.date, models.Choices):
    APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)"
    APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)"
    APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)"
    APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)"
    APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)"
    APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)"

Существуют дополнительные моменты, о которых следует знать:

• Типы перечислений не поддерживают именованные группы.

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

  class Answer(models.IntegerChoices):
      NO = 0, _("No")
      YES = 1, _("Yes")
  
      __empty__ = _("(Unknown)")
  

db_column

Field.db_column

Имя столбца базы данных для этого поля. Если оно не указано, Django будет использовать имя поля.

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

db_comment

Field.db_comment

Комментарий к столбцу базы данных для этого поля. Это полезно для документирования полей для людей, имеющих прямой доступ к базе данных, которые могут не просматривать ваш код Django. Например:

pub_date = models.DateTimeField(
    db_comment="Date and time when the article was published",
)

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

primary_key

Field.primary_key

Если True, это поле является первичным ключом для модели.

Если вы не укажете primary_key=True для любого поля в вашей модели, Django автоматически добавит поле для хранения первичного ключа, поэтому вам не нужно устанавливать primary_key=True ни для одного из ваших полей, если вы не хотите переопределить поведение первичного ключа по умолчанию. Тип автоматически создаваемых полей первичного ключа может быть задан по приложению в AppConfig.default_auto_field или глобально в настройке DEFAULT_AUTO_FIELD. Для получения дополнительной информации, см. Автоматически создаваемые поля первичного ключа.

primary_key=True подразумевает null=False и unique=True. Допускается только один первичный ключ в объекте.

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

Поле первичного ключа устанавливается в значение None при deleting объекта.

unique

Field.unique

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

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

Этот параметр допустим для всех типов полей, кроме ManyToManyField и OneToOneField.

Обратите внимание, что когда unique является True, вам не нужно указывать db_index, потому что unique подразумевает создание индекса.

unique_for_date

Field.unique_for_date

Установите это значение в имя DateField или DateTimeField, чтобы потребовать, чтобы это поле было уникальным для значения поля даты.

Например, если у вас есть поле title, которое имеет unique_for_date="pub_date", то Django не позволит ввести две записи с одинаковой title и pub_date.

Обратите внимание, что если вы зададите это значение для DateTimeField, будет рассмотрена только дата части поля. Кроме того, когда USE_TZ равняется True, проверка будет выполнена в текущей часовой зоне в момент сохранения объекта.

Это обеспечивается Model.validate_unique() во время проверки модели, но не на уровне базы данных. Если какое-либо ограничение unique_for_date включает поля, которые не являются частью ModelForm (например, если одно из полей указано в exclude или имеет editable=False), Model.validate_unique() пропустит проверку для этого конкретного ограничения.

unique_for_month

Field.unique_for_month

Как и unique_for_date, но требует, чтобы поле было уникальным по отношению к месяцу.

unique_for_year

Field.unique_for_year

Как unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

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

validators

Field.validators

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

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

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)

Поле true/false.

Стандартный виджет формы для этого поля — 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. Он необходим для всех бэкэндов баз данных, включенных в Django, за исключением PostgreSQL, который поддерживает колонки с неограниченной VARCHAR.

Примечание

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

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

Добавлена поддержка колонок с неограниченной VARCHAR в PostgreSQL.

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

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

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

FieldFile.name

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

FieldFile.path

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

FieldFile.size

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

FieldFile.url

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

FieldFile.open(mode='rb')

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

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

FieldFile.close()

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

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

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

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

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

from django.core.files import File

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

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

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

Дополнительную информацию см. в разделе Управление файлами.

FieldFile.delete(save=True)

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

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

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

FilePathField

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

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

FilePathField.path

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

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

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


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


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

FilePathField.match

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

FilePathField.recursive

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

FilePathField.allow_files

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

FilePathField.allow_folders

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

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

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

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

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

FloatField

class FloatField(**options)

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

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

GenericIPAddressField

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

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

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

GenericIPAddressField.protocol

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

GenericIPAddressField.unpack_ipv4

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

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

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, 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-ограничение на поле базы данных.

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

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

ManyToManyField

class ManyToManyField(to, **options)

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

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

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

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

Аргументы

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

ManyToManyField.related_name

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

ManyToManyField.related_query_name

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

ManyToManyField.limit_choices_to

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

ManyToManyField.symmetrical

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

from django.db import models


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

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

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

ManyToManyField.through

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

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

Примечание

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

Примечание

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

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

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

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

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

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

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

Model.m2mfield.through.objects.all()

ManyToManyField.through_fields

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

from django.db import models


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


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


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

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

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

Когда у вас есть более одного внешнего ключа в модели посредника к любой (или даже обеим) из моделей, участвующих в связи многие-ко-многим, вы должны указать through_fields. Это также относится к рекурсивным отношениям, когда используется промежуточная модель и есть более двух внешних ключей к модели, или вы хотите явно указать, какие два Django должен использовать.

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

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

Ошибка передать и db_constraint, и through.

ManyToManyField.swappable

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

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

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

ManyToManyField не поддерживает validators.

null не имеет эффекта, так как нет способа потребовать отношения на уровне базы данных.

OneToOneField

class OneToOneField(to, on_delete, parent_link=False, **options)

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

Это наиболее полезно в качестве первичного ключа модели, которая «расширяет» другую модель каким-либо образом; Наследование с несколькими таблицами реализуется путем добавления неявной связи один-к-одному от дочерней модели к родительской модели, например.

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

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

В следующем примере:

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


class MySpecialUser(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="supervisor_of",
    )

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

>>> user = User.objects.get(pk=1)
>>> hasattr(user, "myspecialuser")
True
>>> hasattr(user, "supervisor_of")
True

Исключение RelatedObjectDoesNotExist генерируется при обращении к обратной связи, если запись в связанной таблице отсутствует. Это подкласс исключения Model.DoesNotExist целевой модели и может быть получен как атрибут обратного доступа. Например, если у пользователя нет назначенного руководителя, указанного MySpecialUser:

try:
    user.supervisor_of
except User.supervisor_of.RelatedObjectDoesNotExist:
    pass

Кроме того, 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 использует для сопоставления значения поля со значениями, специфичными для базы данных.

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

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

Каждый экземпляр 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 или обратное отношению «многие к одному»; False в противном случае.

Field.one_to_one

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

Field.related_model

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