Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #15591 - Clarified interaction between ModelForm and model vali…

…dation.
  • Loading branch information...
commit d3fd8a151231726adacb99bdbcd573f95ce32262 1 parent 78f6669
@timgraham timgraham authored
Showing with 19 additions and 10 deletions.
  1. +10 −7 docs/ref/models/instances.txt
  2. +9 −3 docs/topics/forms/modelforms.txt
View
17 docs/ref/models/instances.txt
@@ -67,9 +67,9 @@ Validating objects
There are three steps involved in validating a model:
-1. Validate the model fields
-2. Validate the model as a whole
-3. Validate the field uniqueness
+1. Validate the model fields - :meth:`Model.clean_fields()`
+2. Validate the model as a whole - :meth:`Model.clean()`
+3. Validate the field uniqueness - :meth:`Model.validate_unique()`
All three steps are performed when you call a model's
:meth:`~Model.full_clean()` method.
@@ -97,17 +97,20 @@ not be corrected by the user.
Note that ``full_clean()`` will *not* be called automatically when you call
your model's :meth:`~Model.save()` method, nor as a result of
-:class:`~django.forms.ModelForm` validation. You'll need to call it manually
-when you want to run one-step model validation for your own manually created
-models.
+:class:`~django.forms.ModelForm` validation. In the case of
+:class:`~django.forms.ModelForm` validation, :meth:`Model.clean_fields()`,
+:meth:`Model.clean()`, and :meth:`Model.validate_unique()` are all called
+individually.
-Example::
+You'll need to call ``full_clean`` manually when you want to run one-step model
+validation for your own manually created models. For example::
try:
article.full_clean()
except ValidationError as e:
# Do something based on the errors contained in e.message_dict.
# Display them to a user, or handle them programatically.
+ pass
The first step ``full_clean()`` performs is to clean each individual field.
View
12 docs/topics/forms/modelforms.txt
@@ -192,6 +192,8 @@ we'll discuss in a moment.)::
name = forms.CharField(max_length=100)
authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())
+.. _modelform-is-valid-and-errors:
+
The ``is_valid()`` method and ``errors``
----------------------------------------
@@ -213,7 +215,9 @@ method. This method creates and saves a database object from the data
bound to the form. A subclass of ``ModelForm`` can accept an existing
model instance as the keyword argument ``instance``; if this is
supplied, ``save()`` will update that instance. If it's not supplied,
-``save()`` will create a new instance of the specified model::
+``save()`` will create a new instance of the specified model:
+
+.. code-block:: python
# Create a form instance from POST data.
>>> f = ArticleForm(request.POST)
@@ -232,8 +236,10 @@ supplied, ``save()`` will update that instance. If it's not supplied,
>>> f = ArticleForm(request.POST, instance=a)
>>> f.save()
-Note that ``save()`` will raise a ``ValueError`` if the data in the form
-doesn't validate -- i.e., if form.errors evaluates to True.
+Note that if the form :ref:`hasn't been validated
+<modelform-is-valid-and-errors>`, calling ``save()`` will do so by checking
+``form.errors``. A ``ValueError`` will be raised if the data in the form
+doesn't validate -- i.e., if ``form.errors`` evaluates to ``True``.
This ``save()`` method accepts an optional ``commit`` keyword argument, which
accepts either ``True`` or ``False``. If you call ``save()`` with
Please sign in to comment.
Something went wrong with that request. Please try again.