Поля формы

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

Метка

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 Web site', required=False)
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Your name:</th><td><input type="text" name="name" /></td></tr>
<tr><th>Your Web site:</th><td><input type="url" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></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" /></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" /></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></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" /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></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" /></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></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" /><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" /><br /><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" /><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" /> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" /></li>
<li>Sender: <input type="email" name="sender" /> 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" /> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" /></p>
<p>Sender: <input type="email" name="sender" /> 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.has_changed() [source]

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

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

Встроенные классы полей

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

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

Поле булево

class BooleanField(**kwargs) [source]

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

Примечание

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

Поле символов

class CharField(**kwargs) [source]

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

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

max_length

min_length

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

ChoiceField

class ChoiceField(**kwargs) [source]

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

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

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

choices

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

Добавлена возможность передачи вызываемого объекта в 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'

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

Устаревшее с версии 1.7: Использование SplitDateTimeWidget с DateTimeField устарело и будет удалено в Django 1.9. Используйте SplitDateTimeField вместо этого.

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
• Пустое значение: '' (пустая строка)
• Нормализуется до: Объекта Unicode.
• Проверяет, что заданное значение является корректным адресом электронной почты, используя умеренно сложную регулярную выражение.
• Ключи сообщений об ошибках: 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
• Нормализуется до: Объекта unicode
• Проверяет, что выбранный элемент существует в списке элементов.
• Ключи сообщений об ошибках: 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.

Атрибуты image и content_type , описанные в последнем абзаце, были добавлены.

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

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

IPAddressField

class IPAddressField(**kwargs) [source]

Устарело начиная с версии 1.7: Это поле устарело и рекомендуется использовать GenericIPAddressField.

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

GenericIPAddressField

class GenericIPAddressField(**kwargs) [source]

Поле, содержащее адрес IPv4 или IPv6.

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

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

regex

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

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

Устарело начиная с версии 1.8: Дополнительный аргумент error_message также принимается для обратной совместимости, но будет удален в Django 1.10. Предпочтительный способ предоставления сообщения об ошибке — использовать аргумент error_messages, передавая словарь с 'invalid' в качестве ключа и сообщением об ошибке в качестве значения.

SlugField

class SlugField(**kwargs) [source]

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

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

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
• Пустое значение: '' (пустая строка)
• Нормализуется до: Объект Unicode.
• Проверяет, что заданное значение является корректным URL.
• Ключи сообщений об ошибках: required, invalid

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

max_length

min_length

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

UUIDField

class UUIDField(**kwargs) [source]

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

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

Несколько сложные встроенные Field классы

ComboField

class ComboField(**kwargs) [source]

• Предпочтительный виджет: TextInput
• Пустое значение: '' (пустая строка)
• Нормализуется до: Объект Unicode.
• Проверяет заданное значение по каждому из полей, указанных в качестве аргумента для 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, *args, **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(PhoneField, self).__init__(
            error_messages=error_messages, fields=fields,
            require_all_fields=False, *args, **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(FooMultipleChoiceForm, self).__init__(*args, **kwargs)
        self.fields['foo_select'].queryset = ...

ModelChoiceField

class ModelChoiceField(**kwargs) [source]

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

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

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

queryset

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

Метод __str__ (__unicode__ на Python 2) модели будет вызван для генерации строковых представлений объектов для использования в вариантах поля; чтобы предоставить настраиваемые представления, подклассируйте 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())
• Нормализуется в: QuerySet экземпляров модели.
• Проверяет, что каждый идентификатор в заданном списке значений существует в наборе данных запроса.
• Ключи сообщений об ошибках: required, list, invalid_choice, invalid_pk_value

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

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

queryset

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

Создание настраиваемых полей

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