null¶

Field.null¶

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

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

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

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

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

Вы также можете передать sequence, состоящий из итераций ровно из двух элементов (например, [(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" в данном примере).

Вы также можете использовать последовательность, например, список из двух кортежей:

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, особенно дефис, то это нормально. За кулисами Джанго цитирует имена столбцов и таблиц.

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

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

editable¶

Field.editable¶

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

error_messages¶

Field.error_messages¶

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

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

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

help_text¶

Field.help_text¶

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

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

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

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

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, то будет вызвано исключение 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¶

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

AutoField¶

class AutoField(**options)[исходный код]¶

IntegerField, который автоматически увеличивается в соответствии с доступными идентификаторами. Вам обычно не нужно использовать это напрямую; поле первичного ключа будет автоматически добавлено в вашу модель, если вы не укажете иное. Смотрите: ref: automatic-primary-key-fields.

BigAutoField¶

class BigAutoField(**options)[исходный код]¶

64-разрядное целое число, очень похожее на AutoField, за исключением того, что оно гарантированно соответствует числам от 1 до 9223372036854775807.

BigIntegerField¶

class BigIntegerField(**options)[исходный код]¶

64-разрядное целое число, очень похожее на IntegerField, за исключением того, что оно гарантированно соответствует числам от -9223372036854775808 до 9223372036854775807. Виджет формы по умолчанию для этого поля TextInput.

BinaryField¶

class BinaryField(max_length=None, **options)[исходный код]¶

Поле для хранения необработанных двоичных данных. Может быть назначено bytes, bytearray или memoryview.

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

BinaryField.max_length¶

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

BooleanField¶

class BooleanField(**options)[исходный код]¶

Поле истина/ложь.

Виджет формы по умолчанию для этого поля CheckboxInput или NullBooleanSelect если null=True.

Значение по умолчанию BooleanField равно None, когда Field.default не определено.

CharField¶

class CharField(max_length=None, **options)[исходный код]¶

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

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

Виджет формы по умолчанию для этого поля TextInput.

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

CharField.max_length¶

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

Примечание

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

Changed in Django 4.2:

В PostgreSQL добавлена поддержка неограниченного количества столбцов VARCHAR.

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

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

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

DateTimeField¶

class DateTimeField(auto_now=False, auto_now_add=False, **options)[исходный код]¶

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

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

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

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

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

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

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)

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

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

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

FloatField¶

class FloatField(**options)[исходный код]¶

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

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

GeneratedField¶

class GeneratedField(expression, output_field, db_persist=None, **kwargs)¶

Поле, которое всегда вычисляется на основе других полей в модели. Это поле управляется и обновляется самой базой данных. Использует синтаксис GENERATED ALWAYS SQL.

Существует два вида генерируемых столбцов: хранимые и виртуальные. Хранимый генерируемый столбец вычисляется при записи (вставке или обновлении) и занимает место в памяти, как если бы это был обычный столбец. Виртуальный генерируемый столбец не занимает места в памяти и вычисляется при чтении. Таким образом, виртуальный генерируемый столбец похож на представление, а хранимый генерируемый столбец - на материализованное представление.

GeneratedField.expression¶

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

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

GeneratedField.output_field¶

Экземпляр поля модели для определения типа данных поля.

GeneratedField.db_persist¶

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

PostgreSQL поддерживает только сохраняемые столбцы. Oracle поддерживает только виртуальные колонки.

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

JSONField поддерживается в MariaDB, MySQL, Oracle, PostgreSQL и SQLite (с JSON1 extension enabled).

JSONField.encoder¶

Необязательный подкласс json.JSONEncoder для сериализации типов данных, не поддерживаемых стандартным сериализатором JSON (например, datetime.datetime или UUID). Например, вы можете использовать класс DjangoJSONEncoder.

По умолчанию используется json.JSONEncoder.

JSONField.decoder¶

Необязательный подкласс json.JSONDecoder для десериализации значения, полученного из базы данных. Значение будет в формате, выбранном пользовательским кодировщиком (чаще всего это строка). Ваша десериализация, возможно, должна учитывать тот факт, что вы не можете быть уверены в типе ввода. Например, вы рискуете вернуть datetime, который на самом деле был строкой в том же формате, который выбран для datetime.

По умолчанию используется json.JSONDencoder.

Чтобы запросить JSONField в базе данных, смотрите Запросы к JSONField.

PositiveBigIntegerField¶

class PositiveBigIntegerField(**options)[исходный код]¶

Как a: class: 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)[исходный код]¶

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

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

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

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

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

SlugField.allow_unicode¶

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

SmallAutoField¶

class SmallAutoField(**options)[исходный код]¶

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

SmallIntegerField¶

class SmallIntegerField(**options)[исходный код]¶

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

TextField¶

class TextField(**options)[исходный код]¶

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

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

TextField.db_collation¶

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

Примечание

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

Oracle

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

TimeField¶

class TimeField(auto_now=False, auto_now_add=False, **options)[исходный код]¶

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

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

URLField¶

class URLField(max_length=200, **options)[исходный код]¶

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

Виджет формы по умолчанию для этого поля TextInput.

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

UUIDField¶

class UUIDField(**options)[исходный код]¶

Поле для хранения универсальных уникальных идентификаторов. Использует класс 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)[исходный код]¶

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

ManyToManyField¶

class ManyToManyField(to, **options)[исходный код]¶

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

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

OneToOneField¶

class OneToOneField(to, on_delete, parent_link=False, **options)[исходный код]¶

Отношения один-к-одному. Концептуально это похоже на ForeignKey с :attr:`unique=True <Field.unique> `, но «обратная» сторона отношения будет напрямую возвращать один объект.

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

Требуется один позиционный аргумент: класс, с которым будет связана модель. Это работает точно так же, как и для 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 и используется в модели, которая наследуется от другого concrete model, указывает, что это поле следует использовать как ссылку на родительский класс, а не как дополнительное OneToOneField, которое обычно неявно создается путем создания подклассов.

Смотрите Отношения один-к-одному для примеров использования OneToOneField.