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

В данном документе содержатся все ссылки на API для Field, включая опции полей и типы полей, предлагаемые Django.

Опции полей

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

null

Field.null

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

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

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

Если вы хотите принять значения null с BooleanField, используйте NullBooleanField вместо этого.

blank

Field.blank

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

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

choices

Field.choices

Итерируемый объект (например, список или кортеж), состоящий из итерируемых объектов ровно из двух элементов (например, [(A, B), (A, B) ...]), которые будут использоваться в качестве вариантов для этого поля. Если задано, виджет формы по умолчанию будет выпадающим списком с этими вариантами вместо стандартного текстового поля.

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

YEAR_IN_SCHOOL_CHOICES = (
    ('FR', 'Freshman'),
    ('SO', 'Sophomore'),
    ('JR', 'Junior'),
    ('SR', 'Senior'),
)

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

from django.db import models

class Student(models.Model):
    FRESHMAN = 'FR'
    SOPHOMORE = 'SO'
    JUNIOR = 'JR'
    SENIOR = 'SR'
    YEAR_IN_SCHOOL_CHOICES = (
        (FRESHMAN, 'Freshman'),
        (SOPHOMORE, 'Sophomore'),
        (JUNIOR, 'Junior'),
        (SENIOR, 'Senior'),
    )
    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 в этом примере).

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

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

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

db_column

Field.db_column

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

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

db_index

Field.db_index

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

db_tablespace

Field.db_tablespace

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

default

Field.default

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

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

def contact_default():
    return {"email": "to1@example.com"}

contact_info = JSONField("ContactInfo", default=contact_default)

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

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

Значение по умолчанию используется при создании новых экземпляров модели, если для поля не задано значение. Когда поле является первичным ключом, значение по умолчанию также используется, если поле установлено в None.

editable

Field.editable

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

error_messages

Field.error_messages

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

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

help_text

Field.help_text

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

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

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

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

primary_key

Field.primary_key

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

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

primary_key=True подразумевает null=False и unique=True. Только одно поле первичного ключа разрешено в объекте.

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

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

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

Регистрация и получение поисковых запросов

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

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

AutoField

class AutoField(**options) [source]

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

BigIntegerField

class BigIntegerField(**options) [source]

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

BinaryField

class BinaryField(**options) [source]

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

BooleanField

class BooleanField(**options) [source]

Поле для булевых значений (истина/ложь).

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

Если вам нужно принять значения null, используйте NullBooleanField.

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

CharField

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

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

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

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

CharField имеет один дополнительный обязательный аргумент:

CharField.max_length

Максимальная длина (в символах) поля. Максимальная длина проверяется на уровне базы данных и в валидации Django.

CommaSeparatedIntegerField

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

Поле целых чисел, разделенных запятыми. Как и в CharField, аргумент max_length является обязательным, и следует учитывать примечание о переносимости на базу данных, указанное там.

DateField

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

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

DateField.auto_now

Автоматически устанавливает поле в текущую дату при каждом сохранении объекта. Полезно для отметки «последнего изменения». Обратите внимание, что текущая дата всегда используется; это не просто значение по умолчанию, которое можно переопределить.

Поле обновляется только при вызове Model.save(). Поле не обновляется при обновлении других полей другими способами, такими как QuerySet.update(), хотя вы можете указать пользовательское значение для поля при таком обновлении.

DateField.auto_now_add

Автоматически устанавливает поле в текущую дату при первом создании объекта. Полезно для отметки времени создания. Обратите внимание, что текущая дата всегда используется; это не просто значение по умолчанию, которое можно переопределить. Поэтому даже если вы зададите значение для этого поля при создании объекта, оно будет проигнорировано. Если вы хотите иметь возможность изменить это поле, установите следующее вместо auto_now_add=True:

• Для DateField: default=date.today - из datetime.date.today()
• Для DateTimeField: default=timezone.now - из django.utils.timezone.now()

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

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

DateTimeField

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

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

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

DecimalField

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

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

DecimalField.max_digits

Максимальное количество цифр, разрешенных в числе. Обратите внимание, что это число должно быть больше или равно decimal_places

DecimalField.decimal_places

Количество десятичных знаков для хранения числа.

Например, для хранения чисел до 999 с точностью до 2 десятичных знаков вы бы использовали:

models.DecimalField(..., max_digits=5, decimal_places=2)

И для хранения чисел до примерно одного миллиарда с точностью до 10 десятичных знаков:

models.DecimalField(..., max_digits=19, decimal_places=10)

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

DurationField

class DurationField(**options) [source]

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

EmailField

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

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

FileField

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

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

Имеет два необязательных аргумента:

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 (с использованием слешей) для передачи в систему хранения.

Два аргумента:

Аргумент	Описание
instance	Экземпляр модели, в которой определено FileField. Более конкретно, это конкретный экземпляр, к которому прикрепляется текущий файл. В большинстве случаев этот объект ещё не был сохранён в базе данных, поэтому, если он использует стандартное AutoField, возможно, у него ещё нет значения для поля первичного ключа.
filename	Имя файла, которое было первоначально указано для файла. Оно может или не может учитываться при определении конечного пути назначения.

Например:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return 'user_{0}/{1}'.format(instance.user.id, filename)

class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storage

Объект хранилища, который обрабатывает хранение и извлечение файлов. Подробности о предоставлении этого объекта см. в разделе Управление файлами.

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

Использование FileField или ImageField (см. ниже) в модели требует нескольких шагов:

1. В файле настроек необходимо определить MEDIA_ROOT как полный путь к каталогу, в котором Django должен хранить загруженные файлы. (Для повышения производительности эти файлы не хранятся в базе данных.) Определите MEDIA_URL как базовый публичный URL этого каталога. Убедитесь, что этот каталог доступен для записи пользователю веб-сервера.
2. Добавьте FileField или ImageField в свою модель, определив опцию upload_to для указания подкаталога MEDIA_ROOT для загруженных файлов.
3. В базу данных будет сохраняться только путь к файлу (относительно MEDIA_ROOT). Вероятно, вы захотите использовать удобный атрибут url, предоставляемый Django. Например, если ваше ImageField называется mug_shot, вы можете получить абсолютный путь к своему изображению в шаблоне с помощью {{ object.mug_shot.url }}.

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

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

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

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

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

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

FileField и FieldFile

class FieldFile [source]

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

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

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

FieldFile.name

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

FieldFile.size

Результат вызова метода Storage.size() над базовым хранилищем.

FieldFile.url

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

FieldFile.open(mode='rb') [source]

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

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

FieldFile.close() [source]

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

FieldFile.save(name, content, save=True) [source]

Этот метод принимает имя файла и содержимое файла и передаёт их классу хранилища для поля, затем связывает сохранённый файл с полем модели. Если вы хотите вручную связать данные файла с экземплярами 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) [source]

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

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

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

FilePathField

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

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

FilePathField.path

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

FilePathField.match

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

FilePathField.recursive

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

FilePathField.allow_files

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

FilePathField.allow_folders

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

Конечно, эти аргументы можно использовать вместе.

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

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

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

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

FloatField

class FloatField(**options) [source]

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

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

ImageField

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options) [source]

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

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

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

ImageField.height_field

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

ImageField.width_field

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

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

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

Поле по умолчанию для этого поля — ClearableFileInput.

IntegerField

class IntegerField(**options) [source]

Целое число. Значения от -2147483648 до 2147483647 безопасны во всех базах данных, поддерживаемых Django. Поле по умолчанию для этого поля — NumberInput, если localize равно False, или TextInput в противном случае.

GenericIPAddressField

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

Адрес 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'.

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

NullBooleanField

class NullBooleanField(**options) [source]

Как и BooleanField, но допускает NULL как одно из вариантов. Используйте его вместо BooleanField с null=True. Поле по умолчанию для этого поля — NullBooleanSelect.

PositiveIntegerField

class PositiveIntegerField(**options) [source]

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options) [source]

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

SlugField

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

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

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

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

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

SlugField.allow_unicode

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

SmallIntegerField

class SmallIntegerField(**options) [source]

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

TextField

class TextField(**options) [source]

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

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

TimeField

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

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

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

URLField

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

A CharField для URL.

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

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

UUIDField

class UUIDField(**options) [source]

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

Универсальные уникальные идентификаторы — хорошая альтернатива AutoField для primary_key. База данных не сгенерирует UUID за вас, поэтому рекомендуется использовать default:

import uuid
from django.db import models

class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

Обратите внимание, что вызываемый объект (без скобок) передаётся в default, а не экземпляр UUID.

Связанные поля

Django также определяет набор полей, представляющих отношения.

ForeignKey

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

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

Для создания рекурсивной связи — объекта, имеющего связь «многие ко многим» с самим собой — используйте models.ForeignKey('self', on_delete=models.CASCADE).

Если вам нужно создать отношение к модели, которая ещё не определена, вы можете использовать имя модели, а не сам объект модели:

from django.db import models

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

class Manufacturer(models.Model):
    # ...
    pass

Отношения, определённые таким образом на абстрактных моделях, разрешаются при создании дочерней конкретной модели и не относительны к абстрактной модели app_label:

from django.db import models

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

    class Meta:
        abstract = True

from django.db import models
from products.models import AbstractCar

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

# Car.manufacturer will point to `production.Manufacturer` here.

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

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

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

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

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

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

Аргументы внешнего ключа

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

ForeignKey.on_delete

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

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

Устарело начиная с версии 1.9: on_delete станет обязательным аргументом в Django 2.0. В более ранних версиях он по умолчанию CASCADE.

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

• CASCADE [source]

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

• PROTECT [source]

  Запрещает удаление связанного объекта, вызывая ProtectedError, подкласс django.db.IntegrityError.

• SET_NULL [source]

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

• SET_DEFAULT [source]

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

• SET() [source]

  Устанавливает ForeignKey в значение, переданное в SET(), или, если передан вызываемый объект, в результат его вызова. В большинстве случаев для предотвращения выполнения запросов при импорте моделей.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 [source]

  Не выполнять никаких действий. Если ваш СУБД обеспечивает целостность ссылок, это приведёт к 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 только Users с is_staff=True. Это может быть полезно в Django админке.

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

def limit_pub_date_choices():
    return {'pub_date__lte': datetime.date.utcnow()}

limit_choices_to = limit_pub_date_choices

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

Примечание

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

ForeignKey.related_name

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

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

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

ForeignKey.related_query_name

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

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

ForeignKey.to_field

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

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(othermodel, **options) [source]

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

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

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

Внутри Django создается промежуточная таблица соединения для представления связи «многие ко многим». По умолчанию имя этой таблицы генерируется с использованием имени поля «многие ко многим» и имени таблицы для модели, которая его содержит. Поскольку некоторые базы данных не поддерживают имена таблиц сверх определенной длины, эти имена таблиц будут автоматически усечены до 64 символов, а для обеспечения уникальности будет использоваться хэш. Это означает, что вы можете увидеть имена таблиц, подобные author_books_9cdf4; это совершенно нормально. Вы можете вручную указать имя таблицы соединения, используя параметр 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.

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

ManyToManyField.symmetrical

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

from django.db import models

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

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

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

ManyToManyField.through

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

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

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

Если модели источника и получателя отличаются, генерируются следующие поля:

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

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

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

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

ManyToManyField.through_fields

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

from django.db import models

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

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

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

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

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

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

Рекурсивные взаимосвязи с использованием промежуточной модели всегда определяются как несимметричные — то есть с symmetrical=False — поэтому есть понятие «источника» и «получателя». В этом случае 'field1' будет рассматриваться как «источник» отношения, а 'field2' — как «получатель».

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(othermodel, on_delete, parent_link=False, **options) [source]

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

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

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

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

Рассмотрим следующий пример:

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

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

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

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

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

>>> user.supervisor_of
Traceback (most recent call last):
    ...
DoesNotExist: User matching query does not exist.

Кроме того, OneToOneField принимает все дополнительные аргументы, принимаемые ForeignKey, плюс один дополнительный аргумент:

OneToOneField.parent_link

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

См. Примеры связей один-к-одному для примеров использования OneToOneField.

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

class Field [source]

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

Поле — это фундаментальный элемент в различных API Django, в частности, models и querysets.

В моделях поле создаётся как атрибут класса и представляет определённый столбец таблицы, см. Модели. Оно имеет атрибуты, такие как 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__ поля.

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

get_internal_type() [source]

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

См. Эмуляция встроенных типов полей для использования в пользовательских полях.

db_type(connection) [source]

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

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

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

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

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

get_prep_value(value) [source]

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

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

get_db_prep_value(value, connection, prepared=False) [source]

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

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

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

from_db_value(value, expression, connection, context)

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

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

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

Примечание

По причинам производительности from_db_value не реализован как no-op для полей, которые его не требуют (все поля Django). Вследствие этого вы не можете вызвать super в своём определении.

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

get_db_prep_save(value, connection) [source]

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

pre_save(model_instance, add) [source]

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

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

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

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

Когда операция поиска используется с полем, значение может потребоваться «подготовить». Django предоставляет два метода для этого:

get_prep_lookup(lookup_type, value) [source]

Подготавливает значение value для базы данных перед использованием в поиске. Значение lookup_type будет одним из допустимых поисковых запросов Django: "exact", "iexact", "contains", "icontains", "gt", "gte", "lt", "lte", "in", "startswith", "istartswith", "endswith", "iendswith", "range", "year", "month", "day", "isnull", "search", "regex", и "iregex".

Если вы используете Пользовательские запросы, значение lookup_type может быть любым lookup_name зарегистрированным в поле.

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

get_db_prep_lookup(lookup_type, value, connection, prepared=False) [source]

Аналогично get_db_prep_value(), но для выполнения поиска.

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

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

to_python(value) [source]

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

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

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

value_to_string(obj) [source]

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

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

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

formfield(form_class=None, choices_form_class=None, **kwargs) [source]

Возвращает стандартное поле django.forms.Field для этого поля в ModelForm.

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

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

deconstruct() [source]

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

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

Этот метод должен быть добавлен к полям до версии 1.7, чтобы мигрировать данные с использованием Миграций.

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

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

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

Field.auto_created

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

Field.concrete

Флаг булевого типа, указывающий, связано ли с полем поле в базе данных.

Field.hidden

Флаг булевого типа, указывающий, используется ли поле для поддержки функциональности другого поля, не являющегося скрытым (например, content_type и object_id поля, составляющие GenericForeignKey). Флаг hidden используется для отличия публичной подмножества полей модели от всех полей модели.

Примечание

Options.get_fields() по умолчанию исключает скрытые поля. Передайте include_hidden=True чтобы вернуть скрытые поля в результатах.

Field.is_relation

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

Field.model

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

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

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

Field.many_to_many

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

Field.many_to_one

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

Field.one_to_many

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

Field.one_to_one

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

Field.related_model

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