Fixed #4102 -- Allow update of specific fields in model.save()

Added the ability to update only part of the model's fields in
model.save() by introducing a new kwarg "update_fields". Thanks
to all the numerous reviewers and commenters in the ticket

3 files changed, 46 insertions, 1 deletions

diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 3c84be50a6..fb0fcc046d 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -135,7 +135,7 @@ Saving objects
 
 To save an object back to the database, call ``save()``:
 
-.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS])
+.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None])
 
 .. versionadded:: 1.2
    The ``using`` argument was added.
@@ -289,6 +289,8 @@ almost always do the right thing and trying to override that will lead to
 errors that are difficult to track down. This feature is for advanced use
 only.
 
+Using ``update_fields`` will force an update similarly to ``force_update``.
+
 Updating attributes based on existing fields
 --------------------------------------------
 
@@ -334,6 +336,26 @@ For more details, see the documentation on :ref:`F() expressions
 <query-expressions>` and their :ref:`use in update queries
 <topics-db-queries-update>`.
 
+Specifying which fields to save
+-------------------------------
+
+.. versionadded:: 1.5
+
+If ``save()`` is passed a list of field names in keyword argument
+``update_fields``, only the fields named in that list will be updated.
+This may be desirable if you want to update just one or a few fields on
+an object. There will be a slight performance benefit from preventing
+all of the model fields from being updated in the database. For example:
+
+    product.name = 'Name changed again'
+    product.save(update_fields=['name'])
+
+The ``update_fields`` argument can be any iterable containing strings. An
+empty ``update_fields`` iterable will skip the save. A value of None will
+perform an update on all fields.
+
+Specifying ``update_fields`` will force an update.
+
 Deleting objects
 ================
 
diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
index 3917b52b96..136eee935c 100644
--- a/docs/ref/signals.txt
+++ b/docs/ref/signals.txt
@@ -123,6 +123,12 @@ Arguments sent with this signal:
 ``using``
     The database alias being used.
 
+.. versionadded:: 1.5
+
+``update_fields``
+    The set of fields to update explicitly specified in the ``save()`` method.
+    ``None`` if this argument was not used in the ``save()`` call.
+
 post_save
 ---------
 
@@ -154,6 +160,12 @@ Arguments sent with this signal:
 ``using``
     The database alias being used.
 
+.. versionadded:: 1.5
+
+``update_fields``
+    The set of fields to update explicitly specified in the ``save()`` method.
+    ``None`` if this argument was not used in the ``save()`` call.
+
 pre_delete
 ----------
 
diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt
index 677aac7f2b..be06fe58d8 100644
--- a/docs/releases/1.5.txt
+++ b/docs/releases/1.5.txt
@@ -33,6 +33,17 @@ version compatible with Python 2.6.
 What's new in Django 1.5
 ========================
 
+Support for saving a subset of model's fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The method :meth:`Model.save() <django.db.models.Model.save()>` has a new
+keyword argument ``update_fields``. By using this argument it is possible to
+save only a select list of model's fields. This can be useful for performance
+reasons or when trying to avoid overwriting concurrent changes.
+
+See the :meth:`Model.save() <django.db.models.Model.save()>` documentation for
+more details.
+
 Minor features
 ~~~~~~~~~~~~~~