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

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

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, модель django.db.IntegrityError будет поднята методом save() модели.

Этот параметр доступен для всех типов полей, кроме ManyToManyField и OneToOneField.

Обратите внимание, что когда unique имеет значение True, вам не нужно указывать db_index, потому что unique подразумевает создание индекса.

unique_for_date

Field.unique_for_date

Установите это значение в имя DateField или DateTimeField, чтобы потребовать, чтобы это поле было уникальным для значения поля даты.

Например, если у вас есть поле title с unique_for_date="pub_date", Django не позволит ввести две записи с одинаковым title и pub_date.

Обратите внимание, что если вы установите это значение, указывающее на DateTimeField, будет рассмотрена только дата части поля. Кроме того, когда USE_TZ имеет значение True, проверка будет выполнена в текущем часовом поясе в момент сохранения объекта.

Это обеспечивается Model.validate_unique() во время валидации модели, но не на уровне базы данных. Если какой-либо ограничение unique_for_date включает поля, которые не являются частью ModelForm (например, если одно из полей указано в exclude или имеет editable=False), Model.validate_unique() пропустит проверку для этого конкретного ограничения.

unique_for_month

Field.unique_for_month

Подобно unique_for_date, но требует, чтобы поле было уникальным относительно месяца.

unique_for_year

Field.unique_for_year

Подобно unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

Человекопонятное имя поля. Если имя не указано, Django автоматически создаст его, используя имя атрибута поля, преобразуя символы подчеркивания в пробелы. Смотрите Имена полей с понятными названиями.

validators

Field.validators

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

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

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

Поле для хранения необработанных двоичных данных. Ему можно присвоить bytes, bytearray или memoryview.

По умолчанию, BinaryField устанавливает editable в False, в этом случае его нельзя включить в ModelForm.

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

BinaryField.max_length

Максимальная длина поля (в символах). Максимальная длина проверяется в Django с помощью MaxLengthValidator.

BooleanField

class BooleanField(**options) [source]

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

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

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

CharField

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

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

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

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

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

CharField.max_length

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

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 экземпляра. Проверяет входные данные с помощью DecimalValidator.

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

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]

A CharField that checks that the value is a valid email address using 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]

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

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

Поле по умолчанию для этого поля — 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, так как пустые значения хранятся как NULL.

NullBooleanField

class NullBooleanField(**options) [source]

Подобно BooleanField с null=True. Используйте его вместо этого поля, так как оно, вероятно, будет устаревшим в будущих версиях Django.

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.

Используются validate_slug или validate_unicode_slug для валидации.

SlugField.allow_unicode

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

SmallIntegerField

class SmallIntegerField(**options) [source]

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

TextField

class TextField(**options) [source]

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

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

TimeField

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

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

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

URLField

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

CharField для URL, валидируется с помощью URLValidator.

По умолчанию виджет для этого поля — 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 не создаёт SQL-ограничение в базе данных. Поддержка опций каскадирования на уровне базы данных может быть реализована позже.

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

• CASCADE [source]

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

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

• 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-ограничение к полю базы данных.

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

Аргументы

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

ManyToManyField.related_name

Аналогично ForeignKey.related_name.

ManyToManyField.related_query_name

Аналогично ForeignKey.related_query_name.

ManyToManyField.limit_choices_to

Аналогично ForeignKey.limit_choices_to.

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

Поле является подклассом 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_from_object(obj) [source]

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

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

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.