diff --git a/docs/index.txt b/docs/index.txt index e6558a7478..d5b37512c9 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -182,6 +182,7 @@ Other batteries included * :ref:`Syndication feeds (RSS/Atom) ` * :ref:`Unicode in Django ` * :ref:`Web design helpers ` + * :ref:`Validators ` The Django open-source project ============================== diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 0d40e5fd5f..6440d2e63d 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -266,7 +266,7 @@ error message keys it uses. The ``validators`` argument lets you provide a list of validation functions for this field. -See the :ref:`validators documentation ` for more information. +See the :ref:`validators documentation ` for more information. Built-in ``Field`` classes -------------------------- diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 8612b742ef..3ccf09b58f 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -303,7 +303,7 @@ underscores to spaces. See :ref:`Verbose field names `. .. attribute:: Field.validators A list of validators to run for this field.See the :ref:`validators -documentation ` for more information. +documentation ` for more information. Field types diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 43f18338a1..b3721d6f62 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -27,6 +27,8 @@ The keyword arguments are simply the names of the fields you've defined on your model. Note that instantiating a model in no way touches your database; for that, you need to ``save()``. +.. _validating-objects: + Validating objects ================== diff --git a/docs/ref/validators.txt b/docs/ref/validators.txt new file mode 100644 index 0000000000..ae15011f27 --- /dev/null +++ b/docs/ref/validators.txt @@ -0,0 +1,145 @@ +.. _ref-validators: + +========== +Validators +========== + +.. versionadded:: 1.2 + +Writing validators +================== + +A validator is just a callable that takes a value, and raises a +``ValidationError`` if it doesn't meet some criteria. They can be useful for +re-using validation logic between different types of fields. + +For example, lets write a validator that only allows even numbers:: + + from django.core.exceptions import ValidationError + + def validate_even(value): + if value % 2 != 0: + raise ValidationError(u'%s is not an even number' % value) + +You can then added this to your model fields via the field's ``validators`` +argument:: + + from django.db import models + + class MyModel(models.Model): + even_field = models.IntegerField(validators=[validate_even]) + +Since values are converted to python before validators are run, you can even +use the same validator with forms:: + + from django import forms + + class MyForm(forms.Form): + even_field = forms.IntegerField(validators=[validate_even]) + +How validators are run +====================== + +See the :ref:`form validation ` for more information on +how validators are run in forms, and :ref:`Validating objects ` +for how they are run in models. + +Built-in validators +=================== + +Django has a collection of callable validators for use with model and form +fields. Many of them are used internally, but they are available for use with +your own fields too. They can be used in addition to, or in lieu of custom +field.clean() methods. + +``RegexValidator`` +------------------ + +.. class:: RegexValidator(regex=None, message=None, code=None) + +.. attribute:: regex=None + +The regular expression to search for the provided ``value``. Raises a +``ValidationError`` if no match was found. + +.. attribute:: code='invalid' + +The error code to use if validation fails. Defaults to ``'invalid'``. + +.. attribute:: message=None + +The error message to use if ``regex`` doesn't match the provided ``value``. + +``URLValidator`` +---------------- + +.. class:: URLValidator(verify_exists=False, validator_user_agent=URL_VALIDATOR_USER_AGENT) + +A ``RegexValidaor`` that ensures a value looks like a URL, and optionally +verifies that the URL actually exists. Raises an error code of ``'invalid'`` +if it doesn't look like a URL, and a code of ``'invalid_link'`` if it doesn't +exist. + +.. attribute:: verify_exists=False + +If ``verify_exists`` is ``True``, this validator checks that the url actually +exists. + +.. attribute:: validator_user_agent=URL_VALIDATOR_USER_AGENT + +If ``verify_exists`` is ``True``, use validator_user_agent as the User-agent +for the request. Defaults to ``settings.URL_VALIDATOR_USER_AGENT``. + +``validate_email`` +------------------ + +A ``RegexValidator`` instance that ensures a value looks like an email address. + +``validate_slug`` +----------------- + +A ``RegexValidator`` instance that ensures a value consists of only +letters, numbers, underscores, or hyphens. + +``validate_ipv4_address`` +------------------------- + +A ``RegexValidator`` instance that ensures a value looks like an IPv4 address. + +``validate_comma_separated_integer_list`` +----------------------------------------- + +A ``RegexValidator`` instance that ensures a value is a comma separated list +of integers. + +``MaxValueValidator`` +--------------------- + +.. class:: MaxValueValidator(max_value) + +Raises a ``ValidationError`` with a code of ``'max_value'`` if ``value`` is +greater than ``max_value``. + +``MinValueValidator`` +--------------------- + +.. class:: MinValueValidator(min_value) + +Raises a ``ValidationError`` with a code of ``'min_value'`` if ``value`` is +less than ``min_value``. + +``MaxLengthValidator`` +---------------------- + +.. class:: MaxLengthValidator(max_length) + +Raises a ``ValidationError`` with a code of ``'max_length'`` if the length of +``value`` is greater than ``max_length``. + +``MinLengthValidator`` +---------------------- + +.. class:: MinLengthValidator(min_length) + +Raises a ``ValidationError`` with a code of ``'min_length'`` if the length of +``value`` is less than ``min_length``.