queryset-refactor: Added an update method to QuerySets, since it's needed for

moving SQL out of the core code. Only direct fields and foreign keys can be
updated in this fashion, since multi-table updates are very non-portable.

This also cleans up the API for the UpdateQuery class a bit. Still need to
change DeleteQuery to work similarly, I suspect.

Refs #4260.


git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@7043 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 60 insertions, 0 deletions

diff --git a/tests/modeltests/update/__init__.py b/tests/modeltests/update/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/tests/modeltests/update/__init__.py
diff --git a/tests/modeltests/update/models.py b/tests/modeltests/update/models.py
new file mode 100644
index 0000000000..55b30cd3f5
--- /dev/null
+++ b/tests/modeltests/update/models.py
@@ -0,0 +1,60 @@
+"""
+Tests for the update() queryset method that allows in-place, multi-object
+updates.
+"""
+
+from django.db import models
+
+class DataPoint(models.Model):
+    name = models.CharField(max_length=20)
+    value = models.CharField(max_length=20)
+    another_value = models.CharField(max_length=20, blank=True)
+
+    def __unicode__(self):
+        return unicode(self.name)
+
+class RelatedPoint(models.Model):
+    name = models.CharField(max_length=20)
+    data = models.ForeignKey(DataPoint)
+
+    def __unicode__(self):
+        return unicode(self.name)
+
+
+__test__ = {'API_TESTS': """
+>>> DataPoint(name="d0", value="apple").save()
+>>> DataPoint(name="d2", value="banana").save()
+>>> d3 = DataPoint(name="d3", value="banana")
+>>> d3.save()
+>>> RelatedPoint(name="r1", data=d3).save()
+
+Objects are updated by first filtering the candidates into a queryset and then
+calling the update() method. It executes immediately and returns nothing.
+
+>>> DataPoint.objects.filter(value="apple").update(name="d1")
+>>> DataPoint.objects.filter(value="apple")
+[<DataPoint: d1>]
+
+We can update multiple objects at once.
+
+>>> DataPoint.objects.filter(value="banana").update(value="pineapple")
+>>> DataPoint.objects.get(name="d2").value
+u'pineapple'
+
+Foreign key fields can also be updated, although you can only update the object
+referred to, not anything inside the related object.
+
+>>> d = DataPoint.objects.get(name="d1")
+>>> RelatedPoint.objects.filter(name="r1").update(data=d)
+>>> RelatedPoint.objects.filter(data__name="d1")
+[<RelatedPoint: r1>]
+
+Multiple fields can be updated at once
+
+>>> DataPoint.objects.filter(value="pineapple").update(value="fruit", another_value="peaches")
+>>> d = DataPoint.objects.get(name="d2")
+>>> d.value, d.another_value
+(u'fruit', u'peaches')
+
+"""
+}