1 ==========

     2 Validators

     3 ==========

     4 

     5 .. versionadded:: 1.2

     6 .. module:: django.core.validators

     7     :synopsis: Validation utilities and base classes

     8 

     9 Writing validators

    10 ==================

    11 

    12 A validator is a callable that takes a value and raises a

    13 :exc:`~django.core.exceptions.ValidationError` if it doesn't meet some

    14 criteria. Validators can be useful for re-using validation logic between

    15 different types of fields.

    16 

    17 For 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 

    25 You can add this to a model field via the field's :attr:`~django.db.models.Field.validators`

    26 argument::

    27 

    28     from django.db import models

    29 

    30     class MyModel(models.Model):

    31         even_field = models.IntegerField(validators=[validate_even])

    32 

    33 Because values are converted to Python before validators are run, you can even

    34 use 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 

    41 How validators are run

    42 ======================

    43 

    44 See the :doc:`form validation </ref/forms/validation>` for more information on

    45 how validators are run in forms, and :ref:`Validating objects

    46 <validating-objects>` for how they're run in models. Note that validators will

    47 not 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

    49 that are included in your form. See the

    50 :doc:`ModelForm documentation </topics/forms/modelforms>` for information on

    51 how model validation interacts with forms.

    52 

    53 Built-in validators

    54 ===================

    55 

    56 The :mod:`django.core.validators` module contains a collection of callable

    57 validators for use with model and form fields. They're used internally but

    58 are available for use with your own fields, too. They can be used in addition

    59 to, 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``.