required¶

Field.required¶

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

>>> from django import forms
>>> f = forms.CharField()
>>> f.clean("foo")
'foo'
>>> f.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

Чтобы указать, что поле не является обязательным, передайте required=False в конструктор Field:

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

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

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

label¶

Field.label¶

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

Как объяснено в Выдача формы в виде HTML, метка по умолчанию для поля Field генерируется из имени поля путем преобразования всех символов подчеркивания в пробелы и перевода первой буквы в верхний регистр. Укажите 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)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>

label_suffix¶

Field.label_suffix¶

Аргумент label_suffix позволяет переопределить label_suffix формы для каждого поля:

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

initial¶

Field.initial¶

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

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

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

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="Your name" required></div>
<div>Url:<input type="url" name="url" value="https://" required></div>
<div>Comment:<input type="text" name="comment" required></div>

Вы можете подумать, а почему бы просто не передать словарь начальных значений в качестве данных при отображении формы? Что ж, если вы это сделаете, вы активируете проверку, и вывод HTML будет содержать все ошибки проверки:

>>> class CommentForm(forms.Form):
...     name = forms.CharField()
...     url = forms.URLField()
...     comment = forms.CharField()
...
>>> default_data = {"name": "Your name", "url": "https://"}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<div>Name:
  <input type="text" name="name" value="Your name" required>
</div>
<div>Url:
  <ul class="errorlist"><li>Enter a valid URL.</li></ul>
  <input type="url" name="url" value="https://" required aria-invalid="true">
</div>
<div>Comment:
  <ul class="errorlist"><li>This field is required.</li></ul>
  <input type="text" name="comment" required aria-invalid="true">
</div>

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

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

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fallback 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())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>

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

widget¶

Field.widget¶

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

help_text¶

Field.help_text¶

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

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

Вот полный пример формы, которая реализует 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)
<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>
<div>Message:<input type="text" name="message" required></div>
<div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>
<div>Cc myself:<input type="checkbox" name="cc_myself"></div>

Если поле имеет текст справки, оно связано с его вводом с помощью HTML-атрибута aria-describedby. Если виджет отображается в <fieldset>, то к этому элементу добавляется aria-describedby, в противном случае он добавляется в <input> виджета:

>>> from django import forms
>>> class UserForm(forms.Form):
...     username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>

При добавлении пользовательского атрибута aria-describedby обязательно включите также идентификатор элемента help_text (если он используется) в желаемом порядке. Для пользователей программ чтения с экрана описания будут читаться в порядке их появления внутри aria-describedby:

>>> class UserForm(forms.Form):
...     username = forms.CharField(
...         max_length=255,
...         help_text="e.g., user@example.com",
...         widget=forms.TextInput(
...             attrs={"aria-describedby": "custom-description id_username_helptext"},
...         ),
...     )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>

error_messages¶

Field.error_messages¶

Аргумент error_messages позволяет переопределить сообщения по умолчанию, которые выдает поле. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые вы хотите переопределить. Например, вот сообщение об ошибке по умолчанию:

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

А вот специальное сообщение об ошибке:

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

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

validators¶

Field.validators¶

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

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

localize¶

Field.localize¶

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

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

disabled¶

Field.disabled¶

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

имя_шаблона¶

Field.template_name¶

Аргумент template_name позволяет использовать собственный шаблон, когда поле отображается с помощью as_field_group(). По умолчанию это значение установлено в "django/forms/field.html". Может быть изменено для каждого поля, переопределив этот атрибут, или, в более общем плане, переопределив шаблон по умолчанию, см. также Переопределение встроенных шаблонов полей.

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.

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

max_length¶

min_length¶

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

strip¶

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

empty_value¶

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

ChoiceField¶

class ChoiceField(**kwargs)¶

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

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

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

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

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

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

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

choices¶

Либо iterable из двух кортежей для использования в качестве выбора для этого поля, тип перечисления, либо вызываемый объект, который возвращает такой итерируемый объект. Этот аргумент принимает те же форматы, что и аргумент «choices» для поля модели. Дополнительную информацию см. в справочной документации по полям модели по выбору <field-choices>`. Если аргумент является вызываемым, он оценивается каждый раз при инициализации формы поля, а также во время отрисовки. По умолчанию пустой список.

Тип выбора

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

Changed in Django 5.0:

Была добавлена ​​поддержка сопоставлений и использования типов перечисления <field-choices-enum-types>` непосредственно в choices.

DateField¶

class DateField(**kwargs)¶

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

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

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

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

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

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

input_formats¶

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

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

DateTimeField¶

class DateTimeField(**kwargs)¶

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

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

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

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

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

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

input_formats¶

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

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

• '2006-10-25 14:30:59'

• '2006-10-25T14:30:59'

• '2006-10-25 14:30'

• '2006-10-25T14:30'

• '2006-10-25T14:30Z'

• '2006-10-25T14:30+02:00'

• '25 октября 2006 г.'

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

DecimalField¶

class DecimalField(**kwargs)¶

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

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

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

• Проверяет, что данное значение является десятичным. Использует MaxValueValidator и MinValueValidator, если указаны max_value и min_value. Использует StepValueValidator, если указан step_size. Ведущие и конечные пробелы игнорируются.

• Ключи сообщения об ошибке: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size.

Сообщения об ошибках 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¶

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

step_size¶

Ограничьте допустимые входные данные целым кратным step_size. Если также указано min_value, оно добавляется как смещение, чтобы определить, соответствует ли размер шага.

DurationField¶

class DurationField(**kwargs)¶

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

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

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

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

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

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

EmailField¶

class EmailField(**kwargs)¶

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

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

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

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

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

Имеет необязательные аргументы max_length, min_length и empty_value, которые работают так же, как и для CharField. Аргумент max_length по умолчанию равен 320 (см. RFC 3696 Section 3).

FileField¶

class FileField(**kwargs)¶

• Стандартный виджет: 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)¶

• Стандартный виджет: 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.

• Проверяет, что данное значение является числом с плавающей запятой. Использует MaxValueValidator и MinValueValidator, если указаны max_value и min_value. Использует StepValueValidator, если указан step_size. Допускаются начальные и конечные пробелы, как в функции Python float().

• Ключи сообщения об ошибке: required, invalid, max_value, min_value, step_size.

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

max_value¶

min_value¶

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

step_size¶

Ограничьте допустимые входные данные целым кратным step_size. Если также указано min_value, оно добавляется как смещение, чтобы определить, соответствует ли размер шага.

GenericIPAddressField¶

class GenericIPAddressField(**kwargs)¶

Поле для обработки адресов IPv4 или IPv6.

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

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

• Возвращает: Объект Unicode. Преобразование IPv6 адресов описано далее.

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

• Ключи сообщения об ошибке: required, invalid, max_length

Преобразование адреса 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'.

max_length¶

По умолчанию 39, и ведет себя так же, как и для CharField.

Changed in Django 4.2.18:

Значение по умолчанию для max_length было установлено на 39 символов.

ImageField¶

class ImageField(**kwargs)¶

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

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

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

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

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

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

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

После очистки и проверки поля объект UploadedFile будет иметь дополнительный атрибут image, содержащий экземпляр Pillow Image, используемый для проверки того, является ли файл допустимым изображением. Pillow закрывает базовый дескриптор файла после проверки изображения, поэтому, хотя атрибуты данных, не относящиеся к изображению, такие как «формат», «высота» и «ширина», доступны, методы, которые обращаются к базовым данным изображения, такие как «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", b"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.

• Проверяет, что данное значение является целым числом. Использует MaxValueValidator и MinValueValidator, если указаны max_value и min_value. Использует StepValueValidator, если указан step_size. Допускаются начальные и конечные пробелы, как в функции Python int().

• Ключи сообщения об ошибке: required, invalid, max_value, min_value, step_size

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

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

max_value¶

min_value¶

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

step_size¶

Ограничьте допустимые входные данные целым кратным step_size. Если также указано min_value, оно добавляется как смещение, чтобы определить, соответствует ли размер шага.

JSONField¶

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

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

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

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

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

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

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

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

encoder¶

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

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

decoder¶

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

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

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

Примечание

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

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

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

MultipleChoiceField¶

class MultipleChoiceField(**kwargs)¶

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

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

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

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

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

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

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

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.

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

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, так что выбирайте значение соответственно.

TypedMultipleChoiceField¶

class TypedMultipleChoiceField(**kwargs)¶

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

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

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

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

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

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

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

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

URLField¶

class URLField(**kwargs)¶

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

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

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

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

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

Имеет необязательные аргументы max_length, min_length, empty_value, которые работают так же, как и для CharField, и еще один аргумент:

assume_scheme¶

New in Django 5.0.

Схема предполагается для URL-адресов, предоставленных без него. По умолчанию http'`. Например, если ``assume_scheme — это "https", а предоставленное значение — "example.com", нормализованное значение будет "https://example.com".

Не рекомендуется, начиная с версии 5.0: Значение по умолчанию для Assume_scheme изменится с http на https в Django 6.0. Установите для переходного параметра FORMS_URLFIELD_ASSUME_HTTPS значение True, чтобы разрешить использование "https" во время цикла выпуска Django 5.x.

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.

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

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

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

queryset¶

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

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

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)

Обратите внимание, что пустой выбор не создается (независимо от значенияempty_label), если требуется ModelChoiceField и имеет начальное значение по умолчанию, или для виджета установлено значение RadioSelect, а аргумент blank имеет значение False.

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>

blank¶

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

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