Since newforms is mostly undocumented at the moment this page summarizes some useful information. This documentation should be considered complementary to the documentation on It's mostly information extracted from the unit tests for newforms at the moment.

Widgets Unit tests

Each Widget subclass corresponds to an HTML form widget. A Widget knows how to render itself, given a field name and some data. Widgets don't perform validation.

Widget types

List of Widget types with their associated unit test for easy lookup.

TextInput Unit test
PasswordInput Unit test
HiddenInput Unit test
MultipleHiddenInput Unit test
FileInput Unit test
Textarea Unit test
CheckboxInput Unit test
Select Unit test
NullBooleanSelect Unit test
SelectMultiple Unit test
RadioSelect Unit test
CheckboxSelectMultiple Unit test
Multi Unit test
SplitDateTime Unit test


Each Field class does some sort of validation. Each Field has a clean() method, which either raises django.newforms.ValidationError or returns the "clean" data -- usually a Unicode object, but, in some rare cases, a list.

Each Field's __init__() takes at least these parameters:

  • required -- Boolean that specifies whether the field is required. True by default.
  • widget -- A Widget class, or instance of a Widget class, that should be used for this Field when displaying it. Each Field has a default widget that it'll use if you don't specify this. In most cases, the default widget is TextInput.
  • label -- A verbose name for this field, for use in displaying this field in a form. By default, Django will use a "pretty" version of the form field name, if the Field is part of a Form.
  • initial -- A value to use in this Field's initial display. This value is *not* used as a fallback if data isn't given.

Other than that, the Field subclasses have class-specific options for __init__(). For example, CharField has a max_length option.

Field types Unit tests

List of field types with their associated unit test for easy lookup.

CharField Unit test


  • max_length -- (optional) Maximum number of characters
  • min_length -- (optional) Minimum number of characters
IntegerField Unit test


  • max_value -- (optional) Maximum value
  • min_value -- (optional) Minimum value
FloatField Unit test
DecimalField Unit test
DateField Unit test


  • input_formats -- (optional) A list of strftime() input formats. These will override all other input formats
TimeField Unit test
DateTimeField Unit test
RegexField Unit test


  • regex -- The regular expression in compiled or string form that the input should match
EmailField Unit test


  • min_length -- Minimum length
  • max_length -- Maximum length
URLField Unit test


  • min_length -- Minimum length
  • max_length -- Maximum length
  • verify_exists -- Defaults to False. If True, verifies that the URL is live on the Internet and doesn't return a 404 or 500
BooleanField Unit test

Since HTML forms either return something like 'fieldname=on' in request.POST or request.GET, this value may not be set in form.clean_data().


  • None
ChoiceField Unit test


  • choices -- A list of (key, value) pairs
MultipleChoiceField Unit test


  • choices -- A list of (key, value) pairs
ComboField Unit test

ComboField takes a list of fields that should be used to validate a value, in that order.


  • choices -- A list of fields used to validate the input value
SplitDateTimeField Unit test

Forms Unit test

A Form is a collection of Fields. It knows how to validate a set of data and it knows how to render itself in a couple of default ways (e.g., an HTML table).

You can pass it data in __init__(), as a dictionary, this data will usually come from request.POST or request.GET. The dictionaries passed to form need not be complete, a partial or empty dictionary is valid too. If you don't pass any values to the Form's __init__(), or if you pass None, the Form won't do any validation. Form.errors will be an empty dictionary but Form.is_valid() will return False.

Last modified 17 years ago Last modified on Jul 27, 2007, 2:08:26 PM
Note: See TracWiki for help on using the wiki.
Back to Top