Встроенные поля

class Field(**kwargs)[исходный код]
Когда вы создаете класс Form, наиболее важной частью является определение полей формы. Каждое поле имеет пользовательскую логику валидации, а также несколько других крючков.

Field.clean(value)[исходный код]
Хотя основной способ использования классов Field - это классы Form, вы также можете инстанцировать их и использовать напрямую, чтобы лучше понять, как они работают. Каждый экземпляр Field имеет метод clean(), который принимает один аргумент и либо вызывает исключение django.core.exceptions.ValidationError, либо возвращает чистое значение:

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
'foo@example.com'
>>> f.clean('invalid email address')
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']
Аргументы по основному полю
Каждый конструктор класса Field принимает по крайней мере эти аргументы. Некоторые классы Field принимают дополнительные, специфические для конкретной области аргументы, но следующие должны всегда приниматься:

required
Field.required
По умолчанию каждый класс Field предполагает, что значение является обязательным, поэтому если вы передадите пустое значение – либо None, либо пустую строку ("") – то clean() вызовет исключение ValidationError:

>>> from django import forms
>>> f = forms.CharField()
>>> f.clean('foo')
'foo'
>>> f.clean('')
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(' ')
' '
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
Чтобы указать, что поле не обязательно, передайте required=False в конструктор Field:

>>> f = forms.CharField(required=False)
>>> f.clean('foo')
'foo'
>>> f.clean('')
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
Если Field имеет required=False и вы передаете clean() пустое значение, то clean() вернет нормализованное пустое значение, а не вызовет ValidationError. Для CharField это вернет empty_value, которое по умолчанию будет пустой строкой. Для других классов Field это может быть None. (Это зависит от конкретного поля).

Виджеты обязательных полей формы имеют HTML-атрибут required. Для отключения атрибута Form.use_required_attribute установите значение False. Атрибут required не включается в формы наборов форм, потому что валидация браузера может быть некорректной при добавлении и удалении наборов форм.

label
Field.label
Аргумент label позволяет указать «дружественную» для человека метку для этого поля. Она используется, когда Field отображается в Form.

Как объяснялось выше в разделе «Вывод форм в формате HTML», метка по умолчанию для Field формируется из имени поля путем преобразования всех знаков подчеркивания в пробелы и перевода первой буквы в верхний регистр. Укажите label, если это поведение по умолчанию не приводит к адекватной метке.

Вот полный пример Form, который реализует label для двух своих полей. Мы указали auto_id=False для упрощения вывода:

>>> from django import forms
>>> class CommentForm(forms.Form):
... name = forms.CharField(label='Your name')
... url = forms.URLField(label='Your website', required=False)
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Your website:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>
label_suffix
Field.label_suffix
Аргумент label_suffix позволяет вам переопределить label_suffix формы на основе каждого поля:

>>> class ContactForm(forms.Form):
... age = forms.IntegerField()
... nationality = forms.CharField()
... captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =')
>>> f = ContactForm(label_suffix='?')
>>> print(f.as_p())
<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" required></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" required></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" required></p>
initial
Field.initial
Аргумент initial позволяет указать начальное значение, которое будет использоваться при отображении данного Field в несвязанном Form.

Чтобы задать динамические начальные данные, см. параметр Form.initial.

Это нужно, когда вы хотите отобразить «пустую» форму, в которой поле инициализировано определенным значением. Например:

>>> from django import forms
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='Your name')
... url = forms.URLField(initial='http://')
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>
Вы можете подумать, почему бы просто не передать словарь начальных значений в качестве данных при отображении формы? Если вы сделаете это, то сработает валидация, и в HTML-вывод будут включены все ошибки валидации:

>>> class CommentForm(forms.Form):
... name = forms.CharField()
... url = forms.URLField()
... comment = forms.CharField()
>>> default_data = {'name': 'Your name', 'url': 'http://'}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required></td></tr>
Именно поэтому значения initial отображаются только для несвязанных форм. Для связанных форм HTML-вывод будет использовать связанные данные.

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

>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='Your name')
... url = forms.URLField(initial='http://')
... comment = forms.CharField()
>>> data = {'name': '', 'url': '', 'comment': 'Foo'}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fall back to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}
Вместо константы вы также можете передать любую вызываемую константу:

>>> import datetime
>>> class DateForm(forms.Form):
... day = forms.DateField(initial=datetime.date.today)
>>> print(DateForm())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>
Вызываемый элемент будет оцениваться только при отображении несвязанной формы, а не при ее определении.

widget
Field.widget
Аргумент widget позволяет указать класс Widget, который будет использоваться при рендеринге этого Field. Дополнительную информацию см. в разделе Виджеты.

help_text
Field.help_text
Аргумент help_text позволяет указать описательный текст для этого Field. Если вы укажете help_text, он будет отображаться рядом с Field, когда Field будет отображаться одним из удобных методов Form (например, as_ul()).

Как и в случае с полем модели help_text, это значение не имеет HTML-выражения в автоматически генерируемых формах.

Вот полный пример Form, который реализует help_text для двух своих полей. Мы указали auto_id=False для упрощения вывода:

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
... subject = forms.CharField(max_length=100, help_text='100 characters max.')
... message = forms.CharField()
... sender = forms.EmailField(help_text='A valid email address, please.')
... cc_myself = forms.BooleanField(required=False)
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
>>> print(f.as_ul()))
<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required></li>
<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself"></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required></p>
<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself"></p>
error_messages
Field.error_messages
Аргумент error_messages позволяет вам переопределить сообщения по умолчанию, которые будет выдавать поле. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые вы хотите отменить. Например, вот сообщение об ошибке по умолчанию:

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean('')
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
А вот пользовательское сообщение об ошибке:

>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
...
ValidationError: ['Please enter your name']
В разделе built-in Field classes ниже каждый Field определяет ключи сообщения об ошибке, которые он использует.

validators
Field.validators
Аргумент validators позволяет вам предоставить список функций валидации для этого поля.

Более подробную информацию см. в validators documentation.

localize
Field.localize
Аргумент localize позволяет локализовать ввод данных формы, а также отображаемый вывод.

Для получения дополнительной информации см. документацию format localization.

disabled
Field.disabled
Булев аргумент disabled, когда он установлен в True, отключает поле формы, использующее HTML-атрибут disabled, так что оно не будет редактироваться пользователями. Даже если пользователь изменит значение поля, переданное на сервер, оно будет проигнорировано в пользу значения из исходных данных формы.

Проверка, изменились ли данные поля
has_changed()
Field.has_changed()[исходный код]
Метод has_changed() используется для определения того, изменилось ли значение поля по сравнению с начальным значением. Возвращает True или False.

Для получения дополнительной информации см. документацию Form.has_changed().

Встроенные классы Field
Естественно, библиотека forms поставляется с набором классов Field, которые представляют общие потребности валидации. В этом разделе документируется каждое встроенное поле.

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

BooleanField
class BooleanField(**kwargs)[исходный код]
Виджет по умолчанию: CheckboxInput
Пустое значение: False
Нормализуется до: Значение Python True или False.
Проверяет, что значение True (например, флажок установлен), если поле имеет значение required=True.
Клавиши сообщения об ошибке: required
Примечание

Поскольку все подклассы Field по умолчанию имеют required=True, условие проверки здесь очень важно. Если вы хотите включить в форму булево значение, которое может быть либо True, либо False (например, установленный или снятый флажок), вы должны не забыть передать required=False при создании BooleanField.

CharField
class CharField(**kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует MaxLengthValidator и MinLengthValidator, если предоставлены max_length и min_length. В противном случае все входы действительны.
Клавиши сообщений об ошибках: required, max_length, min_length
Имеет четыре необязательных аргумента для проверки:

max_length
min_length
Если эти аргументы указаны, они гарантируют, что строка имеет длину не более или не менее заданной.

strip
Если True (по умолчанию), значение будет очищено от ведущих и последующих пробелов.

empty_value
Значение, используемое для представления «пусто». По умолчанию это пустая строка.

ChoiceField
class ChoiceField(**kwargs)[исходный код]
Виджет по умолчанию: Select
Пустое значение: '' (пустая строка).
Нормализуется до: Строка.
Проверяет наличие заданного значения в списке вариантов.
Клавиши сообщений об ошибках: required, invalid_choice
Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено на выбранный вариант.

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

choices
Либо iterable из 2-кортежей, которые будут использоваться в качестве вариантов для этого поля, либо enumeration вариантов, либо итерабель, возвращающая такую итерабель. Этот аргумент принимает те же форматы, что и аргумент choices для поля модели. Более подробную информацию см. в model field reference documentation on choices. Если аргумент является вызываемой переменной, он оценивается каждый раз при инициализации формы поля, а также во время рендеринга. По умолчанию используется пустой список.

TypedChoiceField
class TypedChoiceField(**kwargs)[исходный код]
Как и ChoiceField, за исключением того, что TypedChoiceField принимает два дополнительных аргумента, coerce и empty_value.

Виджет по умолчанию: Select
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Значение типа, указанного в аргументе coerce.
Проверяет, что заданное значение существует в списке вариантов и может быть принудительно введено.
Клавиши сообщений об ошибках: required, invalid_choice
Принимает дополнительные аргументы:

coerce
Функция, которая принимает один аргумент и возвращает принудительное значение. Примеры включают встроенные int, float, bool и другие типы. По умолчанию используется функция тождества. Обратите внимание, что принуждение происходит после проверки ввода, поэтому возможно принуждение к значению, отсутствующему в choices.

empty_value
Значение, используемое для обозначения «пусто». По умолчанию - пустая строка; None - другой распространенный вариант. Заметьте, что это значение не будет принудительно использоваться функцией, заданной в аргументе coerce, поэтому выбирайте его соответствующим образом.

DateField
class DateField(**kwargs)[исходный код]
Виджет по умолчанию: DateInput
Пустое значение: None
Нормализуется до: Объект Python datetime.date.
Проверяет, что заданное значение является либо datetime.date, datetime.datetime, либо строкой, отформатированной в определенном формате даты.
Клавиши сообщений об ошибках: required, invalid
Принимает один необязательный аргумент:

input_formats
Список форматов, используемых для попытки преобразования строки в допустимый объект datetime.date.

Если аргумент input_formats не указан, форматы ввода по умолчанию берутся из DATE_INPUT_FORMATS, если USE_L10N является False, или из активного формата локали DATE_INPUT_FORMATS, если локализация включена. См. также format localization.

DateTimeField
class DateTimeField(**kwargs)[исходный код]
Виджет по умолчанию: DateTimeInput
Пустое значение: None
Нормализуется до: Объект Python datetime.datetime.
Проверяет, что заданное значение является либо datetime.datetime, datetime.date, либо строкой, отформатированной в определенном формате времени даты.
Клавиши сообщений об ошибках: required, invalid
Принимает один необязательный аргумент:

input_formats
Список форматов, используемых для попытки преобразования строки в допустимый объект datetime.datetime, в дополнение к форматам ISO 8601.

Поле всегда принимает строки в формате ISO 8601 в виде дат или аналогичных, распознаваемых parse_datetime(). Некоторые примеры:

* '2006-10-25 14:30:59'
* '2006-10-25T14:30:59'
* '2006-10-25 14:30'
* '2006-10-25T14:30'
* '2006-10-25T14:30Z'
* '2006-10-25T14:30+02:00'
* '2006-10-25'
Если аргумент input_formats не указан, форматы ввода по умолчанию берутся из DATETIME_INPUT_FORMATS и DATE_INPUT_FORMATS, если USE_L10N является False, или из активного формата локали DATETIME_INPUT_FORMATS и ключей DATE_INPUT_FORMATS, если локализация включена. См. также format localization.

DecimalField
class DecimalField(**kwargs)[исходный код]
Виджет по умолчанию: NumberInput, если Field.localize - False, иначе TextInput.
Пустое значение: None
Нормализуется до: A Python decimal.
Проверяет, что заданное значение является десятичной дробью. Использует MaxValueValidator и MinValueValidator, если указаны max_value и min_value. Ведущие и последующие пробельные символы игнорируются.
Клавиши сообщений об ошибках: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits
Сообщения об ошибках max_value и min_value могут содержать %(limit_value)s, которое будет заменено соответствующим пределом. Аналогично, сообщения об ошибках max_digits, max_decimal_places и max_whole_digits могут содержать %(max)s.

Принимает четыре необязательных аргумента:

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

max_digits
Максимальное количество цифр (цифры до десятичной точки плюс цифры после десятичной точки, с вычеркнутыми ведущими нулями), допустимое в значении.

decimal_places
Максимально допустимое количество знаков после запятой.

DurationField
class DurationField(**kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: None
Нормализуется до: A Python timedelta.
Проверяет, что заданное значение является строкой, которая может быть преобразована в timedelta. Значение должно быть между datetime.timedelta.min и datetime.timedelta.max.
Клавиши сообщений об ошибках: required, invalid, overflow.
Принимает любой формат, понимаемый parse_duration().

EmailField
class EmailField(**kwargs)[исходный код]
Виджет по умолчанию: EmailInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует EmailValidator для проверки того, что заданное значение является действительным адресом электронной почты, используя умеренно сложное регулярное выражение.
Клавиши сообщений об ошибках: required, invalid
Имеет три необязательных аргумента max_length, min_length и empty_value, которые работают так же, как и для CharField.

FileField
class FileField(**kwargs)[исходный код]
Виджет по умолчанию: ClearableFileInput
Пустое значение: None
Нормализуется до: Объект UploadedFile, который объединяет содержимое файла и имя файла в один объект.
Может подтвердить, что к форме были привязаны непустые данные файла.
Клавиши сообщений об ошибках: required, invalid, missing, empty, max_length
Имеет два необязательных аргумента для проверки, max_length и allow_empty_file. Если они указаны, то гарантируют, что имя файла не более заданной длины, и что проверка пройдет успешно, даже если содержимое файла пусто.

Чтобы узнать больше об объекте UploadedFile, смотрите file uploads documentation.

Когда вы используете FileField в форме, вы также должны помнить о bind the file data to the form.

Ошибка max_length относится к длине имени файла. В сообщении об ошибке для этой клавиши %(max)d будет заменено на максимальную длину имени файла, а %(length)d - на текущую длину имени файла.

FilePathField
class FilePathField(**kwargs)[исходный код]
Виджет по умолчанию: Select
Пустое значение: '' (пустая строка).
Нормализуется до: Строка.
Проверяет наличие выбранного варианта в списке вариантов.
Клавиши сообщений об ошибках: required, invalid_choice
Поле позволяет выбирать из файлов внутри определенного каталога. Оно принимает пять дополнительных аргументов; только path является обязательным:

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

recursive
Если False (по умолчанию), то в качестве вариантов выбора будет предложено только непосредственное содержимое каталога path. Если True, каталог будет спускаться рекурсивно, и все потомки будут перечислены в качестве вариантов выбора.

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

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

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

FloatField
class FloatField(**kwargs)[исходный код]
Виджет по умолчанию: NumberInput, если Field.localize - False, иначе TextInput.
Пустое значение: None
Нормализуется до: Python float.
Проверяет, что заданное значение является float. Использует MaxValueValidator и MinValueValidator, если заданы max_value и min_value. Допускается использование пробелов в начале и в конце строки, как в функции Python float().
Клавиши сообщений об ошибках: required, invalid, max_value, min_value
Принимает два необязательных аргумента для проверки, max_value и min_value. Они управляют диапазоном значений, допустимых в поле.

ImageField
class ImageField(**kwargs)[исходный код]
Виджет по умолчанию: ClearableFileInput
Пустое значение: None
Нормализуется до: Объект UploadedFile, который объединяет содержимое файла и имя файла в один объект.
Проверяет, что данные файла были привязаны к форме. Также использует FileExtensionValidator для проверки того, что расширение файла поддерживается Pillow.
Клавиши сообщений об ошибках: required, invalid, missing, empty, invalid_image
Использование ImageField требует, чтобы Pillow был установлен с поддержкой форматов изображений, которые вы используете. Если при загрузке изображения вы столкнулись с ошибкой corrupt image, это обычно означает, что Pillow не понимает его формат. Чтобы исправить это, установите соответствующую библиотеку и переустановите Pillow.

Когда вы используете ImageField на форме, вы также должны помнить о bind the file data to the form.

После очистки и проверки поля объект UploadedFile будет иметь дополнительный атрибут image, содержащий экземпляр Pillow Image, используемый для проверки того, является ли файл действительным изображением. Pillow закрывает базовый дескриптор файла после проверки изображения, поэтому, хотя атрибуты, не относящиеся к данным изображения, такие как format, height и width, доступны, методы, обращающиеся к базовым данным изображения, такие как getdata() или getpixel(), не могут быть использованы без повторного открытия файла. Например:

>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
... img = forms.ImageField()
>>> file_data = {'img': SimpleUploadedFile('test.png', <file data>)}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data['img']
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>
Кроме того, UploadedFile.content_type будет обновлен типом содержимого изображения, если Pillow сможет его определить, в противном случае он будет установлен в None.

IntegerField
class IntegerField(**kwargs)[исходный код]
Виджет по умолчанию: NumberInput, если Field.localize - False, иначе TextInput.
Пустое значение: None
Нормализуется до: Целое число Python.
Проверяет, что заданное значение является целым числом. Использует MaxValueValidator и MinValueValidator, если заданы max_value и min_value. Допускается использование пробелов в начале и в конце строки, как в функции Python int().
Клавиши сообщений об ошибках: required, invalid, max_value, min_value
Сообщения об ошибках max_value и min_value могут содержать %(limit_value)s, которое будет заменено соответствующим пределом.

Принимает два необязательных аргумента для проверки:

max_value
min_value
Они управляют диапазоном значений, допустимых в поле.

JSONField
class JSONField(encoder=None, decoder=None, **kwargs)[исходный код]
Поле, которое принимает данные в кодировке JSON для JSONField.

Виджет по умолчанию: Textarea
Пустое значение: None
Нормализуется до: Python-представление значения JSON (обычно в виде dict, list или None), в зависимости от JSONField.decoder.
Проверяет, что заданное значение является допустимым JSON.
Клавиши сообщений об ошибках: required, invalid
Принимает два необязательных аргумента:

encoder
Подкласс json.JSONEncoder для сериализации типов данных, не поддерживаемых стандартным сериализатором JSON (например, datetime.datetime или UUID). Например, вы можете использовать класс DjangoJSONEncoder.

По умолчанию используется json.JSONEncoder.

decoder
Подкласс json.JSONDecoder для десериализации входных данных. Десериализация может потребовать учета того факта, что вы не можете быть уверены в типе входных данных. Например, вы рискуете вернуть datetime, который на самом деле был строкой, просто имеющей тот же формат, который выбран для datetimes.

decoder может использоваться для проверки ввода. Если во время десериализации возникает ошибка json.JSONDecodeError, то возникает ошибка ValidationError.

По умолчанию используется json.JSONDencoder.

Примечание

Если вы используете ModelForm, будут использованы encoder и decoder из JSONField.

Удобные для пользователя формы

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

GenericIPAddressField
class GenericIPAddressField(**kwargs)[исходный код]
Поле, содержащее либо IPv4, либо IPv6-адрес.

Виджет по умолчанию: TextInput
Пустое значение: '' (пустая строка).
Нормализуется до: Строка. Адреса IPv6 нормализуются, как описано ниже.
Проверяет, что заданное значение является действительным IP-адресом.
Клавиши сообщений об ошибках: required, invalid
Нормализация адресов 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. Все символы преобразуются в строчные.

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

protocol
Ограничивает допустимые входы указанным протоколом. Принимаемые значения: both (по умолчанию), IPv4 или IPv6. Соответствие нечувствительно к регистру.

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

MultipleChoiceField
class MultipleChoiceField(**kwargs)[исходный код]
Виджет по умолчанию: SelectMultiple
Пустое значение: [] (пустой список).
Нормализуется до: Список строк.
Проверяет, что каждое значение из заданного списка значений существует в списке вариантов.
Клавиши сообщений об ошибках: required, invalid_choice, invalid_list
Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено на выбранный вариант.

Принимает один дополнительный обязательный аргумент choices, как и ChoiceField.

TypedMultipleChoiceField
class TypedMultipleChoiceField(**kwargs)[исходный код]
Как и MultipleChoiceField, за исключением того, что TypedMultipleChoiceField принимает два дополнительных аргумента, coerce и empty_value.

Виджет по умолчанию: SelectMultiple
Пустое значение: То, что вы указали как empty_value
Нормализуется до: Список значений того типа, который указан в аргументе coerce.
Проверяет, что заданные значения существуют в списке вариантов и могут быть принудительно введены.
Клавиши сообщений об ошибках: required, invalid_choice
Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено на выбранный вариант.

Принимает два дополнительных аргумента, coerce и empty_value, как и для TypedChoiceField.

NullBooleanField
class NullBooleanField(**kwargs)[исходный код]
Виджет по умолчанию: NullBooleanSelect
Пустое значение: None
Нормализуется до: Значение Python True, False или None.
Ничего не проверяет (т.е. никогда не выдает ошибку ValidationError).
NullBooleanField можно использовать с такими виджетами, как Select или RadioSelect, предоставив виджет choices:

NullBooleanField(
widget=Select(
choices=[
('', 'Unknown'),
(True, 'Yes'),
(False, 'No'),
]
)
)
RegexField
class RegexField(**kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует RegexValidator для проверки соответствия заданного значения определенному регулярному выражению.
Клавиши сообщений об ошибках: required, invalid
Принимает один необходимый аргумент:

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

Также принимает max_length, min_length, strip и empty_value, которые работают так же, как и для CharField.

strip
По умолчанию имеет значение False. Если включено, отсечение будет применяться перед проверкой regex.

SlugField
class SlugField(**kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует validate_slug или validate_unicode_slug для проверки того, что заданное значение содержит только буквы, цифры, подчеркивания и дефисы.
Сообщения об ошибках: required, invalid
Это поле предназначено для использования при представлении модели SlugField в формах.

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

allow_unicode
Булево значение, указывающее полю принимать буквы Unicode в дополнение к буквам ASCII. По умолчанию имеет значение False.

empty_value
Значение, используемое для представления «пусто». По умолчанию это пустая строка.

TimeField
class TimeField(**kwargs)[исходный код]
Виджет по умолчанию: TimeInput
Пустое значение: None
Нормализуется до: Объект Python datetime.time.
Проверяет, что заданное значение является либо datetime.time, либо строкой, отформатированной в определенном формате времени.
Клавиши сообщений об ошибках: required, invalid
Принимает один необязательный аргумент:

input_formats
Список форматов, используемых для попытки преобразования строки в допустимый объект datetime.time.

Если аргумент input_formats не указан, форматы ввода по умолчанию берутся из TIME_INPUT_FORMATS, если USE_L10N является False, или из активного формата локали TIME_INPUT_FORMATS, если локализация включена. См. также format localization.

URLField
class URLField(**kwargs)[исходный код]
Виджет по умолчанию: URLInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует URLValidator для проверки того, что заданное значение является действительным URL.
Клавиши сообщений об ошибках: required, invalid
Имеет три необязательных аргумента max_length, min_length и empty_value, которые работают так же, как и для CharField.

UUIDField
class UUIDField(**kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: None
Нормализуется до: Объект UUID.
Клавиши сообщений об ошибках: required, invalid
Это поле принимает любой формат строки, принятый в качестве аргумента hex в конструкторе UUID.

Немного сложные встроенные Field классы
ComboField
class ComboField(**kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: '' (пустая строка).
Нормализуется до: Строка.
Проверяет заданное значение по каждому из полей, указанных в качестве аргумента в ComboField.
Клавиши сообщений об ошибках: required, invalid
Принимает один дополнительный необходимый аргумент:

fields
Список полей, которые должны быть использованы для проверки значения поля (в порядке их предоставления).

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('test@example.com')
'test@example.com'
>>> f.clean('longemailaddress@example.com')
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
MultiValueField
class MultiValueField(fields=(), **kwargs)[исходный код]
Виджет по умолчанию: TextInput
Пустое значение: '' (пустая строка).
Нормализуется до: тип, возвращаемый методом compress подкласса.
Проверяет заданное значение по каждому из полей, указанных в качестве аргумента в MultiValueField.
Клавиши сообщений об ошибках: required, invalid, incomplete
Агрегирует логику нескольких полей, которые вместе дают одно значение.

Это поле является абстрактным и должно быть подклассом. В отличие от полей с одним значением, подклассы MultiValueField не должны реализовывать clean(), а вместо этого - реализовывать compress().

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

fields
Кортеж полей, значения которых очищаются и впоследствии объединяются в одно значение. Каждое значение поля очищается соответствующим полем в fields – первое значение очищается первым полем, второе значение очищается вторым полем и т.д. Когда все поля очищены, список чистых значений объединяется в одно значение по compress().

Также принимает некоторые необязательные аргументы:

require_all_fields
По умолчанию установлено значение True, в этом случае будет выдана ошибка валидации required, если для какого-либо поля не указано значение.

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

Сообщение об ошибке по умолчанию incomplete может быть определено для подкласса MultiValueField, или могут быть определены различные сообщения для каждого отдельного поля. Например:

from django.core.validators import RegexValidator

class PhoneField(MultiValueField):
def __init__(self, **kwargs):
# Define one message for all fields.
error_messages = {
'incomplete': 'Enter a country calling code and a phone number.',
}
# Or define a different message for each field.
fields = (
CharField(
error_messages={'incomplete': 'Enter a country calling code.'},
validators=[
RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'),
],
),
CharField(
error_messages={'incomplete': 'Enter a phone number.'},
validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')],
),
CharField(
validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')],
required=False,
),
)
super().__init__(
error_messages=error_messages, fields=fields,
require_all_fields=False, **kwargs
)
widget
Должен быть подклассом django.forms.MultiWidget. Значение по умолчанию TextInput, что, вероятно, не очень полезно в данном случае.

compress(data_list)[исходный код]
Принимает список допустимых значений и возвращает «сжатую» версию этих значений - в одном значении. Например, SplitDateTimeField является подклассом, который объединяет поле времени и поле даты в объект datetime.

Этот метод должен быть реализован в подклассах.

SplitDateTimeField
class SplitDateTimeField(**kwargs)[исходный код]
Виджет по умолчанию: SplitDateTimeWidget
Пустое значение: None
Нормализуется до: Объект Python datetime.datetime.
Проверяет, что заданное значение является datetime.datetime или строкой, отформатированной в определенном формате времени даты.
Клавиши сообщений об ошибках: required, invalid, invalid_date, invalid_time
Принимает два необязательных аргумента:

input_date_formats
Список форматов, используемых для попытки преобразования строки в допустимый объект datetime.date.

Если аргумент input_date_formats не указан, используются форматы ввода по умолчанию для DateField.

input_time_formats
Список форматов, используемых для попытки преобразования строки в допустимый объект datetime.time.

Если аргумент input_time_formats не указан, используются форматы ввода по умолчанию для TimeField.

Поля, которые обрабатывают отношения
Для представления отношений между моделями доступны два поля: ModelChoiceField и ModelMultipleChoiceField. Оба эти поля требуют одного параметра queryset, который используется для создания вариантов для поля. При проверке формы эти поля помещают либо один объект модели (в случае ModelChoiceField), либо несколько объектов модели (в случае ModelMultipleChoiceField) в словарь cleaned_data формы.

Для более сложного использования можно указать queryset=None при объявлении поля формы и затем заполнить queryset в методе __init__() формы:

class FooMultipleChoiceForm(forms.Form):
foo_select = forms.ModelMultipleChoiceField(queryset=None)

def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.fields['foo_select'].queryset = ...
И ModelChoiceField, и ModelMultipleChoiceField имеют атрибут iterator, который определяет класс, используемый для итерации по набору запросов при генерации вариантов. Подробности см. в разделе Итерация выбора отношений.

ModelChoiceField
class ModelChoiceField(**kwargs)[исходный код]
Виджет по умолчанию: Select
Пустое значение: None
Нормализуется до: Экземпляр модели.
Проверяет, существует ли заданный id в наборе запросов.
Клавиши сообщений об ошибках: required, invalid_choice
Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено на выбранный вариант.

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

Требуется один аргумент:

queryset
Объект модели QuerySet>, из которого берутся варианты выбора для поля и который используется для проверки выбора пользователя. Он оценивается при отображении формы.

ModelChoiceField также принимает два необязательных аргумента:

empty_label
По умолчанию виджет <select>, используемый ModelChoiceField, будет иметь пустой выбор в верхней части списка. Вы можете изменить текст этой метки (который по умолчанию равен "---------") с помощью атрибута empty_label, или вы можете полностью отключить пустую метку, установив empty_label в None:

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
Обратите внимание, что если требуется ModelChoiceField и имеет начальное значение по умолчанию, то пустой выбор не создается (независимо от значения empty_label).

to_field_name
Этот необязательный аргумент используется для указания поля, которое будет использоваться в качестве значения выбора в виджете поля. Убедитесь, что это уникальное поле для модели, иначе выбранное значение может соответствовать более чем одному объекту. По умолчанию оно установлено в None, в этом случае будет использоваться первичный ключ каждого объекта. Например:

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)
будет давать:

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>
и:

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
будет давать:

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>
ModelChoiceField также имеет атрибут:

iterator
Класс итератора, используемый для генерации вариантов полей из queryset. По умолчанию ModelChoiceIterator.

Метод __str__() модели будет вызван для генерации строковых представлений объектов для использования в выборе поля. Чтобы обеспечить индивидуальные представления, создайте подкласс ModelChoiceField и переопределите label_from_instance. Этот метод получает объект модели и должен вернуть строку, подходящую для его представления. Например:

from django.forms import ModelChoiceField

class MyModelChoiceField(ModelChoiceField):
def label_from_instance(self, obj):
return "My Object #%i" % obj.id
Changed in Django 4.0:
Добавлена поддержка содержания %(value)s в сообщении об ошибке invalid_choice.

ModelMultipleChoiceField
class ModelMultipleChoiceField(**kwargs)[исходный код]
Виджет по умолчанию: SelectMultiple
Пустое значение: Пустое QuerySet (self.queryset.none())
Нормализуется до: A QuerySet экземпляров модели.
Проверяет, что каждый идентификатор из заданного списка значений существует в наборе запросов.
Клавиши сообщений об ошибках: required, invalid_list, invalid_choice, invalid_pk_value
Сообщение invalid_choice может содержать %(value)s, а сообщение invalid_pk_value может содержать %(pk)s, которые будут заменены соответствующими значениями.

Позволяет выбрать один или несколько объектов модели, подходящих для представления отношения «многие-ко-многим». Как и в случае с ModelChoiceField, вы можете использовать label_from_instance для настройки представлений объектов.

Требуется один аргумент:

queryset
То же самое, что и ModelChoiceField.queryset.

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

to_field_name
То же самое, что и ModelChoiceField.to_field_name.

ModelMultipleChoiceField также имеет атрибут:

iterator
То же самое, что и ModelChoiceField.iterator.

Итерация выбора отношений
По умолчанию ModelChoiceField и ModelMultipleChoiceField используют ModelChoiceIterator для генерации своего поля choices.

При итерации ModelChoiceIterator выдает 2 кортежа выбора, содержащие экземпляры ModelChoiceIteratorValue в качестве первого элемента value в каждом выборе. ModelChoiceIteratorValue оборачивает значение выбора, сохраняя ссылку на исходный экземпляр модели, которая может быть использована в пользовательских реализациях виджетов, например, для добавления data-* attributes к элементам <option>.

Например, рассмотрим следующие модели:

from django.db import models

class Topping(models.Model):
name = models.CharField(max_length=100)
price = models.DecimalField(decimal_places=2, max_digits=6)

def __str__(self):
return self.name

class Pizza(models.Model):
topping = models.ForeignKey(Topping, on_delete=models.CASCADE)
Вы можете использовать подкласс виджета Select для включения значения Topping.price в качестве HTML-атрибута data-price для каждого элемента <option>:

from django import form