null¶

Field.null¶

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

Избегайте использования null для строковых полей таких, как CharField и TextField, т.к. пустое значение всегда будет сохранено как пустая строка, а не NULL. Если строковое поле содержит null=True, это означает, что оно может содержать два возможных «пустых» значения: NULL и пустую строку. В большинстве случаев избыточно иметь два варианты «пустых» значений. Правило Django использовать пустую строку, вместо NULL.

Для всех типов полей, вы также должны указать blank=True если вы хотите разрешить пустые значения в формах, т.к. параметр null влияет только на сохранение в базе данных (смотрите blank).

blank¶

Field.blank¶

При True поле может быть пустым. Значение по умолчанию – False.

Заметим что этот параметр отличается от null. null указывается для базы данных, в то время как blank – для проверки данных. При blank=True, проверка данных в форме позволит сохранять пустое значение в поле. При blank=False поле будет обязательным.

choices¶

Field.choices¶

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

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

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)

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

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

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

Значения лучше указать в константах внутри модели:

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-кортежей:

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

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

Для каждого поля модели, у которого установлен choices, Django нормализует варианты выбора в список из двух кортежей и добавит метод для получения удобочитаемого имени для текущего значения поля. См. 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¶

Имя «tablespace» базы данных используемое для индекса поля, если поле имеет индекс. По-умолчанию используется значение настройки DEFAULT_INDEX_TABLESPACE проекта, если оно указано, иначе db_tablespace модели. Если база данных не поддерживает «tablespace» для индексов, этот параметр будет проигнорирован.

default¶

Field.default¶

Значение по умолчанию для поля. Это может быть значение или вызываемый(callable) объект. Если это вызываемый объект, он будет вызван при создании нового объекта.

Значение по умолчанию не может быть изменяемым объектом (экземпляр модели, «список», «набор» и т. д.), поскольку ссылка на один и тот же экземпляр этого объекта будет использоваться в качестве значения по умолчанию во всех новых экземплярах модели. Вместо этого оберните желаемое значение по умолчанию в вызываемый объект. Например, если вы хотите указать 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. Он также будет пропущен во время проверки модели <validating-objects>`. По умолчанию установлено True.

error_messages¶

Field.error_messages¶

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

Ключи ошибок такие: null, blank, invalid, invalid_choice, unique и ``unique_for_date`. Дополнительные ошибки указаны для каждого типа поля ниже.

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

help_text¶

Field.help_text¶

Подсказка, отображаемая под полем в интерфейсе администратора. Это полезно для описания поля, даже если модель не используется в форме.

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

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

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

primary_key¶

Field.primary_key¶

При True это поле будет первичным ключом.

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

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

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

Поле первичного ключа устанавливается в None при удалении <django.db.models.Model.delete>` объекта.

unique¶

Field.unique¶

При True значение поля должно быть уникальным.

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

Этот параметр можно использовать для любого типа поля кроме ManyToManyField, OneToOneField и FileField.

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

AutoField¶

class BigAutoField(**options)¶

64-битное целочисленное, аналогично IntegerField но позволяет хранить числа от -9223372036854775808 до 9223372036854775807. Форма будет использовать TextInput для отображения.

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.

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

Значение по умолчанию для 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 для некоторых типов баз данных. Смотрите раздел про использование различных типов баз данных.

CharField.db_collation¶

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

Примечание

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

Оракул

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

DateField¶

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

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

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

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

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

DecimalField¶

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

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

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

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 для хранения правильного email-адреса. Использует EmailValidator для проверки значения.

FileField¶

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

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

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

FileField.upload_to¶

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

Поддерживает форматирование 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 (с прямыми слэшами), который будет передан в систему хранения файлов(storage). Два аргумента это:

Аргумент	Описание
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, чтобы указать Django в каком подкаталоге в MEDIA_ROOT должны быть сохранены файлы.

3. Все, что будет сохранено в базе данных, это путь к файлу (относительно MEDIA_ROOT). Скорее всего вы будете использовать url предоставленную Django. Например, если ImageField назван mug_shot, вы можете получить URL к файлу в шаблоне используя {{ object.mug_shot.url }}.

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

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

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

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

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

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

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

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

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

GeneratedField¶

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

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

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

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¶

Определяет формат IP адреса. Принимает значение 'both' (по умолчанию), 'IPv4' или 'IPv6'. Значение не чувствительно регистру.

GenericIPAddressField.unpack_ipv4¶

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

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

ImageField¶

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)¶

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

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

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

ImageField.height_field¶

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

ImageField.width_field¶

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

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

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

Виджет форма для этого поля - ClearableFileInput.

IntegerField¶

class IntegerField(**options)¶

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

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

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

JSONField¶

class JSONField(encoder=None, decoder=None, **options)¶

Поле для хранения данных в формате JSON. В Python данные представлены в собственном формате Python: словари, списки, строки, числа, логические значения и «Нет».

JSONField поддерживается в MariaDB, MySQL, Oracle, PostgreSQL и SQLite (с включенным расширением JSON1).

JSONField.encoder¶

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

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

JSONField.decoder¶

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

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

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

PositiveBigIntegerField¶

class PositiveBigIntegerField(**options)¶

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

PositiveIntegerField¶

class PositiveIntegerField(**options)¶

Как и поле IntegerField, но значение должно быть больше или равно нулю (0). Можно использовать значение от 0 до 2147483647. Значение 0 принимается для обратной совместимости.

PositiveSmallIntegerField¶

class PositiveSmallIntegerField(**options)¶

Как и поле PositiveIntegerField, но принимает значения в определенном диапазоне(зависит от типа базы данных). Для баз данных поддерживаемых Django можно использовать значения от 0 до 32767.

SlugField¶

class SlugField(max_length=50, **options)¶

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

Как и для CharField, можно указать 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.

AutoField¶

class SmallAutoField(**options)¶

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

SmallIntegerField¶

class SmallIntegerField(**options)¶

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

TextField¶

class TextField(**options)¶

Большое текстовое поле. Форма использует виджет Textarea.

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

TextField.db_collation¶

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

Примечание

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

Оракул

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

TimeField¶

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

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

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

URLField¶

class URLField(max_length=200, **options)¶

Поле CharField для хранения правильного email-адреса. Использует EmailValidator для проверки значения.

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

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

UUIDField¶

class UUIDField(**options)¶

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

UUID является хорошей альтернативой 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:

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

ManyToManyField¶

class ManyToManyField(to, **options)¶

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

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

OneToOneField¶

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

Связь один-к-одному. Работает так же, как и ForeignKey с unique=True, но «обратная» связь возвращает один объект.

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

Принимает обязательный позиционный аргумент: класс связанной модели. Работает так же как и 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.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 в Связь один к одному.

Ленивые отношения¶

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

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