/docs/ref/validators.txt

  1==========
  2Validators
  3==========
  4
  5.. versionadded:: 1.2
  6.. module:: django.core.validators
  7    :synopsis: Validation utilities and base classes
  8
  9Writing validators
 10==================
 11
 12A validator is a callable that takes a value and raises a
 13:exc:`~django.core.exceptions.ValidationError` if it doesn't meet some
 14criteria. Validators can be useful for re-using validation logic between
 15different types of fields.
 16
 17For example, here's a validator that only allows even numbers::
 18
 19    from django.core.exceptions import ValidationError
 20
 21    def validate_even(value):
 22        if value % 2 != 0:
 23            raise ValidationError(u'%s is not an even number' % value)
 24
 25You can add this to a model field via the field's :attr:`~django.db.models.Field.validators`
 26argument::
 27
 28    from django.db import models
 29
 30    class MyModel(models.Model):
 31        even_field = models.IntegerField(validators=[validate_even])
 32
 33Because values are converted to Python before validators are run, you can even
 34use the same validator with forms::
 35
 36    from django import forms
 37
 38    class MyForm(forms.Form):
 39        even_field = forms.IntegerField(validators=[validate_even])
 40
 41How validators are run
 42======================
 43
 44See the :doc:`form validation </ref/forms/validation>` for more information on
 45how validators are run in forms, and :ref:`Validating objects
 46<validating-objects>` for how they're run in models. Note that validators will
 47not be run automatically when you save a model, but if you are using a
 48:class:`~django.forms.ModelForm`, it will run your validators on any fields
 49that are included in your form. See the
 50:doc:`ModelForm documentation </topics/forms/modelforms>` for information on
 51how model validation interacts with forms.
 52
 53Built-in validators
 54===================
 55
 56The :mod:`django.core.validators` module contains a collection of callable
 57validators for use with model and form fields. They're used internally but
 58are available for use with your own fields, too. They can be used in addition
 59to, or in lieu of custom ``field.clean()`` methods.
 60
 61``RegexValidator``
 62------------------
 63.. class:: RegexValidator(regex, [message=None, code=None])
 64
 65    .. attribute:: regex
 66
 67        The regular expression pattern to search for the provided ``value``,
 68        or a pre-compiled regular expression. Raises a
 69        :exc:`~django.core.exceptions.ValidationError` with :attr:`.message`
 70        and :attr:`.code` if no match is found.
 71
 72    .. attribute:: message
 73
 74        The error message used by :exc:`~django.core.exceptions.ValidationError`
 75        if validation fails. If no :attr:`.message` is specified, a generic
 76        ``"Enter a valid value"`` message is used. Default value: ``None``.
 77
 78    .. attribute:: code
 79
 80        The error code used by :exc:`~django.core.exceptions.ValidationError`
 81        if validation fails. If :attr:`.code` is not specified, ``"invalid"``
 82        is used. Default value: ``None``.
 83
 84``URLValidator``
 85----------------
 86.. class:: URLValidator([verify_exists=False, validator_user_agent=URL_VALIDATOR_USER_AGENT])
 87
 88    A :class:`RegexValidator` that ensures a value looks like a URL and
 89    optionally verifies that the URL actually exists (i.e., doesn't return a
 90    404 status code). Raises an error code of ``'invalid'`` if it doesn't look
 91    like a URL, and a code of ``'invalid_link'`` if it doesn't exist.
 92
 93    .. attribute:: verify_exists
 94
 95        Default value: ``False``. If set to ``True``, this validator checks
 96        that the URL actually exists.
 97
 98    .. attribute:: validator_user_agent
 99
100        If :attr:`.verify_exists` is ``True``, Django uses the value of
101        :attr:`.validator_user_agent` as the "User-agent" for the request. This
102        defaults to :setting:`settings.URL_VALIDATOR_USER_AGENT <URL_VALIDATOR_USER_AGENT>`.
103
104``validate_email``
105------------------
106.. data:: validate_email
107
108    A :class:`RegexValidator` instance that ensures a value looks like an
109    e-mail address.
110
111``validate_slug``
112-----------------
113.. data:: validate_slug
114
115    A :class:`RegexValidator` instance that ensures a value consists of only
116    letters, numbers, underscores or hyphens.
117
118``validate_ipv4_address``
119-------------------------
120.. data:: validate_ipv4_address
121
122    A :class:`RegexValidator` instance that ensures a value looks like an IPv4
123    address.
124
125``validate_comma_separated_integer_list``
126-----------------------------------------
127.. data:: validate_comma_separated_integer_list
128
129    A :class:`RegexValidator` instance that ensures a value is a
130    comma-separated list of integers.
131
132``MaxValueValidator``
133---------------------
134.. class:: MaxValueValidator(max_value)
135
136    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
137    ``'max_value'`` if ``value`` is greater than ``max_value``.
138
139``MinValueValidator``
140---------------------
141.. class:: MinValueValidator(min_value)
142
143    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
144    ``'min_value'`` if ``value`` is less than ``min_value``.
145
146``MaxLengthValidator``
147----------------------
148.. class:: MaxLengthValidator(max_length)
149
150    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
151    ``'max_length'`` if the length of ``value`` is greater than ``max_length``.
152
153``MinLengthValidator``
154----------------------
155.. class:: MinLengthValidator(min_length)
156
157    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
158    ``'min_length'`` if the length of ``value`` is less than ``min_length``.