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

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

Параметры полей

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

null

Field.null

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

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

Для полей как на основе строк, так и не на основе строк, вам также нужно установить 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'),
)

Первый элемент в каждом кортеже — имя, применяемое к группе. Второй элемент — итерируемый объект из 2-кортежей, где каждый 2-кортеж содержит значение и удобочитаемое имя варианта. Группированные варианты могут быть объединены с необъединенными вариантами в одном списке (например, вариант 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

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

Значение по умолчанию не может быть изменяемым объектом (экземпляр модели, 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.

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, метод модели save() поднимет исключение django.db.IntegrityError.

Этот параметр доступен для всех типов полей, кроме 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

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

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

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

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

AutoField

class AutoField(**options) [source]

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

BigAutoField

class BigAutoField(**options) [source]

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

BigIntegerField

class BigIntegerField(**options) [source]

Це целое 64-битное число, подобное IntegerField, но гарантируется, что оно вместит числа от -9223372036854775808 до 9223372036854775807. Поле по умолчанию для этого поля — TextInput.

BinaryField

class BinaryField(**options) [source]

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

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.

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 в пользовательском хранилище.

Помимо API, унаследованного от 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, поле принимает Unicode-буквы в дополнение к 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]

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

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

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

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

from django.db import models

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

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

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

from django.db import models

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

    class Meta:
        abstract = True

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

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

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

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

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

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

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

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

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

Аргументы

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

ForeignKey.on_delete

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

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

Возможные значения для 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 или 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) [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

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

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

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

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

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

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

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

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

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

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

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

Исключение 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 Django, в частности, models и querysets.

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

Поле является подклассом 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.

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

rel_db_type(connection) [source]

Возвращает тип данных столбца базы данных для полей, таких как ForeignKey и OneToOneField, которые указывают на 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)

Преобразует значение, возвращенное базой данных, в объект 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).

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

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

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 и 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). related_model для GenericForeignKey всегда None.