150 lines
4.3 KiB
Plaintext
150 lines
4.3 KiB
Plaintext
.. _ref-validators:
|
|
|
|
==========
|
|
Validators
|
|
==========
|
|
|
|
.. versionadded:: 1.2
|
|
|
|
Writing validators
|
|
==================
|
|
|
|
A validator is a callable that takes a value and raises a
|
|
``ValidationError`` if it doesn't meet some criteria. Validators can be useful
|
|
for re-using validation logic between different types of fields.
|
|
|
|
For example, here's 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 add this to a model field via the field's ``validators``
|
|
argument::
|
|
|
|
from django.db import models
|
|
|
|
class MyModel(models.Model):
|
|
even_field = models.IntegerField(validators=[validate_even])
|
|
|
|
Because 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 <ref-forms-validation>` for more information on
|
|
how validators are run in forms, and :ref:`Validating objects
|
|
<validating-objects>` for how they're run in models. Note that validators will
|
|
not be run automatically when you save a model, but if you are using a
|
|
``ModelForm``, it will run your validators on any fields that are included in
|
|
your form. See the :ref:`ModelForm documentation <topics-forms-modelforms>`
|
|
for information on how model validation interacts with forms.
|
|
|
|
Built-in validators
|
|
===================
|
|
|
|
Django has a collection of callable validators for use with model and form
|
|
fields. They're used internally but 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 ``RegexValidator`` that ensures a value looks like a URL and optionally
|
|
verifies that the URL actually exists (i.e., doesn't return a 404 status code).
|
|
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``, it uses ``validator_user_agent`` as the "User-agent"
|
|
for the request. This defaults to ``settings.URL_VALIDATOR_USER_AGENT``.
|
|
|
|
``validate_email``
|
|
------------------
|
|
|
|
A ``RegexValidator`` instance that ensures a value looks like an e-mail 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``.
|