/docs/ref/validators.txt
Plain Text | 158 lines | 113 code | 45 blank | 0 comment | 0 complexity | c180e9ba11922ba2f997bb5342833d0c MD5 | raw file
Possible License(s): BSD-3-Clause
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``.