required¶

Field.required¶

By default, each Field class assumes the value is required, so if you pass an empty value – either None or the empty string ("") – then clean() will raise a ValidationError exception:

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

To specify that a field is not required, pass required=False to the Field constructor:

>>> f = forms.CharField(required=False)
>>> f.clean('foo')
'foo'
>>> f.clean('')
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

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

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

label¶

Field.label¶

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

As explained in «Outputting forms as HTML» above, the default label for a Field is generated from the field name by converting all underscores to spaces and upper-casing the first letter. Specify label if that default behavior doesn’t result in an adequate label.

Here’s a full example Form that implements label for two of its fields. We’ve specified auto_id=False to simplify the output:

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label='Your name')
...     url = forms.URLField(label='Your website', required=False)
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Your website:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

label_suffix¶

Field.label_suffix¶

The label_suffix argument lets you override the form’s label_suffix on a per-field basis:

>>> class ContactForm(forms.Form):
...     age = forms.IntegerField()
...     nationality = forms.CharField()
...     captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =')
>>> f = ContactForm(label_suffix='?')
>>> print(f.as_p())
<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" required></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" required></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" required></p>

initial¶

Field.initial¶

Аргумент initial позволяет определять начальное значение для поля, при его отображении на незаполненной форме.

Для определения динамических начальных данных, используйте параметр Form.initial.

The use-case for this is when you want to display an «empty» form in which a field is initialized to a particular value. For example:

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

You may be thinking, why not just pass a dictionary of the initial values as data when displaying the form? Well, if you do that, you’ll trigger validation, and the HTML output will include any validation errors:

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

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

Also note that initial values are not used as «fallback» data in validation if a particular field’s value is not given. initial values are only intended for initial form display:

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

Instead of a constant, you can also pass any callable:

>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
>>> print(DateForm())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>

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

widget¶

Field.widget¶

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

help_text¶

Field.help_text¶

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

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

Here’s a full example Form that implements help_text for two of its fields. We’ve specified auto_id=False to simplify the output:

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
...     message = forms.CharField()
...     sender = forms.EmailField(help_text='A valid email address, please.')
...     cc_myself = forms.BooleanField(required=False)
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
>>> print(f.as_ul()))
<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required></li>
<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself"></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required></p>
<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself"></p>

error_messages¶

Field.error_messages¶

The error_messages argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override. For example, here is the default error message:

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean('')
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']

And here is a custom error message:

>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']

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

validators¶

Field.validators¶

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

Обратитесь к документации на валидаторы для подробной информации.

localize¶

Field.localize¶

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

See the format localization documentation for more information.

disabled¶

Field.disabled¶

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

has_changed()¶

Field.has_changed()¶

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

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

BooleanField¶

class BooleanField(**kwargs)¶

• Стандартный виджет: CheckboxInput

• Пустое значение: False.

• Возвращает: True или False языка Python.

• Гарантирует, что значение равно True (т.е. чекбокс отмечен), если поле имеет атрибут required=True.

• Ключи сообщений об ошибках: required.

Примечание

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

CharField¶

class CharField(**kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: Всё, что вы назовёте empty_value.

• Возвращает: Экземпляр модели.

• Использует MaxLengthValidator и MinLengthValidator, если указаны max_length и min_length. В противном случае все входные данные действительны.

• Ключи сообщений об ошибках: required, max_length, min_length.

Has four optional arguments for validation:

max_length¶

min_length¶

Если они указаны, то производится соответствующая проверка длины полученной строки.

strip¶

При True (по умолчанию), у значения будут обрезаны пробелы в начале и в конце.

empty_value¶

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

ChoiceField¶

class ChoiceField(**kwargs)¶

• Стандартный виджет: Select

• Пустое значение: '' (пустая строка).

• Возвращает: Экземпляр модели.

• Проверяет, что введённое значение присутствует в списке вариантов.

• Ключи сообщений об ошибках: required, invalid_choice.

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

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

choices¶

Either an iterable of 2-tuples to use as choices for this field, enumeration choices, or a callable that returns such an iterable. This argument accepts the same formats as the choices argument to a model field. See the model field reference documentation on choices for more details. If the argument is a callable, it is evaluated each time the field’s form is initialized, in addition to during rendering. Defaults to an empty list.

TypedChoiceField¶

class TypedChoiceField(**kwargs)¶

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

• Стандартный виджет: Select

• Пустое значение: Всё, что вы назовёте empty_value.

• Возвращает: Значение типа, указанного аргументом coerce.

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

• Ключи сообщений об ошибках: required, invalid_choice.

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

coerce¶

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

empty_value¶

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

DateField¶

class DateField(**kwargs)¶

• Стандартный виджет: DateInput

• Пустое значение: None.

• Возвращает: Объект datetime.date языка Python.

• Проверяет, что полученное значение является объектом datetime.date, datetime.datetime или строкой, отформатированной в нужном виде.

• Ключи сообщений об ошибках: required, invalid.

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

input_formats¶

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

If no input_formats argument is provided, the default input formats are taken from DATE_INPUT_FORMATS if USE_L10N is False, or from the active locale format DATE_INPUT_FORMATS key if localization is enabled. See also format localization.

DateTimeField¶

class DateTimeField(**kwargs)¶

• Стандартный виджет: DateTimeInput

• Пустое значение: None.

• Возвращает: Объект datetime.datetime языка Python.

• Проверяет, что полученное значение является объектом datetime.datetime, datetime.date или строкой, отформатированной в нужном виде.

• Ключи сообщений об ошибках: required, invalid.

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

input_formats¶

A list of formats used to attempt to convert a string to a valid datetime.datetime object, in addition to ISO 8601 formats.

The field always accepts strings in ISO 8601 formatted dates or similar recognized by parse_datetime(). Some examples are:

* '2006-10-25 14:30:59'
* '2006-10-25T14:30:59'
* '2006-10-25 14:30'
* '2006-10-25T14:30'
* '2006-10-25T14:30Z'
* '2006-10-25T14:30+02:00'
* '2006-10-25'

If no input_formats argument is provided, the default input formats are taken from DATETIME_INPUT_FORMATS and DATE_INPUT_FORMATS if USE_L10N is False, or from the active locale format DATETIME_INPUT_FORMATS and DATE_INPUT_FORMATS keys if localization is enabled. See also format localization.

Changed in Django 3.1:

Support for ISO 8601 date string parsing (including optional timezone) was added.

The fallback on DATE_INPUT_FORMATS in the default input_formats was added.

DecimalField¶

class DecimalField(**kwargs)¶

• По умолчанию используется виджет NumberInput при Field.localize равном False, иначе TextInput.

• Пустое значение: None.

• Возвращает: Тип decimal языка Python.

• Validates that the given value is a decimal. Uses MaxValueValidator and MinValueValidator if max_value and min_value are provided. Leading and trailing whitespace is ignored.

• Error message keys: 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.

Takes four optional arguments:

max_value¶

min_value¶

Эти аргументы управляют диапазоном значений, разрешённых для ввода в поле, и должны быть заполнены значениями decimal.Decimal.

max_digits¶

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

decimal_places¶

Максимальное число разрешённых десятичных разрядов.

DurationField¶

class DurationField(**kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: None.

• Нормализует к timedelta.

• Проверяет, что полученное значение является строкой, которая может быть преобразована в timedelta.

• Ключи сообщений об ошибках: required, invalid, incomplete

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

EmailField¶

class EmailField(**kwargs)¶

• Стандартный виджет: EmailInput

• Пустое значение: все, что вы указали как «empty_value».

• Возвращает: Экземпляр модели.

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

• Ключи сообщений об ошибках: required, invalid.

Has three optional arguments max_length, min_length, and empty_value which work just as they do for CharField. The max_length argument defaults to 320 (see RFC 3696 Section 3).

Changed in Django 3.2.20:

The default value for max_length was changed to 320 characters.

FileField¶

class FileField(**kwargs)¶

• Стандартный виджет: ClearableFileInput

• Пустое значение: None.

• Возвращает: Объект UploadedFile, который оборачивает содержимое файла и его имя в единый объект.

• Может проверять, что данные непустого файла были связаны с формой.

• Ключи сообщений об ошибках: required, invalid, missing, empty, max_length.

Has two optional arguments for validation, max_length and allow_empty_file. If provided, these ensure that the file name is at most the given length, and that validation will succeed even if the file content is empty.

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

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

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

FilePathField¶

class FilePathField(**kwargs)¶

• Стандартный виджет: Select

• Пустое значение: '' (пустая строка).

• Возвращает: Экземпляр модели.

• Проверяет, что выбранное значение присутствует в списке вариантов.

• Ключи сообщений об ошибках: required, invalid_choice.

Поле позволяет выбирать файл из определённого каталога. Оно принимает три дополнительных аргумента, требуя обязательного наличия аргумента path:

path¶

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

recursive¶

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

match¶

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

allow_files¶

Необязательно. Возможные значения: True или False. По умолчанию: True. Определяет, следует ли подключать файлы из указанного места или нет. Этот атрибут или allow_folders должен быть установлен в True.

allow_folders¶

Необязательно. Возможные значения: True или False. По умолчанию: False. Определяет, следует ли подключать каталоги из указанного места или нет. Этот атрибут или allow_files должен быть установлен в True.

FloatField¶

class FloatField(**kwargs)¶

• По умолчанию используется виджет NumberInput при Field.localize равном False, иначе TextInput.

• Пустое значение: None.

• Возвращает: Тип float языка Python.

• Validates that the given value is a float. Uses MaxValueValidator and MinValueValidator if max_value and min_value are provided. Leading and trailing whitespace is allowed, as in Python’s float() function.

• Error message keys: required, invalid, max_value, min_value

Takes two optional arguments for validation, max_value and min_value. These control the range of values permitted in the field.

ImageField¶

class ImageField(**kwargs)¶

• Стандартный виджет: ClearableFileInput

• Пустое значение: None.

• Возвращает: Объект UploadedFile, который оборачивает содержимое файла и его имя в единый объект.

• Проверяет, что данные файла были связаны с формой, а затем, что файл является изображением, формат которого поддерживается библиотекой Pillow.

• Ключи сообщений об ошибках: required, invalid, missing, empty, invalid_image.

Using an ImageField requires that Pillow is installed with support for the image formats you use. If you encounter a corrupt image error when you upload an image, it usually means that Pillow doesn’t understand its format. To fix this, install the appropriate library and reinstall Pillow.

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

After the field has been cleaned and validated, the UploadedFile object will have an additional image attribute containing the Pillow Image instance used to check if the file was a valid image. Pillow closes the underlying file descriptor after verifying an image, so while non-image data attributes, such as format, height, and width, are available, methods that access the underlying image data, such as getdata() or getpixel(), cannot be used without reopening the file. For example:

>>> 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 получает дополнительный атрибут image, который содержит экземпляр Image, используемый для проверка того, что файл содержит изображение. Атрибут UploadedFile.content_type также обновляется значением соответствующего типа контента, определённого библиотекой Pillow, иначе None.

IntegerField¶

class IntegerField(**kwargs)¶

• По умолчанию используется виджет NumberInput при Field.localize равном False, иначе TextInput.

• Пустое значение: None.

• Возвращает: Тип float языка Python.

• Validates that the given value is an integer. Uses MaxValueValidator and MinValueValidator if max_value and min_value are provided. Leading and trailing whitespace is allowed, as in Python’s int() function.

• Error message keys: required, invalid, max_value, min_value

The max_value and min_value error messages may contain %(limit_value)s, which will be substituted by the appropriate limit.

Takes two optional arguments for validation:

max_value¶

min_value¶

Они определяют диапазон значений, разрешённый для поля.

JSONField¶

class JSONField(encoder=None, decoder=None, **kwargs)¶

New in Django 3.1.

Поле, которое принимает данные в кодировке JSON для JSONField.

• Виджет по умолчанию: Textarea

• Пустое значение: None.

• Нормализуется до: представления Python значения JSON (обычно в виде dict, list или None), в зависимости от JSONField.decoder.

• Проверяет, что данное значение является допустимым JSON.

• Ключи сообщений об ошибках: required, invalid.

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

encoder¶

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

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

decoder¶

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

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

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

Примечание

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

Удобные формы

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

GenericIPAddressField¶

class GenericIPAddressField(**kwargs)¶

Поле для обработки адресов 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)¶

• Стандартный виджет: SelectMultiple

• Пустое значение: [] (пустой список).

• Возвращает: Список объектов Unicode.

• Проверяет, что каждое значение из полученного списка присутствует в списке вариантов.

• Ключи сообщений об ошибках: required, invalid_choice, invalid_list.

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

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

TypedMultipleChoiceField¶

class TypedMultipleChoiceField(**kwargs)¶

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

• Стандартный виджет: SelectMultiple

• Пустое значение: Всё, что вы назовёте empty_value.

• Возвращает: Список значений типа, который указан аргументом coerce.

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

• Ключи сообщений об ошибках: required, invalid_choice.

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

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

NullBooleanField¶

class NullBooleanField(**kwargs)¶

• Стандартный виджет: NullBooleanSelect

• Пустое значение: None.

• Возвращает: True, False или None.

• Ничего не проверяет, т.е. никогда не возвратит ValidationError.

NullBooleanField можно использовать с такими виджетами, как Select или RadioSelect, предоставив виджет choices:

NullBooleanField(
    widget=Select(
        choices=[
            ('', 'Unknown'),
            (True, 'Yes'),
            (False, 'No'),
        ]
    )
)

RegexField¶

class RegexField(**kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: все, что вы указали как «empty_value».

• Возвращает: Экземпляр модели.

• Проверяет, что полученное значение совпадает с указанным регулярным выражением.

• Ключи сообщений об ошибках: required, invalid.

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

regex¶

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

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

strip¶

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

SlugField¶

class SlugField(**kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: Всё, что вы назовёте empty_value.

• Возвращает: Экземпляр модели.

• Проверяет, что полученное значение содержит только буквы, цифры, подчёркивания и тире.

• Ключи сообщений об ошибках: required, invalid.

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

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

allow_unicode¶

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

empty_value¶

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

TimeField¶

class TimeField(**kwargs)¶

• Стандартный виджет: DateTimeInput

• Пустое значение: None.

• Возвращает: Объект datetime.time языка Python.

• Проверяет, что переданное значение является объектом datetime.time или строкой, отформатированной в нужном виде.

• Ключи сообщений об ошибках: required, invalid.

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

input_formats¶

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

If no input_formats argument is provided, the default input formats are taken from TIME_INPUT_FORMATS if USE_L10N is False, or from the active locale format TIME_INPUT_FORMATS key if localization is enabled. See also format localization.

URLField¶

class URLField(**kwargs)¶

• Стандартный виджет: URLInput

• Пустое значение: все, что вы указали как «empty_value».

• Возвращает: Экземпляр модели.

• Проверяет, что полученное значение является правильным URL.

• Ключи сообщений об ошибках: required, invalid.

Has three optional arguments max_length, min_length, and empty_value which work just as they do for CharField.

UUIDField¶

class UUIDField(**kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: None.

• Нормализует к: объекту UUID.

• Ключи сообщений об ошибках: required, invalid.

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

ComboField¶

class ComboField(**kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: '' (пустая строка).

• Возвращает: Экземпляр модели.

• Проверяет, что полученное значение соответствует каждому полю, указанному в качестве аргумента ComboField.

• Ключи сообщений об ошибках: required, invalid.

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

fields¶

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

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('test@example.com')
'test@example.com'
>>> f.clean('longemailaddress@example.com')
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

MultiValueField¶

class MultiValueField(fields=(), **kwargs)¶

• Стандартный виджет: TextInput

• Пустое значение: '' (пустая строка).

• Возвращает: Тип, который вернёт метод compress().

• Проверяет, что полученное значение соответствует полям, указанным в аргументе MultiValueField.

• Ключи сообщений об ошибках: required, invalid, incomplete

Агрегирует логику нескольких полей, создавая единое значение.

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

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

fields¶

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

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

require_all_fields¶

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

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

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

from django.core.validators import RegexValidator

class PhoneField(MultiValueField):
    def __init__(self, **kwargs):
        # Define one message for all fields.
        error_messages = {
            'incomplete': 'Enter a country calling code and a phone number.',
        }
        # Or define a different message for each field.
        fields = (
            CharField(
                error_messages={'incomplete': 'Enter a country calling code.'},
                validators=[
                    RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'),
                ],
            ),
            CharField(
                error_messages={'incomplete': 'Enter a phone number.'},
                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')],
            ),
            CharField(
                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')],
                required=False,
            ),
        )
        super().__init__(
            error_messages=error_messages, fields=fields,
            require_all_fields=False, **kwargs
        )

widget¶

Должен быть дочерним классом django.forms.MultiWidget.Значением по умолчанию является TextInput, который возможно не так полезен в этом случае.

compress(data_list)¶

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

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

SplitDateTimeField¶

class SplitDateTimeField(**kwargs)¶

• Стандартный виджет: :class:SplitDateTimeWidget

• Пустое значение: None.

• Возвращает: Объект datetime.datetime языка Python.

• Проверяет, что переданное значение является объектом datetime.datetime или строкой, отформатированной в нужном виде.

• Ключи сообщений об ошибках: required, invalid, invalid_date, invalid_time.

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

input_date_formats¶

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

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

input_time_formats¶

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

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

ModelChoiceField¶

class ModelChoiceField(**kwargs)¶

• Стандартный виджет: Select

• Пустое значение: None.

• Возвращает: Экземпляр модели.

• Проверяет, что полученный идентификатор присутствует в выборке.

• Ключи сообщений об ошибках: required, invalid_choice.

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

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

queryset¶

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

ModelChoiceField also takes two optional arguments:

empty_label¶

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

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

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

Note that if a ModelChoiceField is required and has a default initial value, no empty choice is created (regardless of the value of empty_label).

to_field_name¶

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

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

вернет:

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

и:

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

вернет:

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

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

iterator¶

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

При генерации текстового представления варианта используется метод __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)¶

• Стандартный виджет: SelectMultiple

• Пустое значение: пустой QuerySet (self.queryset.none()).

• Возвращает: Выборку с экземплярами модели.

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

• Ключи сообщения об ошибке: required, invalid_list, invalid_choice, invalid_pk_value

Сообщение об ошибке invalid_choice может включать %(value)s,а invalid_pk_value – %(pk)s.

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

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

queryset¶

То же, что и ModelChoiceField.queryset.

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

to_field_name¶

То же, что и ModelChoiceField.to_field_name.

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

iterator¶

То же, что и ModelChoiceField.iterator.

Итерационный выбор отношений¶

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

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

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

from django.db import models

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

    def __str__(self):
        return self.name

class Pizza(models.Model):
    topping = models.ForeignKey(Topping, on_delete=models.CASCADE)

Вы можете использовать подкласс виджета Select, чтобы включить значение Topping.price в качестве HTML-атрибута data-price для каждого элемента <option>:

from django import forms

class ToppingSelect(forms.Select):
    def create_option(self, name, value, label, selected, index, subindex=None, attrs=None):
        option = super().create_option(name, value, label, selected, index, subindex, attrs)
        if value:
            option['attrs']['data-price'] = value.instance.price
        return option

class PizzaForm(forms.ModelForm):
    class Meta:
        model = Pizza
        fields = ['topping']
        widgets = {'topping': ToppingSelect}

Это отобразит выбор «Pizza.topping» как:

<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>

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