null

Field.null

Если True, Django будет сохранять пустые значения как NULL в базе данных. Значение по умолчанию — False.

Избегайте использования null для строковых полей, таких как CharField и TextField. Конвенция Django заключается в использовании пустой строки, а не NULL, в качестве состояния «нет данных» для строковых полей. Если строковое поле имеет null=False, пустые строки всё равно могут сохраняться для «нет данных». Если строковое поле имеет null=True, это означает, что у него есть два возможных значения для «нет данных»: 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 [source]

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

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

YEAR_IN_SCHOOL_CHOICES = {
    "FR": "Freshman",
    "SO": "Sophomore",
    "JR": "Junior",
    "SR": "Senior",
    "GR": "Graduate",
}

Также можно передать последовательность, состоящую из итерируемых объектов ровно из двух элементов (например, [(A1, B1), (A2, B2), …]). Первый элемент в каждой кортеже — фактическое значение, которое будет установлено в модели, а второй — читаемое пользователем имя. Например:

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

choices также может быть определён как вызываемый объект, не принимающий аргументов и возвращающий любой из описанных выше форматов. Например:

def get_currencies():
    return {i: i for i in settings.CURRENCIES}


class Expense(models.Model):
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    currency = models.CharField(max_length=3, choices=get_currencies)

Передача вызываемого объекта для choices особенно полезна, когда, например, варианты являются:

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

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

from django.db import models


class Student(models.Model):
    FRESHMAN = "FR"
    SOPHOMORE = "SO"
    JUNIOR = "JR"
    SENIOR = "SR"
    GRADUATE = "GR"
    YEAR_IN_SCHOOL_CHOICES = {
        FRESHMAN: "Freshman",
        SOPHOMORE: "Sophomore",
        JUNIOR: "Junior",
        SENIOR: "Senior",
        GRADUATE: "Graduate",
    }
    year_in_school = models.CharField(
        max_length=2,
        choices=YEAR_IN_SCHOOL_CHOICES,
        default=FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {self.JUNIOR, self.SENIOR}

Хотя вы можете определить список вариантов вне класса модели, а затем на него сослаться, определение вариантов и названий для каждого варианта внутри класса модели сохраняет всю эту информацию в классе, который его использует, и помогает сослаться на варианты (например, Student.SOPHOMORE будет работать везде, где модель Student была импортирована).

Также можно объединять доступные варианты в именованные группы для организационных целей:

MEDIA_CHOICES = {
    "Audio": {
        "vinyl": "Vinyl",
        "cd": "CD",
    },
    "Video": {
        "vhs": "VHS Tape",
        "dvd": "DVD",
    },
    "unknown": "Unknown",
}

Ключом сопоставления является имя, применяемое к группе, а значением — варианты внутри этой группы, состоящие из значения поля и читаемого пользователем имени для варианта. Группированные варианты могут сочетаться с негруппированными вариантами в одном сопоставлении (например, вариант "unknown" в этом примере).

Также можно использовать последовательность, например, список кортежей из 2 элементов:

MEDIA_CHOICES = [
    (
        "Audio",
        (
            ("vinyl", "Vinyl"),
            ("cd", "CD"),
        ),
    ),
    (
        "Video",
        (
            ("vhs", "VHS Tape"),
            ("dvd", "DVD"),
        ),
    ),
    ("unknown", "Unknown"),
]

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

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

Если blank=False установлено для поля вместе с default, то будет отображаться метка, содержащая "---------", вместе с выпадающим списком. Чтобы переопределить это поведение, добавьте кортеж в choices, содержащий None; например, (None, 'Your String For Display'). В качестве альтернативы, вы можете использовать пустую строку вместо None, где это имеет смысл — например, в CharField.

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,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

>>> class Vehicle(models.TextChoices):
...     CAR = "C"
...     TRUCK = "T"
...     JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

class Card(models.Model):
    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit)

>>> 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')]

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

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_default

Field.db_default

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

created = models.DateTimeField(db_default=Now())

Можно использовать более сложные выражения, если они составлены из литералов и функций базы данных:

month_due = models.DateField(
    db_default=TruncMonth(
        Now() + timedelta(days=90),
        output_field=models.DateField(),
    )
)

Значения по умолчанию базы данных не могут ссылаться на другие поля или модели. Например, это некорректно:

end = models.IntegerField(db_default=F("start") + 50)

Если оба db_default и Field.default установлены, default будет иметь приоритет при создании экземпляров в коде Python. db_default всё ещё будет установлено на уровне базы данных и будет использоваться при вставке строк вне ORM или при добавлении нового поля в миграцию.

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

db_index

Field.db_index

Если True, для этого поля будет создан индекс базы данных.

db_tablespace

Field.db_tablespace [source]

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

Значение по умолчанию также может быть установлено на уровне базы данных с помощью Field.db_default.

editable

Field.editable

Если False, поле не будет отображаться в админке или других ModelForm. Оно также будет пропущено при валидации модели. По умолчанию True.

error_messages

Field.error_messages [source]

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

Ключи сообщений об ошибках включают null, blank, invalid, invalid_choice, unique и unique_for_date. Дополнительные ключи сообщений об ошибках указаны для каждого поля в разделе Типы полей ниже.

Эти сообщения об ошибках часто не распространяются на формы. См. Рекомендации относительно model’s error_messages.

help_text

Field.help_text

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

Обратите внимание, что это значение не экранируется в автоматически сгенерированных формах. Это позволяет включать HTML в help_text, если нужно. Например:

help_text = "Please use the following format: <em>YYYY-MM-DD</em>."

В качестве альтернативы можно использовать обычный текст и django.utils.html.escape(), чтобы экранировать любые специальные символы HTML. Убедитесь, что вы экранируете любой текст помощи, который может поступать от ненадежных пользователей, чтобы избежать атаки типа XSS.

primary_key

Field.primary_key

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

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

primary_key=True подразумевает null=False и unique=True. Только одно поле в модели может установить primary_key=True. Составные первичные ключи должны быть определены с помощью CompositePrimaryKey вместо установки этого флага в True для всех полей, чтобы сохранить это условие.

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

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

unique

Field.unique [source]

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

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

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

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

unique_for_date

Field.unique_for_date

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

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

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

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

unique_for_month

Field.unique_for_month

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

unique_for_year

Field.unique_for_year

Аналогично unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

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

validators

Field.validators [source]

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

AutoField

class AutoField(**options) [source]

Поле IntegerField, которое автоматически увеличивается в соответствии с доступными идентификаторами. Обычно вам не нужно использовать его напрямую; поле первичного ключа автоматически добавляется в вашу модель, если вы не укажете иначе. См. Автоматические поля первичного ключа.

BigAutoField

class BigAutoField(**options) [source]

64-битное целое число, аналогичное AutoField, но гарантированно вмещает числа от 1 до 9223372036854775807.

BigIntegerField

class BigIntegerField(**options) [source]

64-битное целое число, аналогичное IntegerField, но гарантированно вмещает числа от -9223372036854775808 до 9223372036854775807. Поле по умолчанию представлено виджетом NumberInput.

BinaryField

class BinaryField(max_length=None, **options) [source]

Поле для хранения данных в бинарном формате. Ему можно присвоить bytes, bytearray или memoryview.

По умолчанию, BinaryField устанавливает editable в False, в этом случае оно не может быть включено в ModelForm.

BinaryField.max_length

Необязательно. Максимальная длина (в байтах) поля. Максимальная длина проверяется в Django с помощью MaxLengthValidator.

BooleanField

class BooleanField(**options) [source]

Поле true/false.

Поле по умолчанию представлено виджетом CheckboxInput или NullBooleanSelect, если null=True.

Значение по умолчанию для BooleanField — None, если Field.default не определено.

CompositePrimaryKey

class CompositePrimaryKey(*field_names, **options) [source]

Виртуальное поле, используемое для определения составного первичного ключа.

Это поле должно быть определено как атрибут pk модели. Если оно присутствует, Django создаст базу данных модели с составным первичным ключом.

Аргумент *field_names — список позиционных имён полей, составляющих первичный ключ.

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

CharField

class CharField(max_length=None, **options) [source]

Строковое поле для строк малого и большого размера.

Для больших объёмов текста используйте TextField.

Поле по умолчанию представлено виджетом TextInput.

CharField имеет следующие дополнительные аргументы:

CharField.max_length

Максимальная длина (в символах) поля. Максимальная длина проверяется на уровне базы данных и в валидации Django с помощью MaxLengthValidator. Она требуется для всех баз данных, поставляемых с Django, кроме PostgreSQL и SQLite, которые поддерживают столбцы неограниченной длины VARCHAR.

Примечание

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

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

Добавлена поддержка столбцов неограниченной длины VARCHAR для SQLite.

CharField.db_collation

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

Примечание

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

Oracle

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

DateField

class DateField(auto_now=False, auto_now_add=False, **options) [source]

Дата, представленная в 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) [source]

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

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

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options) [source]

Десятичное число с фиксированной точностью, представленное в 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) [source]

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

EmailField

class EmailField(max_length=254, **options) [source]

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

FileField

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

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

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

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.

FilePathField

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

A CharField whose choices are limited to the filenames in a certain directory on the file system. Has some special arguments, of which the first is required:

FilePathField.path

Required. The absolute file system path to a directory from which this FilePathField should get its choices. Example: "/home/images".

path may also be a callable, such as a function to dynamically set the path at runtime. Example:

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

Optional. A regular expression, as a string, that FilePathField will use to filter filenames. Note that the regex will be applied to the base filename, not the full path. Example: "foo.*\.txt$", which will match a file called foo23.txt but not bar.txt or foo23.png.

FilePathField.recursive

Optional. Either True or False. Default is False. Specifies whether all subdirectories of path should be included

FilePathField.allow_files

Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.

FilePathField.allow_folders

Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or allow_files must be True.

The one potential gotcha is that match applies to the base filename, not the full path. So, this example:

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

…will match /home/images/foo.png but not /home/images/foo/bar.png because the match applies to the base filename (foo.png and bar.png).

FilePathField instances are created in your database as varchar columns with a default maximum length of 100 characters. As with other fields, you can change the maximum length using the max_length argument.

FloatField

class FloatField(**options) [source]

A floating-point number represented in Python by a float instance.

The default form widget for this field is a NumberInput when localize is False or TextInput otherwise.

GeneratedField

class GeneratedField(expression, output_field, db_persist=None, **kwargs) [source]

A field that is always computed based on other fields in the model. This field is managed and updated by the database itself. Uses the GENERATED ALWAYS SQL syntax.

There are two kinds of generated columns: stored and virtual. A stored generated column is computed when it is written (inserted or updated) and occupies storage as if it were a regular column. A virtual generated column occupies no storage and is computed when it is read. Thus, a virtual generated column is similar to a view and a stored generated column is similar to a materialized view.

GeneratedField.expression

An Expression used by the database to automatically set the field value each time the model is changed.

The expressions should be deterministic and only reference fields within the model (in the same database table). Generated fields cannot reference other generated fields. Database backends can impose further restrictions.

GeneratedField.output_field

A model field instance to define the field’s data type.

GeneratedField.db_persist

Determines if the database column should occupy storage as if it were a real column. If False, the column acts as a virtual column and does not occupy database storage space.

PostgreSQL only supports persisted columns. Oracle only supports virtual columns.

GenericIPAddressField

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

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

Нормализация адресов IPv6 следует RFC 4291 Раздел 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) [source]

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

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

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

ImageField.height_field

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

ImageField.width_field

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

Требует библиотеку pillow.

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

По умолчанию для этого поля используется виджет ClearableFileInput.

IntegerField

class IntegerField(**options) [source]

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

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

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

JSONField

class JSONField(encoder=None, decoder=None, **options) [source]

Поле для хранения данных, закодированных в формате JSON. В Python данные представлены в собственном формате 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.

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

PositiveBigIntegerField

class PositiveBigIntegerField(**options) [source]

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

PositiveIntegerField

class PositiveIntegerField(**options) [source]

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options) [source]

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

SlugField

class SlugField(max_length=50, **options) [source]

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

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

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

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

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

SlugField.allow_unicode

Если True, поле принимает Unicode-символы помимо ASCII. Значение по умолчанию — False.

SmallAutoField

class SmallAutoField(**options) [source]

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

SmallIntegerField

class SmallIntegerField(**options) [source]

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

TextField

class TextField(**options) [source]

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

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

TextField.db_collation

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

Примечание

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

Oracle

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

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options) [source]

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

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

URLField

class URLField(max_length=200, **options) [source]

A CharField для URL, проверенный с помощью URLValidator.

По умолчанию для этого поля используется виджет URLInput.

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

UUIDField

class UUIDField(**options) [source]

Поле для хранения универсальных идентификаторов. Использует класс Python UUID. При использовании с PostgreSQL и MariaDB 10.7+, хранится в типе данных 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.

ForeignKey

class ForeignKey(to, on_delete, **options) [source]

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

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()


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

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

Подробности о втором позиционном аргументе см. в ForeignKey.on_delete.

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

ManyToManyField

class ManyToManyField(to, **options) [source]

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

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

OneToOneField

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

Связь один-к-одному. По сути, она похожа на 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.

Ленивые связи

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

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

from django.db import models


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


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

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):
    name = models.TextField()


class Car(AbstractCar):
    pass

class Car(models.Model):
    manufacturer = models.ForeignKey(
        "thirdpartyapp.Manufacturer",
        on_delete=models.CASCADE,
    )