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

Этот раздел содержит все существующие подробности о всех параметрах поля и типах полей в Django.

См.также

Если существующие поля не предоставляют необходимого функционала, вы можете поискать в django-localflavor, который содержит дополнительный функционал полезный для различных стран.

Также вы можете легко создать собственное поле для модели.

Примечание

Технически, эти поля определенны в django.db.models.fields, но для удобства они импортированы в django.db.models; по неписанному соглашению принято использовать from django.db import models и обращаться к полям, как models.<Foo>Field.

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

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

null

Field.null

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

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

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

Примечание

При использовании Oracle, NULL будет использоваться для пустой строки независимо от значения этого параметра.

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

blank

Field.blank

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

Заметим что этот параметр отличается от null. null указывается для базы данных, в то время как blank – для проверки данных. При blank=True, проверка данных в форме позволит сохранять пустое значение в поле. При blank=False поле будет обязательным.

choices

Field.choices

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

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

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

Значения лучше указать в константах внутри модели:

from django.db import models

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

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

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

Вы можете сгруппировать значения в именованные группы:

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

Первый элемент каждого кортежа – это название группы. Второй элемент – итератор с двух-элементными кортежами содержащими значение и отображаемое название. Сгруппированные опции могут комбинироваться с не сгруппированными (как unknown в примере выше).

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

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

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

db_column

Field.db_column

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

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

db_index

Field.db_index

При True для поля будет создан индекс в базе данных.

db_tablespace

Field.db_tablespace

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

default

Field.default

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

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

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

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

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

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

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

Изменено в Django 1.8:

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

editable

Field.editable

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

error_messages

Field.error_messages

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

Ключи ошибок такие: null, blank, invalid, invalid_choice, unique и ``unique_for_date`. Дополнительные ошибки указаны для каждого типа поля ниже.

help_text

Field.help_text

Подсказка, отображаемая под полем в интерфейсе администратора. Это полезно для описания поля, даже если модель не используется в форме.

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

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

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

primary_key

Field.primary_key

При True это поле будет первичным ключом.

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

primary_key=True подразумевает null=False и unique=True. Модель может содержать только один первичный ключ.

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

unique

Field.unique

При True значение поля должно быть уникальным.

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

Этот параметр можно использовать для любого типа поля кроме ManyToManyField, OneToOneField и FileField.

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

unique_for_date

Field.unique_for_date

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

Например, если модель имеет поле title с unique_for_date="pub_date", тогда Django позволит сохранять записи только с уникальной комбинацией title и pub_date.

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

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

unique_for_month

Field.unique_for_month

Аналогично unique_for_date, но значение будет уникально для месяца.

unique_for_year

Field.unique_for_year

Аналогично unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

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

validators

Field.validators

Список проверок(“валидаторов”) выполняемых для этого поля. Смотрите раздел о “валидаторах” для подробной информации.

Регистрация и загрузка операторов для фильтрации

Field предоставляет API для регистрации своих операторов фильтрации. Этот API позволяет добавить свои варианты фильтрации по полю.

Типы полей

AutoField

class AutoField(**options)

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

BigIntegerField

class BigIntegerField(**options)

64-битное целочисленное, аналогично IntegerField но позволяет хранить числа от -9223372036854775808 до 9223372036854775807. Форма будет использовать TextInput для отображения.

BinaryField

class BinaryField(**options)

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

Злоупотребление BinaryField

Помните, хранение файлов в базе данных в 99% случаях - это плохой подход. Это поле не замена статическим файлам.

BooleanField

class BooleanField(**options)

Поле хранящее значение true/false.

Виджет по умолчанию для этого поля CheckboxInput.

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

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

CharField

class CharField(max_length=None, **options)

Строковое поле для хранения коротких или длинных строк.

Для большого количества текстовой информации используйте TextField.

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

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

CharField.max_length

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

Примечание

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

Пользователям MySQL

Если вы используете это поле с MySQLdb 1.2.2 и utf8_bin “collation” (которое не является значением по умолчанию), могут быть некоторые проблемы. Смотрите советы при работе с MySQL для подробностей.

CommaSeparatedIntegerField

class CommaSeparatedIntegerField(max_length=None, **options)

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

DateField

class DateField(auto_now=False, auto_now_add=False, **options)

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

DateField.auto_now

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

DateField.auto_now_add

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

В форме поле будет представлено как :class:`~django.forms.TextInput с JavaScript календарем, и кнопкой “Сегодня”. Содержит дополнительную ошибку invalid_date.

Опции auto_now_add, auto_now и default взаимоисключающие. Использование их вместе вызовет ошибку.

Примечание

При использовании auto_now или auto_now_add со значением True будут установлены параметры editable=False и blank=True.

Примечание

Опции``auto_now`` и auto_now_add всегда используют дату в часовом поясе по умолчанию в момент создания или изменения объекта. Если такое поведение вам не подходит, вы можете указать свою функцию как значение по умолчанию, или переопределить метод save(), вместо использования auto_now или auto_now_add. Или использовать DateTimeField вместо DateField и выполнять преобразование в дату при выводе значения.

DateTimeField

class DateTimeField(auto_now=False, auto_now_add=False, **options)

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

Виджет по умолчанию в форме для этого поля - TextInput. Интерфейс администратора использует два виджета TextInput и JavaScript.

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)

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

DecimalField.max_digits

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

DecimalField.decimal_places

Количество знаков после запятой.

Например, для хранения числа до 999 с двумя знаками после запятой, используйте:

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

Для хранения числа до миллиарда и 10 знаков после запятой:

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

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

Примечание

Для дополнительной информации о разнице между FloatField и DecimalField, смотрите раздел FloatField vs. DecimalField.

DurationField

Добавлено в Django 1.8.
class DurationField(**options)

Поля для хранения периодов времени - используется объект Python timedelta. Для PostgreSQL используется тип interval, а в Oracle – INTERVAL DAY(9) TO SECOND(6). Иначе используется bigint, в котором хранится количество микросекунд.

Примечание

Арифметика над DurationField работает в большинстве случаев. Однако, для всех баз данных, кроме PostgreSQL, арифметическое сравнение DurationField и DateTimeField работает не как ожидается.

EmailField

class EmailField(max_length=254, **options)

Поле CharField для хранения правильного email-адреса. Использует EmailValidator для проверки значения.

Изменено в Django 1.8:

Значение max_length по умолчанию было увеличено с 75 до 254 для совместимости с RFC3696/5321.

FileField

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

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

Примечание

primary_key и unique не принимаются, и вызовут исключение TypeError при использовании.

Также принимается два дополнительных параметра:

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 (с прямыми слэшами), который будет передан в систему хранения файлов(storage). Два аргумента это:

Аргумент

Описание

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

Объект “storage”, который отвечает за хранение и получение файлов. Смотрите Управление файлами для подробной информации.

Виджет форма для этого поля - ClearableFileInput.

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

  1. В файле настроек необходимо определить MEDIA_ROOT, как полный путь к каталогу, куда Django должен сохранять файлы. (Для повышения производительности файлы не хранятся в базе данных.) Определить MEDIA_URL, который является URL-ом к этому каталогу и используется для создания URL-а к файлу. Убедитесь, что пользователь, от которого работает сервер, имеет права записи в этот каталог.

  2. Добавьте FileField или ImageField к модели, определите upload_to, чтобы указать Django в каком подкаталоге в MEDIA_ROOT должны быть сохранены файлы.

  3. Все, что будет сохранено в базе данных, это путь к файлу (относительно MEDIA_ROOT). Скорее всего вы будете использовать url предоставленную Django. Например, если ImageField назван mug_shot, вы можете получить URL к файлу в шаблоне используя {{ object.mug_shot.url }}.

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

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

Примечание

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

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

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

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

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

FileField и FieldFile

class FieldFile

При доступе к FileField модели, вы получаете экземпляр FieldFile как “proxy” для работы с файлом. Этот класс содержит несколько дополнительных атрибутов и методов для работы с файлом, кроме унаследованных от django.core.files.File:

FieldFile.url

read-only свойство для получения URL вызовом метода url() класса Storage.

FieldFile.open(mode='rb')

Работает так же как и родной метод Python open() – открывает файл, связанный с объектом, в режиме определенном аргументом mode.

FieldFile.close()

Работает так же как и метод file.close() в Python и закрывает файл связанный с объектом.

FieldFile.save(name, content, save=True)

Этот метод принимает имя файла и содержимое и передает его в экземпляр класса “storage” этого поля, потом добавляет файл в модель. Если вы хотите самостоятельно добавить содержимое файла в поле 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('/tmp/hello.world')
myfile = File(f)

Или же создать из строки с содержимым файла:

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

Подробности в Управление файлами.

FieldFile.delete(save=True)

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

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

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

FilePathField

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

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

FilePathField.path

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

FilePathField.match

Необязательный. Регулярное выражение как строка, которое FilePathField использует как фильтр названий. Регулярное выражение применяется к названию файла, а не к полному пути. Например: "foo.*\.txt$", соответствует foo23.txt но отфильтрует bar.txt или foo23.gif.

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)

Число с плавающей точкой представленное объектом float.

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

FloatField или DecimalField

FloatField иногда путают с DecimalField. Хоть оба и представляют вещественные числа, они делают это по разному. FloatField использует тип float в Python, в то время как DecimalField использует тип Decimal. Подробности смотрите в документации Python модуля decimal.

ImageField

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

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

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

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

ImageField.height_field

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

ImageField.width_field

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

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

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

Виджет форма для этого поля - ClearableFileInput.

IntegerField

class IntegerField(**options)

Число. Значение от -2147483648 до 2147483647 для всех поддерживаемых баз данных Django. Форма использует виджет NumberInput при localize равном False, иначе TextInput.

GenericIPAddressField

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

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

Определяет формат IP адреса. Принимает значение 'both' (по умолчанию), 'IPv4' или 'IPv6'. Значение не чувствительно регистру.

GenericIPAddressField.unpack_ipv4

Преобразует адрес IPv4. Если эта опция установлена, адрес ::ffff::192.0.2.1 будет преобразован в 192.0.2.1. По-умолчанию отключена. Может быть использовано, если protocol установлен в 'both'.

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

NullBooleanField

class NullBooleanField(**options)

Как и BooleanField, но принимает значение NULL. Используете его вместо BooleanField с null=True. Форма использует виджет NullBooleanSelect.

PositiveIntegerField

class PositiveIntegerField(**options)

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options)

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

SlugField

class SlugField(max_length=50, **options)

Slug – газетный термин. “Slug” – это короткое название-метка, которое содержит только буквы, числа, подчеркивание или дефис. В основном используются в URL.

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

Устанавливает Field.db_index в True, если аргумент явно не указан.

Обычно значение SlugField создается на основе какого-то другого значения(например, название статьи). Это может работать автоматически в интерфейсе администрации благодаря параметру prepopulated_fields.

SlugField.allow_unicode
Добавлено в Django 1.9.

При True поле может принимать Unicode символы кроме ASCII. Значение по умолчанию – False.

SmallIntegerField

class SmallIntegerField(**options)

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

TextField

class TextField(**options)

Большое текстовое поле. Форма использует виджет Textarea.

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

Пользователям MySQL

Если вы используете это поле с MySQLdb 1.2.1p2 и utf8_bin “collation” (которое не является значением по умолчанию), могут быть некоторые проблемы. Смотрите советы при работе с MySQL для подробностей.

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options)

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

Форма использует виджет TextInput. Интерфейс администратора также использует немного JavaScript.

URLField

class URLField(max_length=200, **options)

Поле CharField для URL.

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

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

UUIDField

Добавлено в Django 1.8.
class UUIDField(**options)

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

UUID является хорошей альтернативой 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)

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

Изменено в Django 1.9:

on_delete может теперь использоваться как второй позиционный аргумент (ранее использовался только как именованный аргумент). Будет обязательным аргументом в Django 2.0.

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

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

from django.db import models

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

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

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

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

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

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

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

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

Параметры

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

ForeignKey.on_delete

Когда объект, на который ссылается ForeignKey, удаляется, Django эмулирует поведение SQL правил, указанных в аргументе on_delete. Например, если ваше поле ForeignKey может содержать NULL и вы хотите, чтобы оно устанавливалось в 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

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

  • PROTECT

    Препятствует удалению связанного объекта вызывая исключение django.db.models.ProtectedError`(подкласс :exc:`django.db.IntegrityError).

  • SET_NULL

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

  • SET_DEFAULT

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

  • SET()

    Устанавливает ForeignKey в значение указанное в SET(). Если указан выполняемый объект, результат его выполнения. Вызываемый объект можно использовать, чтобы избежать запросов во время импорта models.py:

    from django.conf import settings
    from django.contrib.auth import get_user_model
    from django.db import models
    
    def get_sentinel_user():
        return get_user_model().objects.get_or_create(username='deleted')[0]
    
    class MyModel(models.Model):
        user = models.ForeignKey(
            settings.AUTH_USER_MODEL,
            on_delete=models.SET(get_sentinel_user),
        )
    
  • DO_NOTHING

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

Указание функции может быть полезно, если используется объект Python datetime для фильтрации. Например:

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

limit_choices_to = limit_pub_date_choices

Вместо словаря можете использовать объект Q или функцию, которая возвращает такой объект, для создания сложных запросов. Однако, если limit_choices_to объект Q, он будет использован в интерфейсе администратора, только если поле не находится в raw_id_fields класса ModelAdmin для этой модели.

Примечание

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

ForeignKey.related_name

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

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

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

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

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(
        Article,
        on_delete=models.CASCADE,
        related_name="tags",
        related_query_name="tag",
    )
    name = models.CharField(max_length=255)

# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")
ForeignKey.to_field

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

ForeignKey.db_constraint

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

  • Вам досталась в наследство нецелостная база данных

  • Вы используете шардинг базы данных.

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

ForeignKey.swappable

Управляет поведением миграций, если ForeignKey ссылается на подменяемую(swappable) модель. При True - значение по умолчанию - если ForeignKey ссылается на модель, указанную через settings.AUTH_USER_MODEL (или другую настройку, определяющую какую модель использовать), связь в миграции будет использовать настройку, а не саму модель.

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

Указав False, вы не сможете ссылаться на подменяемую модель даже после того, как её подменили. False означает, что миграция, содержащая этот ForeignKey, будет указывать на конкретную модель, которую вы укажите (и пользователь вашего приложения получит ошибку, если попытается выполнить с моделью User, которую вы не поддерживаете, например).

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

ManyToManyField

class ManyToManyField(othermodel, **options)

Связь многие-ко-многим. Принимает позиционный аргумент: класс связанной модели. Работает так же как и 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. Вместо этого подразумевается, что :class:`ManyToManyField`симметрично – то есть, если я твой друг, то и ты мне друг.

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

ManyToManyField.through

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

Обычно используют для хранения дополнительных данных.

Если вы не указали 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 принимает двух-элементный кортеж ('field1', 'field2'), где field1 – название внешнего ключа, который ссылается на модель, которая содержит ManyToManyField (в нашем примере group), а field2 – внешний ключ, который ссылается на целевую модель (в нашем примере person).

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

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

  • Вам досталась в наследство нецелостная база данных

  • Вы используете шардинг базы данных.

Нельзя указать db_constraint и through одновременно.

ManyToManyField.swappable

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

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

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

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

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

OneToOneField

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

Связь один-к-одному. Работает так же, как и ForeignKey с unique=True, но “обратная” связь возвращает один объект.

Изменено в Django 1.9:

on_delete может теперь использоваться как второй позиционный аргумент (ранее использовался только как именованный аргумент). Будет обязательным аргументом в Django 2.0.

В основном применяется как первичный ключ модели, которая “расширяет” другую модель. Например, Multi-table наследование работает через неявное добавление связи один-к-одному от дочерней модели к родительской.

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

При True и связанной модели, которая наследуется от другой модели, определяет, что должна сохраняться связь на родительскую модель, а не поле OneToOneField дочерней модели, которое используется для организации наследования моделей.

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

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

class Field

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

Таким образом поле является фундаментальной частью различных API Django, в частности, models и querysets.

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

Field – дочерний класс RegisterLookupMixin, что позволяет регистрировать Transform и Lookup, чтобы использовать в QuerySet (например, field_name__exact="foo"). Все встроенные фильтры зарегистрированы по умолчанию.

Все встроенные поля Django, например CharField, наследуются от Field. Если вы хотите создать свое поле, можно унаследоваться от любого встроенного поля, или от Field. Подробности смотрите в Создание собственных полей для модели.

description

Читабельное описание поля, например, для приложения django.contrib.admindocs.

Может использовать форматирование:

description = _("String (up to %(max_length)s)")

Аргументы будут подставляется из значений __dict__ поля.

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

get_internal_type()

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

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

db_type(connection)

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

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

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

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

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

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

При запросе используются методы get_db_prep_value() и get_prep_value():

get_prep_value(value)

value – значение атрибута поля модели. Метод должен вернуть значение, которое можно использовать как параметр в запросе.

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

get_db_prep_value(value, connection, prepared=False)

Преобразует value в значение для бэкенда базы данных. По умолчанию возвращает value, если prepared=True, иначе – результат get_prep_value().

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

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

from_db_value(value, expression, connection, context)
Добавлено в Django 1.8.

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

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

Смотрите Преобразование значений базы данных в объекты Python.

Примечание

Для повышения производительности поля, которые не используют from_db_value, не содержат пустую реализацию этого метода (все поля Django). По этому нет необходимости вызывать super в вашем методе.

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

get_db_prep_save(value, connection)

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

pre_save(model_instance, add)

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

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

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

Смотрите Обработка данных перед сохранением.

При использовании фильтрации по полю, может быть необходимо “приготовить” значение. Django используется для этого два метода:

get_prep_lookup(lookup_type, value)

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

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

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

get_db_prep_lookup(lookup_type, value, connection, prepared=False)

Аналогичен get_db_prep_value(), но используется при фильтрации.

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

Поля часто принимает значения разных типов из сериализатора, или формы

to_python(value)

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

Смотрите Преобразование значений базы данных в объекты Python.

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

value_to_string(obj)

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

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

При использовании django.forms.ModelForm Field должно указать, какое поле формы необходимо использовать для его представления в форме:

formfield(form_class=None, choices_form_class=None, **kwargs)

Возвращает django.forms.Field поля модели для ModelForm.

По умолчанию, если form_class и choices_form_class равны None, возвращает CharField. Если указан choices_form_class, вернет TypedChoiceField.

Смотрите Определение поля формы для поля модели.

deconstruct()

Возвращает 4-х элементный кортеж с информацией, как воссоздать поле:

  1. Название поля в модели.

  2. Путь для импорта класса поля (например, "django.db.models.IntegerField"). Должен возвращаться максимально переносимый между платформами и версиями вариант.

  3. Список позиционных аргументов.

  4. Словарь именованных аргументов.

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

Атрибуты поля

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

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

Атрибуты поля

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

Атрибуты связывающих полей

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

Field.many_to_many

Флаг, который содержит True, если поле содержит связь многие-ко-многим, иначе False. Единственное поле Django, которое содержит True – это ManyToManyField.

Field.many_to_one

Флаг, который содержит True, если поле содержит связь многие-к-одному, такие как ForeignKey, иначе False.

Field.one_to_many

Флаг, который содержит True, если поле содержит связь один-ко-многим, такие как GenericRelation или обратная связь ForeignKey, иначе False.

Field.one_to_one

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

Field.related_model

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