Fixed #15591 - Clarified interaction between ModelForm and model validation.

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.

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.

        name = forms.CharField(max_length=100)

        authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())

.. _modelform-is-valid-and-errors:

The ``is_valid()`` method and ``errors``

----------------------------------------

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)

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