Поля форм

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 не включён в формы наборов форм, так как проверка браузера может быть некорректной при добавлении и удалении наборов форм.

Метка

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>

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

Аргумент 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().

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

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

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

`BooleanField`

class BooleanField(**kwargs) [source]

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

Примечание

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

`CharField`

class CharField(**kwargs) [source]

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

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

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

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

choices: Итерируемый объект (iterable) из 2-кортежей, используемых в качестве вариантов для этого поля, или вызываемый объект (callable), который возвращает такой итерируемый объект. Этот аргумент принимает те же форматы, что и аргумент 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.
Проверяет, что заданное значение является десятичным. Использует 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) [source]

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

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

`EmailField`

class EmailField(**kwargs) [source]

По умолчанию виджет: EmailInput
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Использует EmailValidator для проверки того, что заданное значение — это корректный адрес электронной почты, с использованием относительно сложной регулярной выражения.
Ключи сообщений об ошибках: 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Проверяет, что выбранный пункт существует в списке вариантов.
Ключи сообщений об ошибках: 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.
Проверяет, что заданное значение является числом с плавающей точкой. Использует MaxValueValidator и MinValueValidator, если max_value и min_value заданы. Разрешаются начальные и конечные пробелы, как в функции Python float().
Ключи сообщений об ошибках: required, invalid, max_value, min_value

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

`ImageField`

class ImageField(**kwargs) [source]

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

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

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

После очистки и проверки поля, объект 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) [source]

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

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

`GenericIPAddressField`

class GenericIPAddressField(**kwargs) [source]

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

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

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

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

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

`SlugField`

class SlugField(**kwargs) [source]

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

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

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

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

`TimeField`

class TimeField(**kwargs) [source]

Значение по умолчанию виджета: TimeInput
Пустое значение: 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Использует URLValidator для проверки, является ли заданное значение допустимым 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Проверяет заданное значение по отношению к каждому из полей, указанных в качестве аргумента для 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: Набор 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__() модели будет вызван для генерации строковых представлений объектов для использования в вариантах поля. Чтобы предоставить настраиваемые представления, подклассируйте 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())
Нормализуется до: A QuerySet экземпляров модели.
Проверяет, что каждый id в заданном списке значений существует в наборе запросов.
Ключи сообщений об ошибках: 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().

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/2.2/ref/forms/fields/

Поля форм

Основные аргументы полей

Обязательность

Метка

Суффикс метки

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

Виджет

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

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

Валидаторы

Локализация

Отключено

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

Изменились ли данные

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

BooleanField

CharField

ChoiceField

TypedChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

ImageField

IntegerField

GenericIPAddressField

MultipleChoiceField

TypedMultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

URLField

UUIDField

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

ComboField

MultiValueField

SplitDateTimeField

Поля, обрабатывающие отношения

ModelChoiceField

ModelMultipleChoiceField

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

`BooleanField`

`CharField`

`ChoiceField`

`TypedChoiceField`

`DateField`

`DateTimeField`

`DecimalField`

`DurationField`

`EmailField`

`FileField`

`FilePathField`

`FloatField`

`ImageField`

`IntegerField`

`GenericIPAddressField`

`MultipleChoiceField`

`TypedMultipleChoiceField`

`NullBooleanField`

`RegexField`

`SlugField`

`TimeField`

`URLField`

`UUIDField`

Сложные встроенные `Field` классы

`ComboField`

`MultiValueField`

`SplitDateTimeField`

`ModelChoiceField`

`ModelMultipleChoiceField`