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

В данном документе содержатся все ссылки на 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'),
)

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

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.

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

Помимо 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'.

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

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]

Slug — термин из журналистики. Slug — это короткая метка для чего-либо, содержащая только буквы, цифры, нижние подчеркивания или дефисы. Они обычно используются в 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-shortcuts.

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’s 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. (on_delete фактически не требуется, но отсутствие параметра даёт предупреждение о устаревании. Он станет обязательным в Django 2.0.)

Чтобы создать рекурсивную связь — объект, имеющий связь «многие ко одному» с самим собой — используйте 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(), или, если передан вызываемый объект, результат его вызова. В большинстве случаев для предотвращения выполнения запросов при импорте моделей потребуется передать вызываемый объект:

  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

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

from django.db import models

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

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

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

ManyToManyField.through

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

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

Если вы не указали явную модель through, всё равно есть неявный класс модели 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 использует для сопоставления значения поля со значениями, специфичными для базы данных.

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.

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

rel_db_type(connection) [source]

Добавлена в Django 1.10.

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

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

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

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

Примечание

По соображениям производительности, from_db_value не реализован как пустая операция для полей, которые её не требуют (все поля 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.