Ссылка на поля модели

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

Параметры общих полей модели

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

null

Field.null

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

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

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

blank

Field.blank

Если True, поле может быть пустым. Значение по умолчанию — False.

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

choices

Field.choices

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

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

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

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

from django.db import models

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

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

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

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

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

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

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

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

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

db_column

Field.db_column

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

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

db_index

Field.db_index

Если True, для этого поля будет создан индекс базы данных.

db_tablespace

Field.db_tablespace

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

default

Field.default

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

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

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

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

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

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

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

editable

Field.editable

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

error_messages

Field.error_messages

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

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

Эти сообщения об ошибках часто не распространяются на формы. См. Рекомендации по использованию model's error_messages.

help_text

Field.help_text

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

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

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

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

primary_key

Field.primary_key

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

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

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

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

unique

Field.unique

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

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

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

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

unique_for_date

Field.unique_for_date

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

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

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

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

unique_for_month

Field.unique_for_month

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

unique_for_year

Field.unique_for_year

Как unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

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

validators

Field.validators

Список валидаторов, которые нужно выполнить для этого поля. Дополнительная информация в документации по валидаторам.

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

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

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

AutoField

class AutoField(**options) [source]

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

BigAutoField

class BigAutoField(**options) [source]

Целое 64-битное число, подобно AutoField, за исключением того, что оно гарантированно вмещает числа от 1 до 9223372036854775807.

BigIntegerField

class BigIntegerField(**options) [source]

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

BinaryField

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

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

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

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

BinaryField.max_length

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

BooleanField

class BooleanField(**options) [source]

Поле «истина/ложь».

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

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

CharField

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

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

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

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

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

CharField.max_length

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

DateField

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

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

DateField.auto_now

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

Поле обновляется только при вызове Model.save(). Поле не обновляется при внесении изменений в другие поля другими способами, такими как QuerySet.update(), хотя вы можете указать пользовательское значение для поля в таком обновлении.

DateField.auto_now_add

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

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

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

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

DateTimeField

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

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

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

DecimalField

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

Десятичное число с фиксированной точностью, представленное в Python объектом Decimal. Ввод проверяется с помощью DecimalValidator.

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

DecimalField.max_digits

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

DecimalField.decimal_places

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

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

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

А для хранения чисел до примерно одного миллиарда с точностью до 10 десятичных знаков:

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

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

DurationField

class DurationField(**options) [source]

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

EmailField

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

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

FileField

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

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

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

FileField.upload_to

Этот атрибут позволяет задать каталог загрузки и имя файла двумя способами. В обоих случаях значение передаётся методу Storage.save().

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

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to='uploads/')
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

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

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

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

Например:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return 'user_{0}/{1}'.format(instance.user.id, filename)

class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storage

Объект хранилища, который обрабатывает хранение и извлечение файлов. Подробности о том, как предоставить этот объект, см. в разделе Управление файлами.

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

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

1. В файле настроек вам необходимо определить MEDIA_ROOT как полный путь к каталогу, где Django будет хранить загруженные файлы. (Для повышения производительности эти файлы не хранятся в базе данных.) Определите MEDIA_URL как базовый общедоступный URL этого каталога. Убедитесь, что этот каталог доступен для записи пользователем веб-сервера.
2. Добавьте FileField или ImageField в свою модель, определив опцию upload_to, чтобы указать подкаталог MEDIA_ROOT для использования загруженных файлов.
3. В вашу базу данных будет сохранён только путь к файлу (относительно MEDIA_ROOT). Вероятно, вам захочется использовать удобный атрибут url, предоставляемый Django. Например, если ваше поле ImageField называется mug_shot, вы можете получить абсолютный путь к вашему изображению в шаблоне с помощью {{ object.mug_shot.url }}.

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

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

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

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

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

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

FileField и FieldFile

class FieldFile [source]

При обращении к FileField в модели вы получаете экземпляр FieldFile в качестве прокси для доступа к базовому файлу.

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

В дополнение к API, унаследованному от File, например, read() и write(), FieldFile включает несколько методов для взаимодействия с базовым файлом:

FieldFile.name

Имя файла, включая относительный путь от корня Storage связанного FileField.

FieldFile.size

Результат метода базового Storage.size().

FieldFile.url

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

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

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

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

FieldFile.close() [source]

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

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

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

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

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

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

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

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

Дополнительную информацию см. в руководстве по теме Управление файлами.

FieldFile.delete(save=True) [source]

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

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

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

FilePathField

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

A CharField whose choices are limited to the filenames in a certain directory on the filesystem. Has three special arguments, of which the first is required:

FilePathField.path

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

FilePathField.match

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

FilePathField.recursive

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

FilePathField.allow_files

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

FilePathField.allow_folders

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

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

Единственная возможная проблема заключается в том, что match применяется к имени файла, а не к полному пути. Например:

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

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

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

FloatField

class FloatField(**options) [source]

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

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

ImageField

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

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

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

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

ImageField.height_field

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

ImageField.width_field

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

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

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

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

IntegerField

class IntegerField(**options) [source]

Целое число. Значения от -2147483648 до 2147483647 безопасны во всех базах данных, поддерживаемых Django.

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

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

GenericIPAddressField

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

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

Нормализация адресов IPv6 следует разделу 2.2 RFC 4291#section-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=True. Используйте его вместо этого поля, так как оно, вероятно, будет устаревшим в будущих версиях Django.

PositiveIntegerField

class PositiveIntegerField(**options) [source]

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

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options) [source]

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

SlugField

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

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

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

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

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

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

SlugField.allow_unicode

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

SmallIntegerField

class SmallIntegerField(**options) [source]

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

TextField

class TextField(**options) [source]

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

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

TimeField

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

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

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

URLField

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

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

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

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

UUIDField

class UUIDField(**options) [source]

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

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

import uuid
from django.db import models

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

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

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

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

ForeignKey

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

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

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

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

from django.db import models

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

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

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

from django.db import models

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

    class Meta:
        abstract = True

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

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

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

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

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

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

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

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

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

Аргументы

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

ForeignKey.on_delete

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

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

on_delete не создаёт SQL-ограничение в базе данных. Поддержка вариантов каскадного удаления на уровне базы данных может быть реализована позже.

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

• CASCADE [source]

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

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

• PROTECT [source]

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

• SET_NULL [source]

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

• SET_DEFAULT [source]

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

• SET() [source]

  Устанавливает ForeignKey в значение, переданное в SET(), или, если передан вызываемый объект, в результат его вызова. В большинстве случаев для предотвращения выполнения запросов при импорте ваших моделей.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 ON DELETE-ограничение к полю базы данных.

ForeignKey.limit_choices_to

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

Например:

staff_member = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    limit_choices_to={'is_staff': True},
)

приводит к тому, что соответствующее поле в ModelForm отображает только Users с is_staff=True. Это может быть полезно в админском интерфейсе Django.

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

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

limit_choices_to = limit_pub_date_choices

Если limit_choices_to является или возвращает Q object, что полезно для сложных запросов, то он повлияет только на доступные варианты в админском интерфейсе, если поле не указано в raw_id_fields в ModelAdmin для модели.

Примечание

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

ForeignKey.related_name

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

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

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

ForeignKey.related_query_name

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

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

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

Как и related_name, related_query_name поддерживает интерполяцию имени приложения и класса через специальный синтаксис.

ForeignKey.to_field

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

ForeignKey.db_constraint

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

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

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

ForeignKey.swappable

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

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

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

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

ManyToManyField

class ManyToManyField(to, **options) [source]

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

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

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

За кулисами Django создает промежуточную таблицу соединения для представления отношения «многие ко многим». По умолчанию имя этой таблицы генерируется с использованием имени поля «многие ко многим» и имени таблицы для модели, которая его содержит. Поскольку некоторые базы данных не поддерживают имена таблиц определенной длины, эти имена таблиц будут автоматически усечены, и будет использоваться хеш уникальности, например author_books_9cdf. Вы можете вручную указать имя таблицы соединения с помощью опции db_table.

Аргументы

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

ManyToManyField.related_name

То же, что и ForeignKey.related_name.

ManyToManyField.related_query_name

То же, что и ForeignKey.related_query_name.

ManyToManyField.limit_choices_to

То же, что и ForeignKey.limit_choices_to.

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

ManyToManyField.symmetrical

Используется только при определении 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, on_delete=models.CASCADE)
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    inviter = models.ForeignKey(
        Person,
        on_delete=models.CASCADE,
        related_name="membership_invites",
    )
    invite_reason = models.CharField(max_length=64)

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

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

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

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

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

Ошибка возникает при передаче как db_constraint, так и through.

ManyToManyField.swappable

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

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

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

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

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

OneToOneField

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

Связь «один к одному». По концепции это похоже на ForeignKey с unique=True, но обратная сторона связи будет напрямую возвращать единственный объект.

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

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

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

В следующем примере:

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

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

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

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

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

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

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

OneToOneField.parent_link

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

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

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

class Field [source]

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

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

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

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

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

description

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

Описание может быть в виде:

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

где аргументы интерполируются из __dict__ поля.

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

get_internal_type() [source]

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

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

db_type(connection) [source]

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

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

rel_db_type(connection) [source]

Возвращает тип данных столбца базы данных для полей, таких как ForeignKey и OneToOneField , которые указывают на Field, с учетом connection.

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

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

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

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

get_prep_value(value) [source]

value — текущее значение атрибута модели, и метод должен вернуть данные в формате, подготовленном для использования в качестве параметра в запросе.

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

get_db_prep_value(value, connection, prepared=False) [source]

Преобразует value в значение, специфичное для бэкенда. По умолчанию возвращает value , если prepared=True , и get_prep_value(), если False.

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

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

from_db_value(value, expression, connection)

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

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

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

Примечание

Из соображений производительности, from_db_value не реализуется как no-op для полей, которые не требуют этого (все поля Django). Следовательно, вы не можете вызвать super в своем определении.

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

get_db_prep_save(value, connection) [source]

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

pre_save(model_instance, add) [source]

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

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

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

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

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

to_python(value) [source]

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

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

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

value_from_object(obj) [source]

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

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

value_to_string(obj) [source]

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

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

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

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

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

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

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

deconstruct() [source]

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

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

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

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

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

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

Field.auto_created

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

Field.concrete

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

Field.hidden

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

Примечание

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

Field.is_relation

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

Field.model

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

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

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

Field.many_to_many

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

Field.many_to_one

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

Field.one_to_many

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

Field.one_to_one

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

Field.related_model

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