From 65411d01d448ff0cd4abd14eee14cf60b5f8fc20 Mon Sep 17 00:00:00 2001 From: Nishanth Amuluru Date: Sat, 8 Jan 2011 11:20:57 +0530 Subject: Added buildout stuff and made changes accordingly --HG-- rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt rename : taskapp/models.py => parts/django/django/conf/app_template/models.py rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py rename : taskapp/views.py => parts/django/django/conf/app_template/views.py rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py rename : profile/forms.py => pytask/profile/forms.py rename : profile/management/__init__.py => pytask/profile/management/__init__.py rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py rename : profile/models.py => pytask/profile/models.py rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py rename : taskapp/tests.py => pytask/profile/tests.py rename : profile/urls.py => pytask/profile/urls.py rename : profile/utils.py => pytask/profile/utils.py rename : profile/views.py => pytask/profile/views.py rename : static/css/base.css => pytask/static/css/base.css rename : taskapp/tests.py => pytask/taskapp/tests.py rename : taskapp/views.py => pytask/taskapp/views.py rename : templates/base.html => pytask/templates/base.html rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html rename : templates/profile/edit.html => pytask/templates/profile/edit.html rename : templates/profile/view.html => pytask/templates/profile/view.html rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html rename : templates/registration/activate.html => pytask/templates/registration/activate.html rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html rename : templates/registration/login.html => pytask/templates/registration/login.html rename : templates/registration/logout.html => pytask/templates/registration/logout.html rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html rename : utils.py => pytask/utils.py --- parts/django/docs/ref/forms/fields.txt | 939 +++++++++++++++++++++++++++++++++ 1 file changed, 939 insertions(+) create mode 100644 parts/django/docs/ref/forms/fields.txt (limited to 'parts/django/docs/ref/forms/fields.txt') diff --git a/parts/django/docs/ref/forms/fields.txt b/parts/django/docs/ref/forms/fields.txt new file mode 100644 index 0000000..91f245a --- /dev/null +++ b/parts/django/docs/ref/forms/fields.txt @@ -0,0 +1,939 @@ +=========== +Form fields +=========== + +.. module:: django.forms.fields + :synopsis: Django's built-in form fields. + +.. currentmodule:: django.forms + +.. class:: Field(**kwargs) + +When you create a ``Form`` class, the most important part is defining the +fields of the form. Each field has custom validation logic, along with a few +other hooks. + +.. method:: Field.clean(value) + +Although the primary way you'll use ``Field`` classes is in ``Form`` classes, +you can also instantiate them and use them directly to get a better idea of +how they work. Each ``Field`` instance has a ``clean()`` method, which takes +a single argument and either raises a ``django.forms.ValidationError`` +exception or returns the clean value:: + + >>> from django import forms + >>> f = forms.EmailField() + >>> f.clean('foo@example.com') + u'foo@example.com' + >>> f.clean(u'foo@example.com') + u'foo@example.com' + >>> f.clean('invalid e-mail address') + Traceback (most recent call last): + ... + ValidationError: [u'Enter a valid e-mail address.'] + +Core field arguments +-------------------- + +Each ``Field`` class constructor takes at least these arguments. Some +``Field`` classes take additional, field-specific arguments, but the following +should *always* be accepted: + +``required`` +~~~~~~~~~~~~ + +.. attribute:: Field.required + +By default, each ``Field`` class assumes the value is required, so if you pass +an empty value -- either ``None`` or the empty string (``""``) -- then +``clean()`` will raise a ``ValidationError`` exception:: + + >>> f = forms.CharField() + >>> f.clean('foo') + u'foo' + >>> f.clean('') + Traceback (most recent call last): + ... + ValidationError: [u'This field is required.'] + >>> f.clean(None) + Traceback (most recent call last): + ... + ValidationError: [u'This field is required.'] + >>> f.clean(' ') + u' ' + >>> f.clean(0) + u'0' + >>> f.clean(True) + u'True' + >>> f.clean(False) + u'False' + +To specify that a field is *not* required, pass ``required=False`` to the +``Field`` constructor:: + + >>> f = forms.CharField(required=False) + >>> f.clean('foo') + u'foo' + >>> f.clean('') + u'' + >>> f.clean(None) + u'' + >>> f.clean(0) + u'0' + >>> f.clean(True) + u'True' + >>> f.clean(False) + u'False' + +If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value, +then ``clean()`` will return a *normalized* empty value rather than raising +``ValidationError``. For ``CharField``, this will be a Unicode empty string. +For other ``Field`` classes, it might be ``None``. (This varies from field to +field.) + +``label`` +~~~~~~~~~ + +.. attribute:: Field.label + +The ``label`` argument lets you specify the "human-friendly" label for this +field. This is used when the ``Field`` is displayed in a ``Form``. + +As explained in "Outputting forms as HTML" above, the default label for a +``Field`` is generated from the field name by converting all underscores to +spaces and upper-casing the first letter. Specify ``label`` if that default +behavior doesn't result in an adequate label. + +Here's a full example ``Form`` that implements ``label`` for two of its fields. +We've specified ``auto_id=False`` to simplify the output:: + + >>> class CommentForm(forms.Form): + ... name = forms.CharField(label='Your name') + ... url = forms.URLField(label='Your Web site', required=False) + ... comment = forms.CharField() + >>> f = CommentForm(auto_id=False) + >>> print f + Your name: + Your Web site: + Comment: + +``initial`` +~~~~~~~~~~~ + +.. attribute:: Field.initial + +The ``initial`` argument lets you specify the initial value to use when +rendering this ``Field`` in an unbound ``Form``. + +To specify dynamic initial data, see the :attr:`Form.initial` parameter. + +The use-case for this is when you want to display an "empty" form in which a +field is initialized to a particular value. For example:: + + >>> class CommentForm(forms.Form): + ... name = forms.CharField(initial='Your name') + ... url = forms.URLField(initial='http://') + ... comment = forms.CharField() + >>> f = CommentForm(auto_id=False) + >>> print f + Name: + Url: + Comment: + +You may be thinking, why not just pass a dictionary of the initial values as +data when displaying the form? Well, if you do that, you'll trigger validation, +and the HTML output will include any validation errors:: + + >>> class CommentForm(forms.Form): + ... name = forms.CharField() + ... url = forms.URLField() + ... comment = forms.CharField() + >>> default_data = {'name': 'Your name', 'url': 'http://'} + >>> f = CommentForm(default_data, auto_id=False) + >>> print f + Name: + Url: + Comment: + +This is why ``initial`` values are only displayed for unbound forms. For bound +forms, the HTML output will use the bound data. + +Also note that ``initial`` values are *not* used as "fallback" data in +validation if a particular field's value is not given. ``initial`` values are +*only* intended for initial form display:: + + >>> class CommentForm(forms.Form): + ... name = forms.CharField(initial='Your name') + ... url = forms.URLField(initial='http://') + ... comment = forms.CharField() + >>> data = {'name': '', 'url': '', 'comment': 'Foo'} + >>> f = CommentForm(data) + >>> f.is_valid() + False + # The form does *not* fall back to using the initial values. + >>> f.errors + {'url': [u'This field is required.'], 'name': [u'This field is required.']} + +Instead of a constant, you can also pass any callable:: + + >>> import datetime + >>> class DateForm(forms.Form): + ... day = forms.DateField(initial=datetime.date.today) + >>> print DateForm() + Day: + +The callable will be evaluated only when the unbound form is displayed, not when it is defined. + +``widget`` +~~~~~~~~~~ + +.. attribute:: Field.widget + +The ``widget`` argument lets you specify a ``Widget`` class to use when +rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information. + +``help_text`` +~~~~~~~~~~~~~ + +.. attribute:: Field.help_text + +The ``help_text`` argument lets you specify descriptive text for this +``Field``. If you provide ``help_text``, it will be displayed next to the +``Field`` when the ``Field`` is rendered by one of the convenience ``Form`` +methods (e.g., ``as_ul()``). + +Here's a full example ``Form`` that implements ``help_text`` for two of its +fields. We've specified ``auto_id=False`` to simplify the output:: + + >>> 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 e-mail address, please.') + ... cc_myself = forms.BooleanField(required=False) + >>> f = HelpTextContactForm(auto_id=False) + >>> print f.as_table() + Subject:
100 characters max. + Message: + Sender:
A valid e-mail address, please. + Cc myself: + >>> print f.as_ul() +
  • Subject: 100 characters max.
    • +
  • Message:
    • +
  • Sender: A valid e-mail address, please.
    • +
  • Cc myself:
    • + >>> print f.as_p() +

    Subject: 100 characters max.

    +

    Message:

    +

    Sender: A valid e-mail address, please.

    +

    Cc myself:

    + +``error_messages`` +~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +.. attribute:: Field.error_messages + +The ``error_messages`` argument lets you override the default messages that the +field will raise. Pass in a dictionary with keys matching the error messages you +want to override. For example, here is the default error message:: + + >>> generic = forms.CharField() + >>> generic.clean('') + Traceback (most recent call last): + ... + ValidationError: [u'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: [u'Please enter your name'] + +In the `built-in Field classes`_ section below, each ``Field`` defines the +error message keys it uses. + +``validators`` +~~~~~~~~~~~~~~ + +.. versionadded:: 1.2 + +.. attribute:: Field.validators + +The ``validators`` argument lets you provide a list of validation functions +for this field. + +See the :doc:`validators documentation ` for more information. + +``localize`` +~~~~~~~~~~~~ + +.. versionadded:: 1.2 + +.. attribute:: Field.localize + +The ``localize`` argument enables the localization of form data, input as well +as the rendered output. + +See the :ref:`format localization ` documentation for +more information. + + +Built-in ``Field`` classes +-------------------------- + +Naturally, the ``forms`` library comes with a set of ``Field`` classes that +represent common validation needs. This section documents each built-in field. + +For each field, we describe the default widget used if you don't specify +``widget``. We also specify the value returned when you provide an empty value +(see the section on ``required`` above to understand what that means). + +``BooleanField`` +~~~~~~~~~~~~~~~~ + +.. class:: BooleanField(**kwargs) + + * Default widget: ``CheckboxInput`` + * Empty value: ``False`` + * Normalizes to: A Python ``True`` or ``False`` value. + * Validates that the value is ``True`` (e.g. the check box is checked) if + the field has ``required=True``. + * Error message keys: ``required`` + +.. versionchanged:: 1.0 + The empty value for a ``CheckboxInput`` (and hence the standard + ``BooleanField``) has changed to return ``False`` instead of ``None`` in + the Django 1.0. + +.. note:: + + Since all ``Field`` subclasses have ``required=True`` by default, the + validation condition here is important. If you want to include a boolean + in your form that can be either ``True`` or ``False`` (e.g. a checked or + unchecked checkbox), you must remember to pass in ``required=False`` when + creating the ``BooleanField``. + +``CharField`` +~~~~~~~~~~~~~ + +.. class:: CharField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates ``max_length`` or ``min_length``, if they are provided. + Otherwise, all inputs are valid. + * Error message keys: ``required``, ``max_length``, ``min_length`` + +Has two optional arguments for validation: + +.. attribute:: CharField.max_length +.. attribute:: CharField.min_length + + If provided, these arguments ensure that the string is at most or at least + the given length. + +``ChoiceField`` +~~~~~~~~~~~~~~~ + +.. class:: ChoiceField(**kwargs) + + * Default widget: ``Select`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value exists in the list of choices. + * Error message keys: ``required``, ``invalid_choice`` + +Takes one extra required argument: + +.. attribute:: ChoiceField.choices + + An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this + field. This argument accepts the same formats as the ``choices`` argument + to a model field. See the :ref:`model field reference documentation on + choices ` for more details. + +``TypedChoiceField`` +~~~~~~~~~~~~~~~~~~~~ + +.. class:: TypedChoiceField(**kwargs) + +Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes an +extra ``coerce`` argument. + + * Default widget: ``Select`` + * Empty value: Whatever you've given as ``empty_value`` + * Normalizes to: the value returned by the ``coerce`` argument. + * Validates that the given value exists in the list of choices. + * Error message keys: ``required``, ``invalid_choice`` + +Takes extra arguments: + +.. attribute:: TypedChoiceField.coerce + + A function that takes one argument and returns a coerced value. Examples + include the built-in ``int``, ``float``, ``bool`` and other types. Defaults + to an identity function. + +.. attribute:: TypedChoiceField.empty_value + + The value to use to represent "empty." Defaults to the empty string; + ``None`` is another common choice here. + +``DateField`` +~~~~~~~~~~~~~ + +.. class:: DateField(**kwargs) + + * Default widget: ``DateInput`` + * Empty value: ``None`` + * Normalizes to: A Python ``datetime.date`` object. + * Validates that the given value is either a ``datetime.date``, + ``datetime.datetime`` or string formatted in a particular date format. + * Error message keys: ``required``, ``invalid`` + +Takes one optional argument: + +.. attribute:: DateField.input_formats + + A list of formats used to attempt to convert a string to a valid + ``datetime.date`` object. + +If no ``input_formats`` argument is provided, the default input formats are:: + + '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06' + '%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006' + '%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006' + '%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006' + '%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006' + +.. versionchanged:: 1.1 + The ``DateField`` previously used a ``TextInput`` widget by default. It now + uses a ``DateInput`` widget. + +``DateTimeField`` +~~~~~~~~~~~~~~~~~ + +.. class:: DateTimeField(**kwargs) + + * Default widget: ``DateTimeInput`` + * Empty value: ``None`` + * Normalizes to: A Python ``datetime.datetime`` object. + * Validates that the given value is either a ``datetime.datetime``, + ``datetime.date`` or string formatted in a particular datetime format. + * Error message keys: ``required``, ``invalid`` + +Takes one optional argument: + +.. attribute:: DateTimeField.input_formats + + A list of formats used to attempt to convert a string to a valid + ``datetime.datetime`` object. + +If no ``input_formats`` argument is provided, the default input formats are:: + + '%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59' + '%Y-%m-%d %H:%M', # '2006-10-25 14:30' + '%Y-%m-%d', # '2006-10-25' + '%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59' + '%m/%d/%Y %H:%M', # '10/25/2006 14:30' + '%m/%d/%Y', # '10/25/2006' + '%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59' + '%m/%d/%y %H:%M', # '10/25/06 14:30' + '%m/%d/%y', # '10/25/06' + +.. versionchanged:: 1.0 + The ``DateTimeField`` used to use a ``TextInput`` widget by default. This has now changed. + +``DecimalField`` +~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +.. class:: DecimalField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``None`` + * Normalizes to: A Python ``decimal``. + * Validates that the given value is a decimal. Leading and trailing + whitespace is ignored. + * Error message keys: ``required``, ``invalid``, ``max_value``, + ``min_value``, ``max_digits``, ``max_decimal_places``, + ``max_whole_digits`` + +Takes four optional arguments: + +.. attribute:: DecimalField.max_value +.. attribute:: DecimalField.min_value + + These attributes define the limits for the fields value. + +.. attribute:: DecimalField.max_digits + + The maximum number of digits (those before the decimal point plus those + after the decimal point, with leading zeros stripped) permitted in the + value. + +.. attribute:: DecimalField.decimal_places + + The maximum number of decimal places permitted. + +``EmailField`` +~~~~~~~~~~~~~~ + +.. class:: EmailField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value is a valid e-mail address, using a + moderately complex regular expression. + * Error message keys: ``required``, ``invalid`` + +Has two optional arguments for validation, ``max_length`` and ``min_length``. +If provided, these arguments ensure that the string is at most or at least the +given length. + +.. versionchanged:: 1.2 + The EmailField previously did not recognize e-mail addresses as valid that + contained an IDN (Internationalized Domain Name; a domain containing + unicode characters) domain part. This has now been corrected. + +``FileField`` +~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +.. class:: FileField(**kwargs) + + * Default widget: ``FileInput`` + * Empty value: ``None`` + * Normalizes to: An ``UploadedFile`` object that wraps the file content + and file name into a single object. + * Validates that non-empty file data has been bound to the form. + * Error message keys: ``required``, ``invalid``, ``missing``, ``empty`` + +To learn more about the ``UploadedFile`` object, see the :doc:`file uploads +documentation `. + +When you use a ``FileField`` in a form, you must also remember to +:ref:`bind the file data to the form `. + +``FilePathField`` +~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +.. class:: FilePathField(**kwargs) + + * Default widget: ``Select`` + * Empty value: ``None`` + * Normalizes to: A unicode object + * 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 three +extra arguments; only ``path`` is required: + +.. attribute:: FilePathField.path + + The absolute path to the directory whose contents you want listed. This + directory must exist. + +.. attribute:: FilePathField.recursive + + If ``False`` (the default) only the direct contents of ``path`` will be + offered as choices. If ``True``, the directory will be descended into + recursively and all descendants will be listed as choices. + +.. attribute:: FilePathField.match + + A regular expression pattern; only files with names matching this expression + will be allowed as choices. + +``FloatField`` +~~~~~~~~~~~~~~ + + * Default widget: ``TextInput`` + * Empty value: ``None`` + * Normalizes to: A Python float. + * Validates that the given value is an float. Leading and trailing + whitespace is allowed, as in Python's ``float()`` function. + * Error message keys: ``required``, ``invalid``, ``max_value``, + ``min_value`` + +Takes two optional arguments for validation, ``max_value`` and ``min_value``. +These control the range of values permitted in the field. + +``ImageField`` +~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +.. class:: ImageField(**kwargs) + + * Default widget: ``FileInput`` + * Empty value: ``None`` + * Normalizes to: An ``UploadedFile`` object that wraps the file content + and file name into a single object. + * Validates that file data has been bound to the form, and that the + file is of an image format understood by PIL. + * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``, + ``invalid_image`` + +Using an ImageField requires that the `Python Imaging Library`_ is installed. + +When you use an ``ImageField`` on a form, you must also remember to +:ref:`bind the file data to the form `. + +.. _Python Imaging Library: http://www.pythonware.com/products/pil/ + +``IntegerField`` +~~~~~~~~~~~~~~~~ + +.. class:: IntegerField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``None`` + * Normalizes to: A Python integer or long integer. + * Validates that the given value is an integer. Leading and trailing + whitespace is allowed, as in Python's ``int()`` function. + * Error message keys: ``required``, ``invalid``, ``max_value``, + ``min_value`` + +Takes two optional arguments for validation: + +.. attribute:: IntegerField.max_value +.. attribute:: IntegerField.min_value + + These control the range of values permitted in the field. + +``IPAddressField`` +~~~~~~~~~~~~~~~~~~ + +.. class:: IPAddressField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value is a valid IPv4 address, using a regular + expression. + * Error message keys: ``required``, ``invalid`` + +``MultipleChoiceField`` +~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: MultipleChoiceField(**kwargs) + + * Default widget: ``SelectMultiple`` + * Empty value: ``[]`` (an empty list) + * Normalizes to: A list of Unicode objects. + * Validates that every value in the given list of values exists in the list + of choices. + * Error message keys: ``required``, ``invalid_choice``, ``invalid_list`` + +Takes one extra argument, ``choices``, as for ``ChoiceField``. + +``NullBooleanField`` +~~~~~~~~~~~~~~~~~~~~ + +.. class:: NullBooleanField(**kwargs) + + * Default widget: ``NullBooleanSelect`` + * Empty value: ``None`` + * Normalizes to: A Python ``True``, ``False`` or ``None`` value. + * Validates nothing (i.e., it never raises a ``ValidationError``). + +``RegexField`` +~~~~~~~~~~~~~~ + +.. class:: RegexField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value matches against a certain regular + expression. + * Error message keys: ``required``, ``invalid`` + +Takes one required argument: + +.. attribute:: RegexField.regex + + A regular expression specified either as a string or a compiled regular + expression object. + +Also takes ``max_length`` and ``min_length``, which work just as they do for +``CharField``. + +The optional argument ``error_message`` is also accepted for backwards +compatibility. The preferred way to provide an error message is to use the +``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key +and the error message as the value. + +``SlugField`` +~~~~~~~~~~~~~ + +.. class:: SlugField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value contains only letters, numbers, + underscores, and hyphens. + * Error messages: ``required``, ``invalid`` + +This field is intended for use in representing a model +:class:`~django.db.models.SlugField` in forms. + +``TimeField`` +~~~~~~~~~~~~~ + +.. class:: TimeField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``None`` + * Normalizes to: A Python ``datetime.time`` object. + * Validates that the given value is either a ``datetime.time`` or string + formatted in a particular time format. + * Error message keys: ``required``, ``invalid`` + +Takes one optional argument: + +.. attribute:: TimeField.input_formats + + A list of formats used to attempt to convert a string to a valid + ``datetime.time`` object. + +If no ``input_formats`` argument is provided, the default input formats are:: + + '%H:%M:%S', # '14:30:59' + '%H:%M', # '14:30' + +``URLField`` +~~~~~~~~~~~~ + +.. class:: URLField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value is a valid URL. + * Error message keys: ``required``, ``invalid``, ``invalid_link`` + +Takes the following optional arguments: + +.. attribute:: URLField.max_length +.. attribute:: URLField.min_length + + Same as ``CharField.max_length`` and ``CharField.min_length``. + +.. attribute:: URLField.verify_exists + + If ``True``, the validator will attempt to load the given URL, raising + ``ValidationError`` if the page gives a 404. Defaults to ``False``. + +.. attribute:: URLField.validator_user_agent + + String used as the user-agent used when checking for a URL's existence. + Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting. + +.. versionchanged:: 1.2 + The URLField previously did not recognize URLs as valid that contained an IDN + (Internationalized Domain Name; a domain name containing unicode characters) + domain name. This has now been corrected. + + +Slightly complex built-in ``Field`` classes +------------------------------------------- + +``ComboField`` +~~~~~~~~~~~~~~ + +.. class:: ComboField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value against each of the fields specified + as an argument to the ``ComboField``. + * Error message keys: ``required``, ``invalid`` + +Takes one extra required argument: + +.. attribute:: ComboField.fields + + The list of fields that should be used to validate the field's value (in + the order in which they are provided). + + >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) + >>> f.clean('test@example.com') + u'test@example.com' + >>> f.clean('longemailaddress@example.com') + Traceback (most recent call last): + ... + ValidationError: [u'Ensure this value has at most 20 characters (it has 28).'] + +``MultiValueField`` +~~~~~~~~~~~~~~~~~~~ + +.. class:: MultiValueField(**kwargs) + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: the type returned by the ``compress`` method of the subclass. + * Validates that the given value against each of the fields specified + as an argument to the ``MultiValueField``. + * Error message keys: ``required``, ``invalid`` + + This abstract field (must be subclassed) aggregates the logic of multiple + fields. Subclasses should not have to implement clean(). Instead, they must + implement compress(), which takes a list of valid values and returns a + "compressed" version of those values -- a single value. For example, + :class:`SplitDateTimeField` is a subclass which combines a time field and + a date field into a datetime object. + +Takes one extra required argument: + +.. attribute:: MultiValueField.fields + + A list of fields which are cleaned into a single field. Each value in + ``clean`` is cleaned by the corresponding field in ``fields`` -- the first + value is cleaned by the first field, the second value is cleaned by + the second field, etc. Once all fields are cleaned, the list of clean + values is "compressed" into a single value. + +``SplitDateTimeField`` +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: SplitDateTimeField(**kwargs) + + * Default widget: ``SplitDateTimeWidget`` + * Empty value: ``None`` + * Normalizes to: A Python ``datetime.datetime`` object. + * Validates that the given value is a ``datetime.datetime`` or string + formatted in a particular datetime format. + * Error message keys: ``required``, ``invalid`` + +Takes two optional arguments: + +.. attribute:: SplitDateTimeField.input_date_formats + + A list of formats used to attempt to convert a string to a valid + ``datetime.date`` object. + +If no ``input_date_formats`` argument is provided, the default input formats +for ``DateField`` are used. + +.. attribute:: SplitDateTimeField.input_time_formats + + A list of formats used to attempt to convert a string to a valid + ``datetime.time`` object. + +If no ``input_time_formats`` argument is provided, the default input formats +for ``TimeField`` are used. + +.. versionchanged:: 1.1 + The ``SplitDateTimeField`` previously used two ``TextInput`` widgets by + default. The ``input_date_formats`` and ``input_time_formats`` arguments + are also new. + +Fields which handle relationships +--------------------------------- + +Two fields are available for representing relationships between +models: :class:`ModelChoiceField` and +:class:`ModelMultipleChoiceField`. Both of these fields require a +single ``queryset`` parameter that is used to create the choices for +the field. Upon form validation, these fields will place either one +model object (in the case of ``ModelChoiceField``) or multiple model +objects (in the case of ``ModelMultipleChoiceField``) into the +``cleaned_data`` dictionary of the form. + +``ModelChoiceField`` +~~~~~~~~~~~~~~~~~~~~ + +.. class:: ModelChoiceField(**kwargs) + + * 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`` + +Allows the selection of a single model object, suitable for +representing a foreign key. A single argument is required: + +.. attribute:: ModelChoiceField.queryset + + A ``QuerySet`` of model objects from which the choices for the + field will be derived, and which will be used to validate the + user's selection. + +``ModelChoiceField`` also takes one optional argument: + +.. attribute:: ModelChoiceField.empty_label + + By default the ``