Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.5.X] Fixed #15591 - Clarified interaction between ModelForm and mo…

…del validation.

Backport of d3fd8a1 from master
  • Loading branch information...
commit f7d87b30fb3636f0964880a6dd8a066db54ce3c1 1 parent a23c9c4
Tim Graham authored November 05, 2012
17  docs/ref/models/instances.txt
@@ -67,9 +67,9 @@ Validating objects
67 67
 
68 68
 There are three steps involved in validating a model:
69 69
 
70  
-1. Validate the model fields
71  
-2. Validate the model as a whole
72  
-3. Validate the field uniqueness
  70
+1. Validate the model fields - :meth:`Model.clean_fields()`
  71
+2. Validate the model as a whole - :meth:`Model.clean()`
  72
+3. Validate the field uniqueness - :meth:`Model.validate_unique()`
73 73
 
74 74
 All three steps are performed when you call a model's
75 75
 :meth:`~Model.full_clean()` method.
@@ -97,17 +97,20 @@ not be corrected by the user.
97 97
 
98 98
 Note that ``full_clean()`` will *not* be called automatically when you call
99 99
 your model's :meth:`~Model.save()` method, nor as a result of
100  
-:class:`~django.forms.ModelForm` validation. You'll need to call it manually
101  
-when you want to run one-step model validation for your own manually created
102  
-models.
  100
+:class:`~django.forms.ModelForm` validation. In the case of
  101
+:class:`~django.forms.ModelForm` validation, :meth:`Model.clean_fields()`,
  102
+:meth:`Model.clean()`, and :meth:`Model.validate_unique()` are all called
  103
+individually.
103 104
 
104  
-Example::
  105
+You'll need to call ``full_clean`` manually when you want to run one-step model
  106
+validation for your own manually created models. For example::
105 107
 
106 108
     try:
107 109
         article.full_clean()
108 110
     except ValidationError as e:
109 111
         # Do something based on the errors contained in e.message_dict.
110 112
         # Display them to a user, or handle them programatically.
  113
+        pass
111 114
 
112 115
 The first step ``full_clean()`` performs is to clean each individual field.
113 116
 
12  docs/topics/forms/modelforms.txt
@@ -192,6 +192,8 @@ we'll discuss in a moment.)::
192 192
         name = forms.CharField(max_length=100)
193 193
         authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())
194 194
 
  195
+.. _modelform-is-valid-and-errors:
  196
+
195 197
 The ``is_valid()`` method and ``errors``
196 198
 ----------------------------------------
197 199
 
@@ -213,7 +215,9 @@ method. This method creates and saves a database object from the data
213 215
 bound to the form. A subclass of ``ModelForm`` can accept an existing
214 216
 model instance as the keyword argument ``instance``; if this is
215 217
 supplied, ``save()`` will update that instance. If it's not supplied,
216  
-``save()`` will create a new instance of the specified model::
  218
+``save()`` will create a new instance of the specified model:
  219
+
  220
+.. code-block:: python
217 221
 
218 222
     # Create a form instance from POST data.
219 223
     >>> f = ArticleForm(request.POST)
@@ -232,8 +236,10 @@ supplied, ``save()`` will update that instance. If it's not supplied,
232 236
     >>> f = ArticleForm(request.POST, instance=a)
233 237
     >>> f.save()
234 238
 
235  
-Note that ``save()`` will raise a ``ValueError`` if the data in the form
236  
-doesn't validate -- i.e., if form.errors evaluates to True.
  239
+Note that if the form :ref:`hasn't been validated
  240
+<modelform-is-valid-and-errors>`, calling ``save()`` will do so by checking
  241
+``form.errors``. A ``ValueError`` will be raised if the data in the form
  242
+doesn't validate -- i.e., if ``form.errors`` evaluates to ``True``.
237 243
 
238 244
 This ``save()`` method accepts an optional ``commit`` keyword argument, which
239 245
 accepts either ``True`` or ``False``. If you call ``save()`` with

0 notes on commit f7d87b3

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