Form.cleaned_data
Each field in a Form
class is responsible not only for validating data, but also for “cleaning” it – normalizing it to a consistent format. This is a nice feature, because it allows data for a particular field to be input in a variety of ways, always resulting in consistent output.
For example, DateField
normalizes input into a Python datetime.date
object. Regardless of whether you pass it a string in the format '1994-07-15'
, a datetime.date
object, or a number of other formats, DateField
will always normalize it to a datetime.date
object as long as it’s valid.
Once you’ve created a Form
instance with a set of data and validated it, you can access the clean data via its cleaned_data
attribute:
>>> data = {'subject': 'hello', ... 'message': 'Hi there', ... 'sender': 'foo@example.com', ... 'cc_myself': True} >>> f = ContactForm(data) >>> f.is_valid() True >>> f.cleaned_data {'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}
Note that any text-based field – such as CharField
or EmailField
– always cleans the input into a Unicode string. We’ll cover the encoding implications later in this document.
If your data does not validate, the cleaned_data
dictionary contains only the valid fields:
>>> data = {'subject': '', ... 'message': 'Hi there', ... 'sender': 'invalid email address', ... 'cc_myself': True} >>> f = ContactForm(data) >>> f.is_valid() False >>> f.cleaned_data {'cc_myself': True, 'message': 'Hi there'}
cleaned_data
will always only contain a key for fields defined in the Form
, even if you pass extra data when you define the Form
. In this example, we pass a bunch of extra fields to the ContactForm
constructor, but cleaned_data
contains only the form’s fields:
>>> data = {'subject': 'hello', ... 'message': 'Hi there', ... 'sender': 'foo@example.com', ... 'cc_myself': True, ... 'extra_field_1': 'foo', ... 'extra_field_2': 'bar', ... 'extra_field_3': 'baz'} >>> f = ContactForm(data) >>> f.is_valid() True >>> f.cleaned_data # Doesn't contain extra_field_1, etc. {'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}
When the Form
is valid, cleaned_data
will include a key and value for all its fields, even if the data didn’t include a value for some optional fields. In this example, the data dictionary doesn’t include a value for the nick_name
field, but cleaned_data
includes it, with an empty value:
>>> from django.forms import Form >>> class OptionalPersonForm(Form): ... first_name = CharField() ... last_name = CharField() ... nick_name = CharField(required=False) >>> data = {'first_name': 'John', 'last_name': 'Lennon'} >>> f = OptionalPersonForm(data) >>> f.is_valid() True >>> f.cleaned_data {'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}
In this above example, the cleaned_data
value for nick_name
is set to an empty string, because nick_name
is CharField
, and CharField
s treat empty values as an empty string. Each field type knows what its “blank” value is – e.g., for DateField
, it’s None
instead of the empty string. For full details on each field’s behavior in this case, see the “Empty value” note for each field in the “Built-in Field
classes” section below.
You can write code to perform validation for particular form fields (based on their name) or for the form as a whole (considering combinations of various fields). More information about this is in Form and field validation.
Please login to continue.