Справочник типов полей

Этот документ содержит весь справочник по API Field, включая` field options`_ и field types, предлагаемые Django.

См.также

Если встроенные поля не помогают, вы можете попробовать django-localflavor (documentation),, который содержит различные фрагменты кода, полезные для конкретных стран и культур.

Также вы можете легко создать свои собственные поля модели.

Примечание

Поля определены в django.db.models.fields, но для удобства они импортированы в django.db.models. Стандартным соглашением является использование from django.db import models и обращение к полям как к models.<Foo>Field.

Опции полей

Следующие аргументы доступны для всех типов полей. Все необязательные.

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

Примечание

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

blank

Field.blank

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

Обратите внимание, что это отличается от null. null связана исключительно с базой данных, тогда как blank связана с проверкой. Если поле имеет blank=True, проверка формы позволит ввести пустое значение. Если поле имеет blank=False, поле будет обязательным.

Предоставление недостающих значений

blank=True можно использовать с полями, имеющими null=False, но это потребует реализации clean() в модели, чтобы программно предоставить все недостающие значения.

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.

Типы перечисления

Кроме того, Django предоставляет типы перечисления, которые вы можете создать на подклассе для краткого определения вариантов:

from django.utils.translation import gettext_lazy as _


class Student(models.Model):
    class YearInSchool(models.TextChoices):
        FRESHMAN = "FR", _("Freshman")
        SOPHOMORE = "SO", _("Sophomore")
        JUNIOR = "JR", _("Junior")
        SENIOR = "SR", _("Senior")
        GRADUATE = "GR", _("Graduate")

    year_in_school = models.CharField(
        max_length=2,
        choices=YearInSchool,
        default=YearInSchool.FRESHMAN,
    )

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

Они работают аналогично enum из стандартной библиотеки Python, но с некоторыми изменениями:

  • Значения членов Enum - это кортеж аргументов, которые нужно использовать при построении конкретного типа данных. Django поддерживает добавление дополнительного строкового значения в конец этого кортежа, которое будет использоваться в качестве человекочитаемого имени, или label. label может быть лениво переводимой строкой. Таким образом, в большинстве случаев значение члена будет представлять собой 2-кортеж (value, label). О an example of subclassing choices с использованием более сложного типа данных см. ниже. Если кортеж не указан или последний элемент не является (ленивой) строкой, то label будет automatically generated из имени члена.

  • Свойство .label добавляется в значения, чтобы вернуть удобочитаемое имя.

  • В классы перечислений добавлено несколько пользовательских свойств - .choices, .labels, .values и .names - чтобы упростить доступ к спискам этих отдельных частей перечисления.

    Предупреждение

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

  • Использование enum.unique() применяется для обеспечения того, чтобы значения не могли быть определены несколько раз. Этого вряд ли можно ожидать при выборе поля.

Обратите внимание, что использование YearInSchool.SENIOR, YearInSchool['SENIOR'] или YearInSchool('SR') для доступа к элементам перечисления или их поиска работает должным образом, как и .name и .value свойства для членов.

Если перевод человекочитаемых имен не требуется, их можно вывести из имени пользователя (заменяя подчеркивания пробелами и используя регистр заголовка):

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

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

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

    suit = models.IntegerField(choices=Suit)

Также можно использовать Enum Functional API с оговоркой, что метки будут генерироваться автоматически, как было указано выше:

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

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

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

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

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

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

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

    __empty__ = _("(Unknown)")

db_column

Field.db_column

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

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

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, для этого поля будет создан индекс базы данных.

Вместо этого используйте параметр indexes.

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

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, то поле не будет отображаться ни в admin, ни в любом другом ModelForm. Оно также будет пропущено во время model validation. По умолчанию используется 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. Для каждой модели может быть установлено только одно поле primary_key=True. Составные первичные ключи должны быть определены с использованием CompositePrimaryKey вместо установки этого флага на True, чтобы все поля сохраняли этот инвариант.

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

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

Changed in Django 5.2:

Было добавлено поле CompositePrimaryKey.

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.

Злоупотребление BinaryField

Хотя вы можете подумать о хранении файлов в базе данных, учтите, что это плохой дизайн в 99% случаев. Это поле не замена для правильной обработки статических файлов.

BooleanField

class BooleanField(**options)

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

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

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

CompositePrimaryKey

New in Django 5.2.
class CompositePrimaryKey(*field_names, **options)

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

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

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

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

CharField

class CharField(max_length=None, **options)

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

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

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

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

CharField.max_length

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

Примечание

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

Changed in Django 5.2:

В SQLite была добавлена поддержка неограниченного количества столбцов 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 следующее:

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

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

Примечание

Как в настоящее время реализовано, установка auto_now или auto_now_add в True приведет к тому, что в поле будут установлены editable=False и blank=True.

Примечание

Опции auto_now и auto_now_add всегда будут использовать дату в часовом поясе по умолчанию в момент создания или обновления. Если вам нужно что-то другое, вы можете рассмотреть возможность использования собственной функции вызываемой по умолчанию или переопределения save() вместо использования auto_now или auto_now_add; или используя DateTimeField вместо `` DateField`` и решая, как обрабатывать преобразование из даты-времени в дату во время отображения.

Предупреждение

Всегда используйте DateField с экземпляром datetime.date.

Если у вас есть экземпляр datetime.datetime, рекомендуется сначала преобразовать его в datetime.date. Если вы этого не сделаете, DateField локализует datetime.datetime в default timezone и преобразует его в экземпляр datetime.date, удалив его временную составляющую. Это справедливо как для хранения, так и для сравнения.

DateTimeField

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

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

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

Предупреждение

Всегда используйте DateTimeField с экземпляром datetime.datetime.

Если у вас есть экземпляр datetime.date, рекомендуется сначала преобразовать его в datetime.datetime. Если вы этого не сделаете, DateTimeField будет использовать полночь в default timezone для компонента времени. Это справедливо как для хранения, так и для сравнения. Чтобы сравнить часть данных DateTimeField с экземпляром datetime.date, воспользуйтесь поиском date.

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 в противном случае.

Примечание

Для получения дополнительной информации о различиях между классами FloatField и DecimalField, пожалуйста, смотрите FloatField или DecimalField. Вы также должны ознакомиться с ограничения SQLite для десятичных полей.

DurationField

class DurationField(**options)

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

Примечание

Арифметика с DurationField работает в большинстве случаев. Однако во всех базах данных, кроме PostgreSQL, сравнение значения DurationField с арифметикой в экземплярах DateTimeField не будет работать должным образом.

EmailField

class EmailField(max_length=254, **options)

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

FileField

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

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

Примечание

Аргумент primary_key не поддерживается и выдает ошибку, если используется.

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

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.

FileField и FieldFile

class FieldFile

Когда вы обращаетесь к FileField в модели, вам предоставляется экземпляр FieldFile в качестве прокси для доступа к базовому файлу.

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

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

Предупреждение

Два метода этого класса save() и delete(), по умолчанию сохраняют объект модели связанного FieldFile в базе данных.

FieldFile.name

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

FieldFile.path

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

FieldFile.size

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

FieldFile.url

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

FieldFile.open(mode='rb')

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

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

FieldFile.close()

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

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

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

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

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

from django.core.files import File

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

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

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

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

FieldFile.delete(save=True)

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

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

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

FilePathField

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

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

FilePathField.path

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

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

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


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


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

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

FilePathField.recursive

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

FilePathField.allow_files

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

FilePathField.allow_folders

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

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

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

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

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

FloatField

class FloatField(**options)

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

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

FloatField против DecimalField

Класс FloatField иногда сопоставляют с классом DecimalField. Хотя они оба представляют действительные числа, они представляют эти числа по-разному. FloatField использует внутри Python тип float, а DecimalField использует тип Decimal. Информацию о разнице между ними смотрите в документации Python для модуля decimal.

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 поддерживает только виртуальные колонки.

Обновление данных

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

Ограничения базы данных

Существует множество специфических для базы данных ограничений на генерируемые поля, которые Django не проверяет, и база данных может выдать ошибку, например, PostgreSQL требует, чтобы функции и операторы, на которые ссылается генерируемый столбец, были помечены как IMMUTABLE.

Вы должны всегда проверять, поддерживается ли expression в вашей базе данных. Проверьте документацию по MariaDB, MySQL, Oracle, PostgreSQL или SQLite.

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.

Значение по умолчанию

Если вы присваиваете полю значение default, убедитесь, что это вызываемый объект, например, класс dict или функция, которая каждый раз возвращает свежий объект. Неправильное использование мутабельных объектов, таких как default={} или default=[], создает мутабельное значение по умолчанию, которое разделяется между всеми экземплярами.

Индексирование

Index и Field.db_index оба создают индекс B-дерева, который не особенно полезен при запросах к JSONField. Только в PostgreSQL вы можете использовать GinIndex, который лучше подходит.

Пользователи PostgreSQL

PostgreSQL имеет два собственных типа данных на основе JSON: json и jsonb. Основное различие между ними заключается в том, как они хранятся и как к ним можно обращаться. Поле json в PostgreSQL хранится как оригинальное строковое представление JSON и должно быть декодировано на лету при запросе на основе ключей. Поле jsonb хранится на основе фактической структуры JSON, что позволяет осуществлять индексирование. Компромиссом является небольшая дополнительная стоимость записи в поле jsonb. В JSONField используется jsonb.

Пользователи Oracle

База данных Oracle не поддерживает хранение скалярных значений JSON. Поддерживаются только объекты и массивы JSON (представленные в Python с использованием dict и list).

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.

Поиск в PostgreSQL и MariaDB 10.7+

Использование поисков iexact, contains, icontains, startswith, istartswith, endswith или iendswith в PostgreSQL не работает для значений без дефиса, поскольку PostgreSQL и MariaDB 10.7+ хранят их в типе данных 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)

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

Смотрите ForeignKey.on_delete для получения подробной информации о втором позиционном аргументе.

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

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

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

Аргументы

ForeignKey принимает другие аргументы, которые определяют детали работы отношений.

ForeignKey.on_delete

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

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

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

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

  • CASCADE

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

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

  • PROTECT

    Предотвращает удаление объекта, на который есть ссылка, путем вызова ProtectedError, подкласса django.db.IntegrityError.

  • RESTRICT

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

    Рассмотрим этот набор моделей:

    class Artist(models.Model):
    name = models.CharField(max_length=10)


class Album(models.Model):
    artist = models.ForeignKey(Artist, on_delete=models.CASCADE)


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

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

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

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

  • SET_DEFAULT

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

  • SET()

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

    from django.conf import settings
from django.contrib.auth import get_user_model
from django.db import models


def get_sentinel_user():
    return get_user_model().objects.get_or_create(username="deleted")[0]


class MyModel(models.Model):
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.SET(get_sentinel_user),
    )
  • DO_NOTHING

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

ForeignKey.limit_choices_to

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

Например:

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

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

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

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


limit_choices_to = limit_pub_date_choices

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

Примечание

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

ForeignKey.related_name

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

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

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

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

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


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

Например related_name, related_query_name поддерживает интерполяцию меток приложения и классов посредством специального синтаксиса.

ForeignKey.to_field

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

ForeignKey.db_constraint

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

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

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

ForeignKey.swappable

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

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

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

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

ManyToManyField

class ManyToManyField(to, **options)

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

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

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

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

Аргументы

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

ManyToManyField.related_name

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

ManyToManyField.related_query_name

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

ManyToManyField.limit_choices_to

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

ManyToManyField.symmetrical

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

from django.db import models


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

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

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

ManyToManyField.through

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

Модель through может быть указана либо непосредственно с помощью класса model, либо с помощью lazy reference для класса model.

Чаще всего этот параметр используется, когда вы хотите связать дополнительные данные с отношением «многие ко многим».

Примечание

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

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

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

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

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

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

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

Model.m2mfield.through.objects.all()
ManyToManyField.through_fields

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

from django.db import models


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


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


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

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

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

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

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

Будет ошибкой пропускать оба параметра: db_constraint и through.

ManyToManyField.swappable

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

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

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

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

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

OneToOneField

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

Отношения один-к-одному. Концептуально это похоже на ForeignKey с :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, плюс один дополнительный аргумент:

Когда True и используется в модели, которая наследуется от другого concrete model, указывает, что это поле следует использовать как ссылку на родительский класс, а не как дополнительное OneToOneField, которое обычно неявно создается путем создания подклассов.

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

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

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

Рекурсивный

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

from django.db import models


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

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

Родственник

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

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)

Отношения, определенные следующим образом абстрактные модели, разрешаются, когда модель подклассифицируется как конкретная модель, и не относятся к app_label абстрактной модели:

products/models.py
from django.db import models


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

    class Meta:
        abstract = True
production/models.py
from django.db import models
from products.models import AbstractCar


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


class Car(AbstractCar):
    pass

В этом примере отношение Car.manufacturer преобразуется в production.Manufacturer, поскольку оно указывает на конкретную модель, определенную в файле production/models.py.

Повторно используемые модели с относительными ссылками

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

Абсолютный

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

Например, если модель Manufacturer определена в другом приложении с именем thirdpartyapp, на нее можно ссылаться как:

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

Абсолютные ссылки всегда указывают на одну и ту же модель, даже если они используются в виде abstract model.

Справочник API полей

class Field

Field - абстрактный класс, представляющий столбец таблицы базы данных. Django использует поля для создания таблицы базы данных (db_type()), для отображения типов Python в базу данных (get_prep_value()) и наоборот (from_db_value()).

Таким образом, поле является фундаментальной частью в различных API Django, а именно модели и наборы запросов.

В моделях поле создается как атрибут класса и представляет определенный столбец таблицы, см. Модели. Он имеет такие атрибуты, как null и unique, а также методы, которые Django использует для сопоставления значения поля со значениями, специфичными для базы данных.

Field является подклассом RegisterLookupMixin и, следовательно, и Transform и Lookup может быть зарегистрирован для использования в QuerySet (например, field_name__exact="foo"). Все встроенные фильтры зарегистрированы по умолчанию.

Все встроенные поля Django, такие как CharField, являются конкретными реализациями Field. Если вам нужно настраиваемое поле, вы можете создать подкласс любого из встроенных полей или написать Field с нуля. В любом случае смотрите Как создать пользовательские поля модели.

description

Подробное описание поля, например, для приложения django.contrib.admindocs.

Описание может иметь вид:

description = _("String (up to %(max_length)s)")

где аргументы интерполируются из поля __dict__.

descriptor_class

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

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

get_internal_type()

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

Смотрите emulation-built-in-field-types для использования в пользовательских полях.

db_type(connection)

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

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

rel_db_type(connection)

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

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

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

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

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

get_prep_value(value)

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

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

get_db_prep_value(value, connection, prepared=False)

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

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

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

from_db_value(value, expression, connection)

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

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

expression это то же самое, что и self.

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

Примечание

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

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

get_db_prep_save(value, connection)

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

pre_save(model_instance, add)

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

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

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

Смотрите:ref:preprocessing-values-before-save для использования.

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

to_python(value)

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

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

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

value_from_object(obj)

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

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

value_to_string(obj)

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

Смотрите convert-model-field-field-to-serialization для использования.

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

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

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

Если formfield() переопределено для возврата None, это поле исключается из ModelForm.

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

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

deconstruct()

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

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

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

Регистрация и выборка поисков

Field реализует lookup registration API. API можно использовать для настройки того, какие поисковые запросы доступны для класса поля и его экземпляров, а также для настройки способа получения поисковых запросов из поля.

Справочник атрибутов полей

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

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

Field.auto_created

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

Field.concrete

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

Field.hidden

Логический флаг, указывающий, скрыто ли поле и не должно ли оно быть возвращено Options.get_fields() по умолчанию. Примером может служить обратное поле для ForeignKey с related_name, которое начинается с '+'.

Field.is_relation

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

Field.model

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

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

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

Field.many_to_many

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

Field.many_to_one

Логический флаг, устанавливаемый в True, если поле имеет отношение многие-к-одному, например, ForeignKey; иначе``False``.

Field.one_to_many

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

Field.one_to_one

Логический флаг, устанавливаемый в True, если поле имеет взаимно-однозначное отношение, например OneToOneField; иначе``False``.

Field.related_model

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

Модели
Справочник по индексам модели
Вернуться на верх