Ticket #4102: 4102-only-udpate-fields.patch

tests/modeltests/update_fields/models.py

@@ +1 @@
+"""
+#. Save only specific fields on update
+
+If a list of field names is given to the save() method,
+update only those in the database.
+"""
+from django.db import models
+
+class Article(models.Model):
+    headline = models.CharField(maxlength=100, default='Default headline')
+    body = models.TextField()
+    pub_date = models.DateTimeField()
+
+    class Meta:
+        ordering = ('pub_date','headline')
+
+    def __str__(self):
+        return self.headline
+
+__test__ = {'API_TESTS':"""
+# Create a couple of Articles.
+>>> from datetime import datetime
+>>> a = Article(headline='Article 1', body='Body 1', pub_date=datetime(2007, 5, 5))
+>>> a.save()
+
+# Change headline and body but only save the headline
+>>> a.headline, a.body = 'Changed headline 1', 'Changed body 1'
+>>> a.save(['headline'])
+>>> a.headline
+'Changed headline 1'
+>>> a.body
+'Changed body 1'
+>>> a1 = Article.objects.get(pk=a.id)
+>>> a1.headline
+'Changed headline 1'
+>>> a1.body
+'Body 1'
+
+# Use the keyword argument form
+>>> a.headline, a.body = 'Changed headline 2nd time', 'Changed body 2nd time'
+>>> a.save(only_fields=['headline'])
+>>> a.headline
+'Changed headline 2nd time'
+>>> a.body
+'Changed body 2nd time'
+>>> a2 = Article.objects.get(pk=a.id)
+>>> a2.headline
+'Changed headline 2nd time'
+>>> a2.body
+'Body 1'
+"""}

django/db/models/base.py

@@ -98 +98 @@
         dispatcher.send(signal=signals.pre_init, sender=self.__class__, args=args, kwargs=kwargs)
         
         # There is a rather weird disparity here; if kwargs, it's set, then args
-        # overrides it. It should be one or the other; don't duplicate the work 
+        # overrides it. It should be one or the other; don't duplicate the work.
         # The reason for the kwargs check is that standard iterator passes in by
-        # args, and nstantiation for iteration is 33% faster.
+        # args, and instantiation for iteration is 33% faster.
         args_len = len(args)
         if args_len > len(self._meta.fields):
             # Daft, but matches old exception sans the err msg.
@@ -198 +198 @@
 
     _prepare = classmethod(_prepare)
 
-    def save(self):
+    def save(self, only_fields=None):
+        "Save model object to database, creating if doesn't exist, otherwise updating"
         dispatcher.send(signal=signals.pre_save, sender=self.__class__, instance=self)
 
         non_pks = [f for f in self._meta.fields if not f.primary_key]
+        if only_fields:
+            non_pks = [f for f in non_pks if f.name in only_fields]
+
         cursor = connection.cursor()
 
         # First, try an UPDATE. If that doesn't update anything, do an INSERT.

docs/db-api.txt

@@ -134 +134 @@
 
 The ``save()`` method has no return value.
 
+Specifying which fields to save
+-------------------------------
+
+If ``save()`` is passed a list of field names as its argument, only the fields
+named in that list will be saved to the database. This may be desirable if you
+want to update just one or a few fields on an object, as there will be a slight
+performance benefit from preventing all of the model fields from being updated
+in the database. For example:
+
+    b5.name = 'Changed name'
+    b5.save(['name'])   # Only 'name' is updated, no other fields in SQL
+
+Alternately, you can use the keyword argument ``only_fields`` to specify the
+list of field names:
+
+    b5.name = 'Name changed again'
+    b5.save(only_fields=['name'])
+
 How Django knows to UPDATE vs. INSERT
 -------------------------------------