required¶

Field.required¶

By default, eachField class assumes the value is required, so if you passan empty value – eitherNone or the empty string ("") – thenclean() will raise aValidationError exception:

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

To specify that a field isnot required, passrequired=False to theField 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'

If aField hasrequired=False and you passclean() an empty value,thenclean() will return anormalized empty value rather than raisingValidationError. ForCharField, this will returnempty_value which defaults to an empty string. For otherField classes, it might beNone. (This varies from field to field.)

Widgets of required form fields have therequired HTML attribute. Set theForm.use_required_attribute attribute toFalse to disable it. Therequired attribute isn’t included on forms of formsets because the browservalidation may not be correct when adding and deleting formsets.

label¶

Field.label¶

Thelabel argument lets you specify the “human-friendly” label for thisfield. This is used when theField is displayed in aForm.

As explained inOutputting forms as HTML, the default label for aField is generated from the field name by converting all underscores tospaces and upper-casing the first letter. Specifylabel if that defaultbehavior doesn’t result in an adequate label.

Here’s a full exampleForm that implementslabel for two of its fields.We’ve specifiedauto_id=False to simplify the output:

>>>fromdjangoimportforms>>>classCommentForm(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¶

Thelabel_suffix argument lets you override the form’slabel_suffix on a per-field basis:

>>>classContactForm(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¶

Theinitial argument lets you specify the initial value to use whenrendering thisField in an unboundForm.

To specify dynamic initial data, see theForm.initial parameter.

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

>>>fromdjangoimportforms>>>classCommentForm(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>

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

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

This is whyinitial values are only displayed for unbound forms. For boundforms, the HTML output will use the bound data.

Also note thatinitial values arenot used as “fallback” data invalidation if a particular field’s value is not given.initial values areonly intended for initial form display:

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

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

>>>importdatetime>>>classDateForm(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>

The callable will be evaluated only when the unbound form is displayed, not when it is defined.

widget¶

Field.widget¶

Thewidget argument lets you specify aWidget class to use whenrendering thisField. SeeWidgets for more information.

help_text¶

Field.help_text¶

Thehelp_text argument lets you specify descriptive text for thisField. If you providehelp_text, it will be displayed next to theField when theField is rendered by one of the convenienceFormmethods (e.g.,as_ul()).

Like the model field’shelp_text, this valueisn’t HTML-escaped in automatically-generated forms.

Here’s a full exampleForm that implementshelp_text for two of itsfields. We’ve specifiedauto_id=False to simplify the output:

>>>fromdjangoimportforms>>>classHelpTextContactForm(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>

When a field has help text it is associated with its input using thearia-describedby HTML attribute. If the widget is rendered in a<fieldset> thenaria-describedby is added to this element, otherwise itis added to the widget’s<input>:

>>>fromdjangoimportforms>>>classUserForm(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>

When adding a customaria-describedby attribute, make sure to also includetheid of thehelp_text element (if used) in the desired order. Forscreen reader users, descriptions will be read in their order of appearanceinsidearia-describedby:

>>>classUserForm(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¶

Theerror_messages argument lets you override the default messages that thefield will raise. Pass in a dictionary with keys matching the error messages youwant to override. For example, here is the default error message:

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

In thebuilt-in Field classes section below, eachField defines theerror message keys it uses.

validators¶

Field.validators¶

Thevalidators argument lets you provide a list of validation functionsfor this field.

See thevalidators documentation for more information.

localize¶

Field.localize¶

Thelocalize argument enables the localization of form data input, as wellas the rendered output.

See theformat localization documentation formore information.

disabled¶

Field.disabled¶

Thedisabled boolean argument, when set toTrue, disables a form fieldusing thedisabled HTML attribute so that it won’t be editable by users.Even if a user tampers with the field’s value submitted to the server, it willbe ignored in favor of the value from the form’s initial data.

template_name¶

Field.template_name¶

Thetemplate_name argument allows a custom template to be used when thefield is rendered withas_field_group(). Bydefault this value is set to"django/forms/field.html". Can be changed perfield by overriding this attribute or more generally by overriding the defaulttemplate, see alsoOverriding built-in field templates.

has_changed()¶

Field.has_changed()[source]¶

Thehas_changed() method is used to determine if the field value has changedfrom the initial value. ReturnsTrue orFalse.

See theForm.has_changed() documentation for more information.

BooleanField¶

classBooleanField(**kwargs)[source]¶

• Default widget:CheckboxInput

• Empty value:False

• Normalizes to: A PythonTrue orFalse value.

• Validates that the value isTrue (e.g. the check box is checked) ifthe field hasrequired=True.

• Error message keys:required

Note

Since allField subclasses haverequired=True by default, thevalidation condition here is important. If you want to include a booleanin your form that can be eitherTrue orFalse (e.g. a checked orunchecked checkbox), you must remember to pass inrequired=False whencreating theBooleanField.

CharField¶

classCharField(**kwargs)[source]¶

• Default widget:TextInput

• Empty value: Whatever you’ve given asempty_value.

• Normalizes to: A string.

• UsesMaxLengthValidator andMinLengthValidator ifmax_length andmin_length are provided. Otherwise, all inputs are valid.

• Error message keys:required,max_length,min_length

Has the following optional arguments for validation:

max_length¶

min_length¶

If provided, these arguments ensure that the string is at most or atleast the given length.

strip¶

IfTrue (default), the value will be stripped of leading andtrailing whitespace.

empty_value¶

The value to use to represent “empty”. Defaults to an empty string.

ChoiceField¶

classChoiceField(**kwargs)[source]¶

• Default widget:Select

• Empty value:'' (an empty string)

• Normalizes to: A string.

• Validates that the given value exists in the list of choices.

• Error message keys:required,invalid_choice

Theinvalid_choice error message may contain%(value)s, which will bereplaced with the selected choice.

Takes one extra argument:

choices[source]¶

Either aniterable of 2-tuples to use as choices for thisfield,enumeration type, or acallable that returns such an iterable. This argument accepts the sameformats as thechoices argument to a model field. See themodel field reference documentation on choicesfor more details. If the argument is a callable, it is evaluated eachtime the field’s form is initialized, in addition to during rendering.Defaults to an empty list.

Choice type

This field normalizes choices to strings, so if choices are required inother data types, such as integers or booleans, consider usingTypedChoiceField instead.

Changed in Django 5.0:

Support for mappings and usingenumeration types directly inchoices was added.

DateField¶

classDateField(**kwargs)[source]¶

• Default widget:DateInput

• Empty value:None

• Normalizes to: A Pythondatetime.date object.

• Validates that the given value is either adatetime.date,datetime.datetime or string formatted in a particular date format.

• Error message keys:required,invalid

Takes one optional argument:

input_formats¶

An iterable of formats used to attempt to convert a string to a validdatetime.date object.

If noinput_formats argument is provided, the default input formats aretaken from the active locale formatDATE_INPUT_FORMATS key, or fromDATE_INPUT_FORMATS if localization is disabled. See alsoformat localization.

DateTimeField¶

classDateTimeField(**kwargs)[source]¶

• Default widget:DateTimeInput

• Empty value:None

• Normalizes to: A Pythondatetime.datetime object.

• Validates that the given value is either adatetime.datetime,datetime.date or string formatted in a particular datetime format.

• Error message keys:required,invalid

Takes one optional argument:

input_formats¶

An iterable of formats used to attempt to convert a string to a validdatetime.datetime object, in addition to ISO 8601 formats.

The field always accepts strings in ISO 8601 formatted dates or similarrecognized byparse_datetime(). Some examplesare:

• '2006-10-2514:30:59'

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

• '2006-10-2514:30'

• '2006-10-25T14:30'

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

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

• '2006-10-25'

If noinput_formats argument is provided, the default input formats aretaken from the active locale formatDATETIME_INPUT_FORMATS andDATE_INPUT_FORMATS keys, or fromDATETIME_INPUT_FORMATS andDATE_INPUT_FORMATS if localization is disabled. See alsoformat localization.

DecimalField¶

classDecimalField(**kwargs)[source]¶

• Default widget:NumberInput whenField.localize isFalse, elseTextInput.

• Empty value:None

• Normalizes to: A Pythondecimal.

• Validates that the given value is a decimal. UsesMaxValueValidator andMinValueValidator ifmax_value andmin_value are provided. UsesStepValueValidator ifstep_size isprovided. Leading and trailing whitespace is ignored.

• Error message keys:required,invalid,max_value,min_value,max_digits,max_decimal_places,max_whole_digits,step_size.

Themax_value andmin_value error messages may contain%(limit_value)s, which will be substituted by the appropriate limit.Similarly, themax_digits,max_decimal_places andmax_whole_digits error messages may contain%(max)s.

Takes five optional arguments:

max_value¶

min_value¶

These control the range of values permitted in the field, and should begiven asdecimal.Decimal values.

max_digits¶

The maximum number of digits (those before the decimal point plus thoseafter the decimal point, with leading zeros stripped) permitted in thevalue.

decimal_places¶

The maximum number of decimal places permitted.

step_size¶

Limit valid inputs to an integral multiple ofstep_size. Ifmin_value is also provided, it’s added as an offset to determine ifthe step size matches.

DurationField¶

classDurationField(**kwargs)[source]¶

• Default widget:TextInput

• Empty value:None

• Normalizes to: A Pythontimedelta.

• Validates that the given value is a string which can be converted into atimedelta. The value must be betweendatetime.timedelta.minanddatetime.timedelta.max.

• Error message keys:required,invalid,overflow.

Accepts any format understood byparse_duration().

EmailField¶

classEmailField(**kwargs)[source]¶

• Default widget:EmailInput

• Empty value: Whatever you’ve given asempty_value.

• Normalizes to: A string.

• UsesEmailValidator to validate thatthe given value is a valid email address, using a moderately complexregular expression.

• Error message keys:required,invalid

Has the optional argumentsmax_length,min_length, andempty_value which work just as they do forCharField. Themax_length argument defaults to 320 (seeRFC 3696 Section 3).

FileField¶

classFileField(**kwargs)[source]¶

• Default widget:ClearableFileInput

• Empty value:None

• Normalizes to: AnUploadedFile object that wraps the file contentand file name into a single object.

• Can validate that non-empty file data has been bound to the form.

• Error message keys:required,invalid,missing,empty,max_length

Has the optional arguments for validation:max_length andallow_empty_file. If provided, these ensure that the file name is atmost the given length, and that validation will succeed even if the filecontent is empty.

To learn more about theUploadedFile object, see thefile uploadsdocumentation.

When you use aFileField in a form, you must also remember tobind the file data to the form.

Themax_length error refers to the length of the filename. In the errormessage for that key,%(max)d will be replaced with the maximum filenamelength and%(length)d will be replaced with the current filename length.

FilePathField¶

classFilePathField(**kwargs)[source]¶

• Default widget:Select

• Empty value:'' (an empty string)

• Normalizes to: A string.

• Validates that the selected choice exists in the list of choices.

• Error message keys:required,invalid_choice

The field allows choosing from files inside a certain directory. It takes fiveextra arguments; onlypath is required:

path¶

The absolute path to the directory whose contents you want listed. Thisdirectory must exist.

recursive¶

IfFalse (the default) only the direct contents ofpath will beoffered as choices. IfTrue, the directory will be descended intorecursively and all descendants will be listed as choices.

match¶

A regular expression pattern; only files with names matching this expressionwill be allowed as choices.

allow_files¶

Optional. EitherTrue orFalse. Default isTrue. Specifieswhether files in the specified location should be included. Either this orallow_folders must beTrue.

allow_folders¶

Optional. EitherTrue orFalse. Default isFalse. Specifieswhether folders in the specified location should be included. Either this orallow_files must beTrue.

FloatField¶

classFloatField(**kwargs)[source]¶

• Default widget:NumberInput whenField.localize isFalse, elseTextInput.

• Empty value:None

• Normalizes to: A Python float.

• Validates that the given value is a float. UsesMaxValueValidator andMinValueValidator ifmax_value andmin_value are provided. UsesStepValueValidator ifstep_size isprovided. Leading and trailing whitespace is allowed, as in Python’sfloat() function.

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

Takes three optional arguments:

max_value¶

min_value¶

These control the range of values permitted in the field.

step_size¶

Limit valid inputs to an integral multiple ofstep_size. Ifmin_value is also provided, it’s added as an offset to determine ifthe step size matches.

GenericIPAddressField¶

classGenericIPAddressField(**kwargs)[source]¶

A field containing either an IPv4 or an IPv6 address.

• Default widget:TextInput

• Empty value:'' (an empty string)

• Normalizes to: A string. IPv6 addresses are normalized as described below.

• Validates that the given value is a valid IP address.

• Error message keys:required,invalid,max_length

The IPv6 address normalization followsRFC 4291 Section 2.2 section 2.2,including using the IPv4 format suggested in paragraph 3 of that section, like::ffff:192.0.2.0. For example,2001:0::0:01 would be normalized to2001::1, and::ffff:0a0a:0a0a to::ffff:10.10.10.10. All charactersare converted to lowercase.

Takes three optional arguments:

protocol¶

Limits valid inputs to the specified protocol.Accepted values areboth (default),IPv4orIPv6. Matching is case insensitive.

unpack_ipv4¶

Unpacks IPv4 mapped addresses like::ffff:192.0.2.1.If this option is enabled that address would be unpacked to192.0.2.1. Default is disabled. Can only be usedwhenprotocol is set to'both'.

max_length¶

Defaults to 39, and behaves the same way as it does forCharField.

Changed in Django 4.2.18:

The default value formax_length was set to 39 characters.

ImageField¶

classImageField(**kwargs)[source]¶

• Default widget:ClearableFileInput

• Empty value:None

• Normalizes to: AnUploadedFile object that wraps the file contentand file name into a single object.

• Validates that file data has been bound to the form. Also usesFileExtensionValidator to validate thatthe file extension is supported by Pillow.

• Error message keys:required,invalid,missing,empty,invalid_image

Using anImageField requires thatpillow is installed withsupport for the image formats you use. If you encounter acorruptimageerror when you upload an image, it usually means that Pillow doesn’tunderstand its format. To fix this, install the appropriate library andreinstall Pillow.

When you use anImageField on a form, you must also remember tobind the file data to the form.

After the field has been cleaned and validated, theUploadedFileobject will have an additionalimage attribute containing the PillowImage instance used to check if the file was a valid image. Pillowcloses the underlying file descriptor after verifying an image, so whilenon-image data attributes, such asformat,height, andwidth,are available, methods that access the underlying image data, such asgetdata() orgetpixel(), cannot be used without reopening the file.For example:

>>>fromPILimportImage>>>fromdjangoimportforms>>>fromdjango.core.files.uploadedfileimportSimpleUploadedFile>>>classImageForm(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.width191>>>image_field.image.height287>>>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>

Additionally,UploadedFile.content_type will be updated with theimage’s content type if Pillow can determine it, otherwise it will be settoNone.

IntegerField¶

classIntegerField(**kwargs)[source]¶

• Default widget:NumberInput whenField.localize isFalse, elseTextInput.

• Empty value:None

• Normalizes to: A Python integer.

• Validates that the given value is an integer. UsesMaxValueValidator andMinValueValidator ifmax_value andmin_value are provided. UsesStepValueValidator ifstep_size isprovided. Leading and trailing whitespace is allowed, as in Python’sint() function.

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

Themax_value,min_value andstep_size error messages maycontain%(limit_value)s, which will be substituted by the appropriatelimit.

Takes three optional arguments for validation:

max_value¶

min_value¶

These control the range of values permitted in the field.

step_size¶

Limit valid inputs to an integral multiple ofstep_size. Ifmin_value is also provided, it’s added as an offset to determine ifthe step size matches.

JSONField¶

classJSONField(encoder=None,decoder=None,**kwargs)[source]¶

A field which accepts JSON encoded data for aJSONField.

• Default widget:Textarea

• Empty value:None

• Normalizes to: A Python representation of the JSON value (usually as adict,list, orNone), depending onJSONField.decoder.

• Validates that the given value is a valid JSON.

• Error message keys:required,invalid

Takes two optional arguments:

encoder¶

Ajson.JSONEncoder subclass to serialize data types notsupported by the standard JSON serializer (e.g.datetime.datetimeorUUID). For example, you can use theDjangoJSONEncoder class.

Defaults tojson.JSONEncoder.

decoder¶

Ajson.JSONDecoder subclass to deserialize the input. Yourdeserialization may need to account for the fact that you can’t becertain of the input type. For example, you run the risk of returning adatetime that was actually a string that just happened to be in thesame format chosen fordatetimes.

Thedecoder can be used to validate the input. Ifjson.JSONDecodeError is raised during the deserialization,aValidationError will be raised.

Defaults tojson.JSONDecoder.

Note

If you use aModelForm, theencoder anddecoder fromJSONFieldwill be used.

User friendly forms

JSONField is not particularly user friendly in most cases. However,it is a useful way to format data from a client-side widget forsubmission to the server.

MultipleChoiceField¶

classMultipleChoiceField(**kwargs)[source]¶

• Default widget:SelectMultiple

• Empty value:[] (an empty list)

• Normalizes to: A list of strings.

• Validates that every value in the given list of values exists in the listof choices.

• Error message keys:required,invalid_choice,invalid_list

Theinvalid_choice error message may contain%(value)s, which will bereplaced with the selected choice.

Takes one extra required argument,choices, as forChoiceField.

NullBooleanField¶

classNullBooleanField(**kwargs)[source]¶

• Default widget:NullBooleanSelect

• Empty value:None

• Normalizes to: A PythonTrue,False orNone value.

• Validates nothing (i.e., it never raises aValidationError).

NullBooleanField may be used with widgets such asSelect orRadioSelectby providing the widgetchoices:

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

RegexField¶

classRegexField(**kwargs)[source]¶

• Default widget:TextInput

• Empty value: Whatever you’ve given asempty_value.

• Normalizes to: A string.

• UsesRegexValidator to validate thatthe given value matches a certain regular expression.

• Error message keys:required,invalid

Takes one required argument:

regex¶

A regular expression specified either as a string or a compiled regularexpression object.

Also takesmax_length,min_length,strip, andempty_valuewhich work just as they do forCharField.

strip¶

Defaults toFalse. If enabled, stripping will be applied before theregex validation.

SlugField¶

classSlugField(**kwargs)[source]¶

• Default widget:TextInput

• Empty value: Whatever you’ve given asempty_value.

• Normalizes to: A string.

• Usesvalidate_slug orvalidate_unicode_slug to validate thatthe given value contains only letters, numbers, underscores, and hyphens.

• Error messages:required,invalid

This field is intended for use in representing a modelSlugField in forms.

Takes two optional parameters:

allow_unicode¶

A boolean instructing the field to accept Unicode letters in additionto ASCII letters. Defaults toFalse.

empty_value¶

The value to use to represent “empty”. Defaults to an empty string.

TimeField¶

classTimeField(**kwargs)[source]¶

• Default widget:TimeInput

• Empty value:None

• Normalizes to: A Pythondatetime.time object.

• Validates that the given value is either adatetime.time or stringformatted in a particular time format.

• Error message keys:required,invalid

Takes one optional argument:

input_formats¶

An iterable of formats used to attempt to convert a string to a validdatetime.time object.

If noinput_formats argument is provided, the default input formats aretaken from the active locale formatTIME_INPUT_FORMATS key, or fromTIME_INPUT_FORMATS if localization is disabled. See alsoformat localization.

TypedChoiceField¶

classTypedChoiceField(**kwargs)[source]¶

Just like aChoiceField, exceptTypedChoiceField takes twoextra arguments,coerce andempty_value.

• Default widget:Select

• Empty value: Whatever you’ve given asempty_value.

• Normalizes to: A value of the type provided by thecoerceargument.

• Validates that the given value exists in the list of choices and can becoerced.

• Error message keys:required,invalid_choice

Takes extra arguments:

coerce¶

A function that takes one argument and returns a coerced value. Examplesinclude the built-inint,float,bool and other types. Defaultsto an identity function. Note that coercion happens after inputvalidation, so it is possible to coerce to a value not present inchoices.

empty_value¶

The value to use to represent “empty.” Defaults to the empty string;None is another common choice here. Note that this value will not becoerced by the function given in thecoerce argument, so choose itaccordingly.

TypedMultipleChoiceField¶

classTypedMultipleChoiceField(**kwargs)[source]¶

Just like aMultipleChoiceField, exceptTypedMultipleChoiceFieldtakes two extra arguments,coerce andempty_value.

• Default widget:SelectMultiple

• Empty value: Whatever you’ve given asempty_value

• Normalizes to: A list of values of the type provided by thecoerceargument.

• Validates that the given values exists in the list of choices and can becoerced.

• Error message keys:required,invalid_choice

Theinvalid_choice error message may contain%(value)s, which will bereplaced with the selected choice.

Takes two extra arguments,coerce andempty_value, as forTypedChoiceField.

URLField¶

classURLField(**kwargs)[source]¶

• Default widget:URLInput

• Empty value: Whatever you’ve given asempty_value.

• Normalizes to: A string.

• UsesURLValidator to validate that thegiven value is a valid URL.

• Error message keys:required,invalid

Has the optional argumentsmax_length,min_length,empty_valuewhich work just as they do forCharField, and one more argument:

assume_scheme¶

New in Django 5.0.

The scheme assumed for URLs provided without one. Defaults to"http". For example, ifassume_scheme is"https" and theprovided value is"example.com", the normalized value will be"https://example.com".

Deprecated since version 5.0:The default value forassume_scheme will change from"http" to"https" in Django 6.0. SetFORMS_URLFIELD_ASSUME_HTTPStransitional setting toTrue to opt into using"https" duringthe Django 5.x release cycle.

UUIDField¶

classUUIDField(**kwargs)[source]¶

• Default widget:TextInput

• Empty value:None

• Normalizes to: AUUID object.

• Error message keys:required,invalid

This field will accept any string format accepted as thehex argumentto theUUID constructor.

ComboField¶

classComboField(**kwargs)[source]¶

• Default widget:TextInput

• Empty value:'' (an empty string)

• Normalizes to: A string.

• Validates the given value against each of the fields specifiedas an argument to theComboField.

• Error message keys:required,invalid

Takes one extra required argument:

fields¶

The list of fields that should be used to validate the field’s value (inthe order in which they are provided).

>>>fromdjango.formsimportComboField>>>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¶

classMultiValueField(fields=(),**kwargs)[source]¶

• Default widget:TextInput

• Empty value:'' (an empty string)

• Normalizes to: the type returned by thecompress method of the subclass.

• Validates the given value against each of the fields specifiedas an argument to theMultiValueField.

• Error message keys:required,invalid,incomplete

Aggregates the logic of multiple fields that together produce a singlevalue.

This field is abstract and must be subclassed. In contrast with thesingle-value fields, subclasses ofMultiValueField must notimplementclean() but instead - implementcompress().

Takes one extra required argument:

fields¶

A tuple of fields whose values are cleaned and subsequently combinedinto a single value. Each value of the field is cleaned by thecorresponding field infields – the first value is cleaned by thefirst field, the second value is cleaned by the second field, etc.Once all fields are cleaned, the list of clean values is combined intoa single value bycompress().

Also takes some optional arguments:

require_all_fields¶

Defaults toTrue, in which case arequired validation errorwill be raised if no value is supplied for any field.

When set toFalse, theField.required attribute can be settoFalse for individual fields to make them optional. If no valueis supplied for a required field, anincomplete validation errorwill be raised.

A defaultincomplete error message can be defined on theMultiValueField subclass, or different messages can be definedon each individual field. For example:

fromdjango.core.validatorsimportRegexValidatorclassPhoneField(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¶

Must be a subclass ofdjango.forms.MultiWidget.Default value isTextInput, whichprobably is not very useful in this case.

compress(data_list)[source]¶

Takes a list of valid values and returns a “compressed” version ofthose values – in a single value. For example,SplitDateTimeField is a subclass which combines a time fieldand a date field into adatetime object.

This method must be implemented in the subclasses.

SplitDateTimeField¶

classSplitDateTimeField(**kwargs)[source]¶

• Default widget:SplitDateTimeWidget

• Empty value:None

• Normalizes to: A Pythondatetime.datetime object.

• Validates that the given value is adatetime.datetime or stringformatted in a particular datetime format.

• Error message keys:required,invalid,invalid_date,invalid_time

Takes two optional arguments:

input_date_formats¶

A list of formats used to attempt to convert a string to a validdatetime.date object.

If noinput_date_formats argument is provided, the default input formatsforDateField are used.

input_time_formats¶

A list of formats used to attempt to convert a string to a validdatetime.time object.

If noinput_time_formats argument is provided, the default input formatsforTimeField are used.

ModelChoiceField¶

classModelChoiceField(**kwargs)[source]¶

• Default widget:Select

• Empty value:None

• Normalizes to: A model instance.

• Validates that the given id exists in the queryset.

• Error message keys:required,invalid_choice

Theinvalid_choice error message may contain%(value)s, which willbe replaced with the selected choice.

Allows the selection of a single model object, suitable for representing aforeign key. Note that the default widget forModelChoiceField becomesimpractical when the number of entries increases. You should avoid using itfor more than 100 items.

A single argument is required:

queryset¶

AQuerySet of model objects from which the choices for the fieldare derived and which is used to validate the user’s selection. It’sevaluated when the form is rendered.

ModelChoiceField also takes several optional arguments:

empty_label¶

By default the<select> widget used byModelChoiceField will have anempty choice at the top of the list. You can change the text of thislabel (which is"---------" by default) with theempty_labelattribute, or you can disable the empty label entirely by settingempty_label toNone:

# A custom empty labelfield1=forms.ModelChoiceField(queryset=...,empty_label="(Nothing)")# No empty labelfield2=forms.ModelChoiceField(queryset=...,empty_label=None)

Note that no empty choice is created (regardless of the value ofempty_label) if aModelChoiceField is required and has adefault initial value, or awidget is set toRadioSelect and theblank argument isFalse.

to_field_name¶

This optional argument is used to specify the field to use as the valueof the choices in the field’s widget. Be sure it’s a unique field forthe model, otherwise the selected value could match more than oneobject. By default it is set toNone, in which case the primary keyof each object will be used. For example:

# No custom to_field_namefield1=forms.ModelChoiceField(queryset=...)

would yield:

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

and:

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

would yield:

<selectid="id_field2"name="field2"><optionvalue="obj1.name">Object1</option><optionvalue="obj2.name">Object2</option>...</select>

blank¶

When using theRadioSelect widget, this optionalboolean argument determines whether an empty choice is created. Bydefault,blank isFalse, in which case no empty choice iscreated.

ModelChoiceField also has the attribute:

iterator¶

The iterator class used to generate field choices fromqueryset. Bydefault,ModelChoiceIterator.

The__str__() method of the model will be called to generate stringrepresentations of the objects for use in the field’s choices. To providecustomized representations, subclassModelChoiceField and overridelabel_from_instance. This method will receive a model object and shouldreturn a string suitable for representing it. For example:

fromdjango.formsimportModelChoiceFieldclassMyModelChoiceField(ModelChoiceField):deflabel_from_instance(self,obj):return"My Object #%i"%obj.id

ModelMultipleChoiceField¶

classModelMultipleChoiceField(**kwargs)[source]¶

• Default widget:SelectMultiple

• Empty value: An emptyQuerySet (self.queryset.none())

• Normalizes to: AQuerySet of model instances.

• Validates that every id in the given list of values exists in thequeryset.

• Error message keys:required,invalid_list,invalid_choice,invalid_pk_value

Theinvalid_choice message may contain%(value)s and theinvalid_pk_value message may contain%(pk)s, which will besubstituted by the appropriate values.

Allows the selection of one or more model objects, suitable forrepresenting a many-to-many relation. As withModelChoiceField,you can uselabel_from_instance to customize the objectrepresentations.

A single argument is required:

queryset¶

Same asModelChoiceField.queryset.

Takes one optional argument:

to_field_name¶

Same asModelChoiceField.to_field_name.

ModelMultipleChoiceField also has the attribute:

iterator¶

Same asModelChoiceField.iterator.

Iterating relationship choices¶

By default,ModelChoiceField andModelMultipleChoiceField useModelChoiceIterator to generate their fieldchoices.

When iterated,ModelChoiceIterator yields 2-tuple choices containingModelChoiceIteratorValue instances as the firstvalue element ineach choice.ModelChoiceIteratorValue wraps the choice value whilemaintaining a reference to the source model instance that can be used in customwidget implementations, for example, to adddata-* attributes to<option> elements.

For example, consider the following models:

fromdjango.dbimportmodelsclassTopping(models.Model):name=models.CharField(max_length=100)price=models.DecimalField(decimal_places=2,max_digits=6)def__str__(self):returnself.nameclassPizza(models.Model):topping=models.ForeignKey(Topping,on_delete=models.CASCADE)

You can use aSelect widget subclass to includethe value ofTopping.price as the HTML attributedata-price for each<option> element:

fromdjangoimportformsclassToppingSelect(forms.Select):defcreate_option(self,name,value,label,selected,index,subindex=None,attrs=None):option=super().create_option(name,value,label,selected,index,subindex,attrs)ifvalue:option["attrs"]["data-price"]=value.instance.pricereturnoptionclassPizzaForm(forms.ModelForm):classMeta:model=Pizzafields=["topping"]widgets={"topping":ToppingSelect}

This will render thePizza.topping select as:

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

For more advanced usage you may subclassModelChoiceIterator in order tocustomize the yielded 2-tuple choices.