Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #14537 -- Added documentation on where validators can be import…

…ed from to Validators Reference docs, and improved Sphinx formatting and metadata. Thanks to rfugger for the report.

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

0 notes on commit d371142

Please sign in to comment.
Something went wrong with that request. Please try again.