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

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

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

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

null

Field.null

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

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

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

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

blank

Field.blank

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

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

choices

Field.choices

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

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

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

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

from django.db import models

class Student(models.Model):
    FRESHMAN = 'FR'
    SOPHOMORE = 'SO'
    JUNIOR = 'JR'
    SENIOR = 'SR'
    YEAR_IN_SCHOOL_CHOICES = (
        (FRESHMAN, 'Freshman'),
        (SOPHOMORE, 'Sophomore'),
        (JUNIOR, 'Junior'),
        (SENIOR, 'Senior'),
    )
    year_in_school = models.CharField(
        max_length=2,
        choices=YEAR_IN_SCHOOL_CHOICES,
        default=FRESHMAN,
    )

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

Хотя вы можете определить список вариантов вне класса модели и затем обратиться к нему, определение вариантов и их имен внутри класса модели сохраняет всю эту информацию с классом, который ее использует, и делает варианты легко доступными (например, Student.SOPHOMORE будет работать в любом месте, где была импортирована модель Student).

Вы также можете объединять доступные варианты в именованные группы для целей организации:

MEDIA_CHOICES = (
    ('Audio', (
            ('vinyl', 'Vinyl'),
            ('cd', 'CD'),
        )
    ),
    ('Video', (
            ('vhs', 'VHS Tape'),
            ('dvd', 'DVD'),
        )
    ),
    ('unknown', 'Unknown'),
)

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

default

Field.default

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

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

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

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

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

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

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

editable

Field.editable

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

error_messages

Field.error_messages

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

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

help_text

Field.help_text

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

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

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

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

primary_key

Field.primary_key

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

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

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

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

unique

Field.unique

Если True, это поле должно быть уникальным во всей таблице.

Это накладывается на уровне базы данных и при валидации модели. Если вы попытаетесь сохранить модель со значением, дублирующимся в поле unique, метод save() модели поднимет django.db.IntegrityError.

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

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

unique_for_date

Field.unique_for_date

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

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

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

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

unique_for_month

Field.unique_for_month

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

unique_for_year

Field.unique_for_year

Как unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

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

validators

Field.validators

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

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

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

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

AutoField

class AutoField(**options) [source]

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

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]

A CharField that checks that the value is a valid email address. It uses EmailValidator to validate the input.

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

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

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

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

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

SlugField.allow_unicode

Новое в Django 1.9.

Если 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.

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

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

UUIDField

class UUIDField(**options) [source]

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

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

import uuid
from django.db import models

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

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

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

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

ForeignKey

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

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

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

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

from django.db import models

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

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

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

from django.db import models

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

    class Meta:
        abstract = True

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

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

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

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

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

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

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

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

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

Аргументы

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

ForeignKey.on_delete

Когда объект, на который ссылается ForeignKey, удаляется, Django будет эмулировать поведение SQL-ограничения, указанного аргументом on_delete. Например, если у вас есть допускающее NULL значение 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(othermodel, **options) [source]

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

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

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

На самом деле, Django создаёт промежуточную таблицу для представления связи многие-ко-многим. По умолчанию, имя этой таблицы генерируется с помощью имени поля многие-ко-многим и имени таблицы для модели, которая его содержит. Поскольку некоторые базы данных не поддерживают имена таблиц длиннее определённого предела, эти имена таблиц будут автоматически усечены до 64 символов, и будет использован хэш для уникальности. Это означает, что вы можете увидеть имена таблиц, например, author_books_9cdf4; это совершенно нормально. Вы можете вручную указать имя таблицы соединения, используя параметр db_table.

Аргументы

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

ManyToManyField.related_name

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

ManyToManyField.related_query_name

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

ManyToManyField.limit_choices_to

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

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

ManyToManyField.symmetrical

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

from django.db import models

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

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

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

ManyToManyField.through

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

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

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

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

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

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

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

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

ManyToManyField.through_fields

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

from django.db import models

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

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

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

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

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

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

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

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

Ошибка передавать и db_constraint и through.

ManyToManyField.swappable

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

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

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

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

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

OneToOneField

class OneToOneField(othermodel, on_delete, parent_link=False, **options) [source]

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

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

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

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

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

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

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

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

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

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

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

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

OneToOneField.parent_link

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

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

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

class Field [source]

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

Таким образом, поле является фундаментальным элементом различных API 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 не реализован как no-op для полей, которые этого не требуют (все поля Django). Следовательно, вы не можете вызвать super в своём определении.

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

get_db_prep_save(value, connection) [source]

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

pre_save(model_instance, add) [source]

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

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

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

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

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

to_python(value) [source]

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

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

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

value_to_string(obj) [source]

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

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

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

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

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

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

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

deconstruct() [source]

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

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

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

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

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

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

Field.auto_created

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

Field.concrete

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

Field.hidden

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

Примечание

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

Field.is_relation

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

Field.model

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

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

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

Field.many_to_many

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

Field.many_to_one

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

Field.one_to_many

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

Field.one_to_one

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

Field.related_model

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