Поля форм

class Field(**kwargs) [source]

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

Field.clean(value) [source]

Хотя основное применение классов Field заключается в классах Form, вы также можете их инстанцировать и использовать напрямую, чтобы лучше понять их работу. Каждый экземпляр Field имеет метод clean(), который принимает один аргумент и либо вызывает исключение django.forms.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 принимают дополнительные аргументы, специфичные для поля, но следующие должны всегда приниматься:

Требовательность

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, это будет пустая строка. Для других классов Field, это может быть None. (Это зависит от поля.)

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

Метка

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>

Приставка к метке

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>

Начальное значение

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>

Вызываемый объект будет вычислен только при отображении свободной формы, а не при её определении.

Виджет

Field.widget

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

Текст справки

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>

Сообщения об ошибках

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']

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

Валидаторы

Field.validators

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

Дополнительная информация приведена в документации по валидаторам.

Локализация

Field.localize

Аргумент localize включает локализованный ввод данных формы, а также вывод.

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

Отключено

Field.disabled

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

Проверка изменений данных поля

Проверка изменений

Field.has_changed() [source]

Метод has_changed() используется для определения, изменилось ли значение поля с момента начального значения. Возвращает True или False.

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

Встроенные классы Field

Библиотека forms поставляется с набором классов Field для типичных задач валидации. В этом разделе описаны каждый встроенный виджет.

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

Поле boolean

class BooleanField(**kwargs) [source]

• Виджет по умолчанию: CheckboxInput
• Пустое значение: False
• Нормализация: значение Python True или False.
• Проверка: значение должно быть True, если поле required=True.
• Ключи сообщений об ошибках: required

Примечание

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

Поле char

class CharField(**kwargs) [source]

• Значение по умолчанию виджета: TextInput
• Пустое значение: то, что вы задали как empty_value.
• Нормализуется в: Строку.
• Проверяет max_length или min_length, если они предоставлены. В противном случае все входные данные валидны.
• Ключи сообщений об ошибках: required, max_length, min_length

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

max_length

min_length

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

strip

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

empty_value

Новое в Django 1.11.

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

ChoiceField

class ChoiceField(**kwargs) [source]

• Значение по умолчанию виджета: Select
• Пустое значение: '' (пустая строка)
• Нормализуется в: Строку.
• Проверяет, что заданное значение существует в списке вариантов.
• Ключи сообщений об ошибках: required, invalid_choice

Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено выбранным вариантом.

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

choices

Итерируемый объект (например, список или кортеж) из 2-х кортежей, используемых в качестве вариантов для этого поля, или вызываемый объект, возвращающий такой итерируемый объект. Этот аргумент принимает те же форматы, что и аргумент choices для поля модели. См. документацию по полям модели по вариантам для получения более подробной информации. Если аргументом является вызываемый объект, он вычисляется каждый раз, когда поле формы инициализируется. По умолчанию — пустой список.

TypedChoiceField

class TypedChoiceField(**kwargs) [source]

Подобно 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) [source]

• Значение по умолчанию виджета: DateInput
• Пустое значение: None
• Нормализуется в: Объект Python datetime.date.
• Проверяет, что заданное значение является datetime.date, datetime.datetime или строкой, отформатированной в определённом формате даты.
• Ключи сообщений об ошибках: required, invalid

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

input_formats

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

Если аргумент input_formats не предоставлен, форматы ввода по умолчанию:

['%Y-%m-%d',      # '2006-10-25'
 '%m/%d/%Y',      # '10/25/2006'
 '%m/%d/%y']      # '10/25/06'

Кроме того, если вы укажете USE_L10N=False в своих настройках, следующие значения также будут включены в форматы ввода по умолчанию:

['%b %d %Y',      # 'Oct 25 2006'
 '%b %d, %Y',     # 'Oct 25, 2006'
 '%d %b %Y',      # '25 Oct 2006'
 '%d %b, %Y',     # '25 Oct, 2006'
 '%B %d %Y',      # 'October 25 2006'
 '%B %d, %Y',     # 'October 25, 2006'
 '%d %B %Y',      # '25 October 2006'
 '%d %B, %Y']     # '25 October, 2006'

См. также локализация формата.

DateTimeField

class DateTimeField(**kwargs) [source]

• Значение по умолчанию виджета: DateTimeInput
• Пустое значение: None
• Нормализуется в: Объект Python datetime.datetime.
• Проверяет, что заданное значение является datetime.datetime, datetime.date или строкой, отформатированной в определённом формате даты и времени.
• Ключи сообщений об ошибках: required, invalid

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

input_formats

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

Если аргумент input_formats не предоставлен, форматы ввода по умолчанию:

['%Y-%m-%d %H:%M:%S',    # '2006-10-25 14:30:59'
 '%Y-%m-%d %H:%M',       # '2006-10-25 14:30'
 '%Y-%m-%d',             # '2006-10-25'
 '%m/%d/%Y %H:%M:%S',    # '10/25/2006 14:30:59'
 '%m/%d/%Y %H:%M',       # '10/25/2006 14:30'
 '%m/%d/%Y',             # '10/25/2006'
 '%m/%d/%y %H:%M:%S',    # '10/25/06 14:30:59'
 '%m/%d/%y %H:%M',       # '10/25/06 14:30'
 '%m/%d/%y']             # '10/25/06'

См. также локализация формата.

DecimalField

class DecimalField(**kwargs) [source]

• Значение по умолчанию виджета: NumberInput, когда Field.localize равно False, иначе TextInput.
• Пустое значение: None
• Нормализуется в: Объект Python decimal.
• Проверяет, что заданное значение является десятичным. Начальные и конечные пробелы игнорируются.
• Ключи сообщений об ошибках: 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) [source]

• Значение по умолчанию виджета: TextInput
• Пустое значение: None
• Нормализуется до: Python timedelta.
• Проверяет, что заданное значение — строка, которую можно преобразовать в timedelta.
• Ключи сообщений об ошибках: required, invalid.

Принимает любой формат, понимаемый parse_duration().

EmailField

class EmailField(**kwargs) [source]

• Значение по умолчанию виджета: EmailInput
• Пустое значение: '' (пустая строка)
• Нормализуется до: Строка.
• Проверяет, что заданное значение является корректным адресом электронной почты, используя умеренно сложную регулярную выражение.
• Ключи сообщений об ошибках: required, invalid

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

FileField

class FileField(**kwargs) [source]

• Значение по умолчанию виджета: ClearableFileInput
• Пустое значение: None
• Нормализуется до: Объекта UploadedFile, который объединяет содержимое файла и имя файла в один объект.
• Может проверять, что непустые данные файла привязаны к форме.
• Ключи сообщений об ошибках: required, invalid, missing, empty, max_length

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

Чтобы узнать больше об объекте UploadedFile, обратитесь к документации по загрузке файлов.

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

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

FilePathField

class FilePathField(**kwargs) [source]

• Значение по умолчанию виджета: Select
• Пустое значение: None
• Нормализуется до: Строки.
• Проверяет, что выбранный элемент существует в списке вариантов.
• Ключи сообщений об ошибках: 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) [source]

• Значение по умолчанию виджета: NumberInput, когда Field.localize равно False, иначе TextInput.
• Пустое значение: None
• Нормализуется до: Python float.
• Проверяет, что заданное значение — число с плавающей точкой. Разрешены ведущие и хвостовые пробелы, как в функции Python float().
• Ключи сообщений об ошибках: required, invalid, max_value, min_value

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

ImageField

class ImageField(**kwargs) [source]

• Значение по умолчанию виджета: ClearableFileInput
• Пустое значение: None
• Нормализуется до: Объекта UploadedFile, который объединяет содержимое файла и имя файла в один объект.
• Проверяет, что данные файла привязаны к форме, и что файл имеет формат изображения, поддерживаемый Pillow.
• Ключи сообщений об ошибках: required, invalid, missing, empty, invalid_image

Использование поля ImageField требует установки библиотеки Pillow с поддержкой используемых форматов изображений. Если при загрузке изображения возникает ошибка corrupt image, это обычно означает, что Pillow не поддерживает указанный формат. Для исправления этой проблемы установите соответствующую библиотеку и переустановите Pillow.

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

После очистки и валидации поля объект UploadedFile будет иметь дополнительный атрибут image, содержащий экземпляр Pillow Image, используемый для проверки, является ли файл корректным изображением. Также, UploadedFile.content_type будет обновлен с типом содержимого изображения, если Pillow может его определить, в противном случае он будет установлен в None.

IntegerField

class IntegerField(**kwargs) [source]

• Значение по умолчанию виджета: NumberInput, когда Field.localize равно False, иначе TextInput.
• Пустое значение: None
• Нормализуется до: Python целого числа.
• Проверяет, что заданное значение — целое число. Разрешены ведущие и хвостовые пробелы, как в функции Python int().
• Ключи сообщений об ошибках: required, invalid, max_value, min_value

Сообщения об ошибках max_value и min_value могут содержать %(limit_value)s, которое будет заменено соответствующим пределом.

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

max_value

min_value

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

GenericIPAddressField

class GenericIPAddressField(**kwargs) [source]

Поле, содержащее IP-адрес версии 4 или 6.

• По умолчанию виджет: 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) [source]

• По умолчанию виджет: SelectMultiple
• Пустое значение: [] (пустой список)
• Нормализуется до: Список строк.
• Проверяет, что каждое значение в заданном списке значений существует в списке вариантов.
• Ключи сообщений об ошибках: required, invalid_choice, invalid_list

Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено выбранным вариантом.

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

TypedMultipleChoiceField

class TypedMultipleChoiceField(**kwargs) [source]

Точно так же, как MultipleChoiceField, за исключением того, что TypedMultipleChoiceField принимает два дополнительных аргумента, coerce и empty_value.

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

Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено выбранным вариантом.

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

NullBooleanField

class NullBooleanField(**kwargs) [source]

• По умолчанию виджет: NullBooleanSelect
• Пустое значение: None
• Нормализуется до: Значение Python True, False или None.
• Не выполняет проверки (т.е., никогда не вызывает ValidationError).

RegexField

class RegexField(**kwargs) [source]

• По умолчанию виджет: TextInput
• Пустое значение: '' (пустая строка)
• Нормализуется до: Строка.
• Проверяет, что заданное значение соответствует определённому регулярному выражению.
• Ключи сообщений об ошибках: required, invalid

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

regex

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

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

strip

По умолчанию False. Если включено, перед проверкой регулярного выражения будет применено удаление пробелов.

SlugField

class SlugField(**kwargs) [source]

• По умолчанию виджет: TextInput
• Пустое значение: '' (пустая строка)
• Нормализуется до: Строка.
• Проверяет, что заданное значение содержит только буквы, цифры, символы подчёркивания и дефисы.
• Сообщения об ошибках: required, invalid

Это поле предназначено для использования при представлении модели SlugField в формах.

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

allow_unicode

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

TimeField

class TimeField(**kwargs) [source]

• По умолчанию виджет: TextInput
• Пустое значение: None
• Нормализуется до: Объект Python datetime.time.
• Проверяет, что заданное значение является либо объектом datetime.time , либо строкой, отформатированной в определённом формате времени.
• Ключи сообщений об ошибках: required, invalid

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

input_formats

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

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

'%H:%M:%S',     # '14:30:59'
'%H:%M',        # '14:30'

URLField

class URLField(**kwargs) [source]

• По умолчанию виджет: URLInput
• Пустое значение: '' (пустая строка)
• Нормализуется до: Строка.
• Проверяет, что заданное значение является валидным URL.
• Ключи сообщений об ошибках: required, invalid

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

max_length

min_length

Они аналогичны CharField.max_length и CharField.min_length.

UUIDField

class UUIDField(**kwargs) [source]

• По умолчанию виджет: TextInput
• Пустое значение: '' (пустая строка)
• Нормализуется до: Объект UUID.
• Ключи сообщений об ошибках: required, invalid

Это поле будет принимать любой формат строки, который принимается как аргумент hex для конструктора UUID.

Slightly complex built-in Field classes

ComboField

class ComboField(**kwargs) [source]

• Значение по умолчанию виджета: 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) [source]

• Значение по умолчанию виджета: 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) [source]

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

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

SplitDateTimeField

class SplitDateTimeField(**kwargs) [source]

• Значение по умолчанию виджета: 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

class ModelChoiceField(**kwargs) [source]

• Значение по умолчанию виджета: Select
• Пустое значение: None
• Нормализуется до: экземпляра модели.
• Проверяет, что заданный id существует в наборе запросов.
• Ключи сообщений об ошибках: required, invalid_choice

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

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

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

<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>

Метод __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

ModelMultipleChoiceField

class ModelMultipleChoiceField(**kwargs) [source]

• Значение по умолчанию виджета: SelectMultiple
• Пустое значение: Пустой QuerySet (self.queryset.none())
• Нормализуется в: Список объектов модели.
• Проверяет, что каждый идентификатор в заданном списке значений существует в наборе запроса.
• Ключи сообщений об ошибках: required, 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.

Создание пользовательских полей

Если встроенные классы Field не удовлетворяют вашим потребностям, вы можете легко создать пользовательские классы Field. Для этого просто создайте подкласс django.forms.Field. Единственные требования — реализация метода clean() и метода __init__(), который принимает основные аргументы, упомянутые выше (required, label, initial, widget, help_text).

Также можно настроить доступ к полю, переопределив get_bound_field().