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

Этот документ содержит все ссылки 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, django-admin sqlindexes выведет инструкцию CREATE INDEX для этого поля.

db_tablespace

Field.db_tablespace

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

default

Field.default

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

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

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

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

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

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

editable

Field.editable

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

error_messages

Field.error_messages

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

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

Ключ сообщения об ошибке 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, которое автоматически инкрементируется в соответствии с доступными идентификаторами. Обычно вам не нужно использовать его напрямую; поле первичного ключа будет автоматически добавлено в вашу модель, если вы не укажете иначе. См. Автоматические поля первичного ключа.

BigIntegerField

class BigIntegerField(**options) [source]

64-битовое целое число, очень похоже на IntegerField, за исключением того, что оно гарантированно поместится в числа от -9223372036854775808 до 9223372036854775807. Виджет формы по умолчанию для этого поля — TextInput.

BinaryField

class BinaryField(**options) [source]

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

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

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

DateField.auto_now_add

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

• Для DateField: default=date.today - из datetime.date.today()
• Для DateTimeField: default=timezone.now - из django.utils.timezone.now()

По умолчанию для этого поля используется виджет формы TextInput. В админке добавляется календарь JavaScript и ярлык «Сегодня». Включает дополнительный ключ сообщения об ошибке invalid_date

Опции auto_now_add, auto_now, и default взаимно исключаются. Любое сочетание этих опций приведет к ошибке.

DateTimeField

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

Дата и время, представленные в Python экземпляром datetime.datetime. Принимает те же дополнительные аргументы, что и DateField.

По умолчанию для этого поля используется виджет формы TextInput. В админке используется два отдельных виджета TextInput с ярлыками JavaScript.

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options) [source]

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

DecimalField.max_digits

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

DecimalField.decimal_places

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

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

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

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

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

По умолчанию для этого поля используется виджет формы NumberInput, когда localize равно False, или TextInput в противном случае.

DurationField

class DurationField(**options) [source]

Поле для хранения периодов времени — моделируется в Python с помощью timedelta. При использовании с PostgreSQL используется тип данных interval, а в Oracle — INTERVAL DAY(9) TO SECOND(6). В противном случае используется значение в микросекундах bigint.

EmailField

class EmailField(max_length=254, **options) [source]

Поле CharField, проверяющее, является ли значение корректным адресом электронной почты. Для валидации используется EmailValidator.

FileField

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

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

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

FileField.upload_to

upload_to был обязательным в более старых версиях Django.

Локальный путь к файловой системе, который будет добавлен к вашему параметру MEDIA_ROOT для определения значения атрибута url.

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

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

Два аргумента, которые будут переданы:

Аргумент	Описание
instance	Экземпляр модели, где определено поле FileField. То есть, конкретный экземпляр, где прикрепляется текущий файл. В большинстве случаев этот объект ещё не был сохранён в базе данных, поэтому, если он использует значение по умолчанию AutoField, у него может ещё не быть значения для поля первичного ключа.
filename	Имя файла, которое изначально было дано файлу. Может или не может быть учтено при определении конечного пути назначения.

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 в качестве прокси для доступа к базовому файлу. Помимо функциональности, унаследованной от django.core.files.File, в этом классе есть несколько атрибутов и методов, которые можно использовать для взаимодействия с данными файла:

FieldFile.url

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

FieldFile.open(mode='rb') [source]

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

FieldFile.close() [source]

Ведёт себя как стандартный метод Python file.close() и закрывает файл, связанный с этим экземпляром.

FieldFile.save(name, content, save=True) [source]

Этот метод принимает имя файла и содержимое файла и передает их классу хранения для поля, а затем связывает сохранённый файл с полем модели. Если вы хотите вручную связать данные файла с экземплярами FileField в вашей модели, используется метод save() для сохранения этих данных файла.

Требует два обязательных аргумента: name, которое является именем файла, и content, который содержит содержимое файла. Необязательный аргумент save управляет сохранением экземпляра модели после изменения файла, связанного с этим полем. По умолчанию True.

Обратите внимание, что аргумент content должен быть экземпляром django.core.files.File, а не встроенного объекта файла Python. Вы можете создать File из существующего объекта файла Python так:

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/path/to/hello.world')
myfile = File(f)

Или вы можете создать его из строки Python так:

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

Дополнительная информация см. в Управление файлами.

FieldFile.delete(save=True) [source]

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

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

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

FilePathField

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

A CharField, варианты которого ограничены именами файлов в определённой директории на файловой системе. Имеет три специальных аргумента, из которых первый необходим:

FilePathField.path

Необходимый. Абсолютный путь к директории, из которой этот FilePathField должен получать свои варианты. Пример: "/home/images".

FilePathField.match

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

FilePathField.recursive

Необязательный. Либо True либо False. По умолчанию False. Указывает, должны ли включаться все подкаталоги каталога path.

FilePathField.allow_files

Необязательный. Либо True либо False. По умолчанию True. Указывает, должны ли включаться файлы в указанном расположении. Либо это, либо allow_folders должно быть True.

FilePathField.allow_folders

Необязательный. Либо True либо False. По умолчанию False. Указывает, должны ли включаться папки в указанном расположении. Либо это, либо allow_files должно быть True.

Конечно, эти аргументы можно использовать вместе.

Единственный потенциальный момент — то, что match применяется к имени базового файла, а не к полному пути. Итак, этот пример:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…будет соответствовать /home/images/foo.png, но не /home/images/foo/bar.png, потому что match применяется к имени базового файла (foo.png и bar.png).

FilePathField экземпляры создаются в вашей базе данных как varchar столбцы с максимальной длиной по умолчанию 100 символов. Как и другие поля, вы можете изменить максимальную длину, используя аргумент max_length.

FloatField

class FloatField(**options) [source]

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

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

ImageField

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

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

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

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

ImageField.height_field

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

ImageField.width_field

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

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

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

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

IntegerField

class IntegerField(**options) [source]

Целое число. Значения от -2147483648 до 2147483647 безопасны во всех базах данных, поддерживаемых Django. Поле по умолчанию для этого поля — виджет NumberInput, когда localize равен False, или TextInput в противном случае.

IPAddressField

class IPAddressField(**options) [source]

IP-адрес в строковом формате (например, “192.0.2.30”). Поле по умолчанию для этого поля — виджет TextInput.

GenericIPAddressField

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

Адрес IPv4 или IPv6 в строковом формате (например, 192.0.2.30 или 2a02:42fe::4). Поле по умолчанию для этого поля — виджет TextInput.

Нормализация адреса IPv6 следует RFC 4291#section-2.2 пункту 2.2, включая использование формата IPv4, предложенного в абзаце 3 этого пункта, например, ::ffff:192.0.2.0. Например, 2001:0::0:01 будет нормализовано до 2001::1, а ::ffff:0a0a:0a0a до ::ffff:10.10.10.10. Все символы преобразуются в нижний регистр.

GenericIPAddressField.protocol

Ограничивает допустимые значения указанным протоколом. Допустимые значения — 'both' (по умолчанию), 'IPv4' или 'IPv6'. Сопоставление не учитывает регистр.

GenericIPAddressField.unpack_ipv4

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

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

NullBooleanField

class NullBooleanField(**options) [source]

Подобно BooleanField, но допускает значение NULL в качестве одного из вариантов. Используйте его вместо BooleanField с null=True. Поле по умолчанию для этого поля — виджет NullBooleanSelect.

PositiveIntegerField

class PositiveIntegerField(**options) [source]

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options) [source]

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

SlugField

class SlugField(max_length=50, **options) [source]

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

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

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

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

SmallIntegerField

class SmallIntegerField(**options) [source]

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

TextField

class TextField(**options) [source]

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

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

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

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

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

from django.db import models

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

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

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

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

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

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

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

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

Аргументы

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

ForeignKey.limit_choices_to

Устанавливает ограничение на доступные варианты для этого поля при отображении этого поля с помощью ModelForm или админа (по умолчанию доступны все объекты в наборе запросов). Можно использовать словарь, объект Q или вызываемый объект, возвращающий словарь или объект Q.

Например:

staff_member = models.ForeignKey(User, 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 модели.

В предыдущих версиях Django не разрешалось передавать вызываемый объект как значение для limit_choices_to.

Примечание

Если используется вызываемый объект для limit_choices_to, он будет вызываться каждый раз при создании новой формы. Он также может быть вызван при валидации модели, например, командными утилитами или админом. Админ строит наборы запросов для валидации входных данных формы в различных граничных случаях несколько раз, поэтому существует возможность, что ваш вызываемый объект может быть вызван несколько раз.

ForeignKey.related_name

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

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

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

ForeignKey.related_query_name

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

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(Article, 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

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

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

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

ForeignKey.on_delete

При удалении объекта, на который ссылается ForeignKey, Django по умолчанию эмулирует поведение SQL-ограничения ON DELETE CASCADE и также удаляет объект, содержащий ForeignKey. Это поведение можно переопределить, указав аргумент on_delete. Например, если у вас есть необязательная ссылка ForeignKey и вы хотите, чтобы она была установлена в null при удалении связанного объекта:

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

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

• CASCADE [source]

  Каскадное удаление; значение по умолчанию.

• PROTECT [source]

  Запрещает удаление связанного объекта, вызывая ProtectedError, подкласс django.db.IntegrityError.

• SET_NULL [source]

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

• SET_DEFAULT [source]

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

• SET() [source]

  Установить 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 [source]

  Не выполнять никаких действий. Если ваш поставщик баз данных применяет целостность ссылок, это приведёт к IntegrityError, пока вы вручную не добавите SQL-ограничение целостности к полю базы данных (возможно, используя начальные SQL-запросы).

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

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

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)
    person = models.ForeignKey(Person)
    inviter = models.ForeignKey(Person, 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 только если уверены, что ваша модель всегда должна указывать на подставленную модель — например, если это модель профиля, специально разработанная для вашей пользовательской модели.

В случае сомнений оставьте значение по умолчанию False.

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

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

OneToOneField

class OneToOneField(othermodel, 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)
    supervisor = models.OneToOneField(settings.AUTH_USER_MODEL, 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.

Field API reference

class Field [source]

Field является абстрактным классом, представляющим столбец таблицы базы данных. Django использует поля для создания таблицы базы данных (db_type()), для сопоставления типов Python с базой данных (get_prep_value()) и наоборот (from_db_value()), а также для применения Справочник по API поиска (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() [source]

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

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

db_type(connection) [source]

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

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

Когда используется операция поиска на поле, может потребоваться «подготовка» значения. Django предоставляет два метода для этого:

get_prep_lookup(lookup_type, value) [source]

Подготавливает значение 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) [source]

Аналогично get_db_prep_value(), но для выполнения поиска.

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

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

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_form_class задано, возвращается TypedChoiceField.

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

deconstruct() [source]

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

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

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

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

Каждый экземпляр Field содержит несколько атрибутов, которые позволяют просмотреть его поведение. Используйте эти атрибуты вместо isinstance проверок, когда вам нужно написать код, зависящий от функциональности поля. Эти атрибуты можно использовать вместе с Модель._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 будет ссылаться на суперкласс, а не на класс экземпляра.

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

Эти атрибуты используются для запроса кардинальности и других деталей отношения. Эти атрибуты присутствуют во всех полях; однако они будут иметь только значения boolean (а не 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). Если у поля есть общее отношение (например, GenericForeignKey или GenericRelation), тогда related_model будет None.