=== added directory 'tests/modeltests/update'
=== added file 'tests/modeltests/update/__init__.py'
=== added file 'tests/modeltests/update/models.py'
--- tests/modeltests/update/models.py	1970-01-01 00:00:00 +0000
+++ tests/modeltests/update/models.py	2006-12-22 04:20:11 +0000
@@ -0,0 +1,69 @@
+"""
+34. update()
+
+update() will update an object's fields with the paramaters passed to it,
+and then save the object.
+"""
+
+from django.db import models
+from django.core import validators
+
+class User(models.Model):
+    username = models.CharField(maxlength=30, unique=True,
+                                validator_list=[validators.isAlphaNumeric])
+    first_name = models.CharField(maxlength=100)
+    last_name = models.CharField(maxlength=100)
+
+    def __str__(self):
+        return '%s %s "%s"' % (self.first_name, self.last_name, self.username)
+
+    class Meta:
+        ordering = ('username',)
+
+__test__ = {'API_TESTS':"""
+# Lets create a User.
+>>> u1 = User.objects.create(username='brave', first_name='Sir', last_name='Robin')
+
+# Only one User in the database so far.
+>>> User.objects.all()
+[<User: Sir Robin "brave">]
+
+# Now we update the user's username and check that it was indeed updated.
+>>> u1.update(username='notsobrave')
+>>> u1.username
+'notsobrave'
+
+# We should still only have one User in the database.
+>>> User.objects.all()
+[<User: Sir Robin "notsobrave">]
+
+# We should be able to grab the User by its new username.
+>>> u1 = User.objects.get(username='notsobrave')
+
+# And we should no longer have a User with username 'brave'.
+>>> User.objects.filter(username='brave').count()
+0L
+
+# Let's create another User.
+>>> u2 = User.objects.create(username='brave', first_name='Sir', last_name='Lancelot')
+
+# Two Users in the database now, and we also have the first User's updated data.
+>>> User.objects.all()
+[<User: Sir Lancelot "brave">, <User: Sir Robin "notsobrave">]
+
+# We can update more than one field at a time.
+>>> u1.update(username='pure', last_name='Galahad')
+
+# The user did indeed get updated.
+>>> User.objects.all()
+[<User: Sir Lancelot "brave">, <User: Sir Galahad "pure">]
+
+# If we have a dictionary of fields to change, we can pass that to
+# update() also.
+>>> data = {'username': 'knight', 'first_name': 'Knight'}
+>>> u1.update(**data)
+>>> u1
+<User: Knight Galahad "knight">
+>>> User.objects.all()
+[<User: Sir Lancelot "brave">, <User: Knight Galahad "knight">]
+"""}

=== modified file 'django/db/models/base.py'
--- django/db/models/base.py	2006-12-19 04:35:09 +0000
+++ django/db/models/base.py	2006-12-22 02:22:48 +0000
@@ -217,6 +217,19 @@
 
     save.alters_data = True
 
+    def update(self, **kwargs):
+        """
+        Set the object's fields to the new values passed in as keyword
+        arguments and then save the object.  Fields not specified in the
+        keyword arguments will not be altered.
+        """
+        # Nothing to do if we have no keyword arguments.
+        if kwargs:
+            self.__dict__.update(kwargs)
+            self.save()
+
+    update.alters_data = True
+
     def validate(self):
         """
         First coerces all fields on this instance to their proper Python types.

=== modified file 'docs/db-api.txt'
--- docs/db-api.txt	2006-12-19 04:35:09 +0000
+++ docs/db-api.txt	2006-12-22 02:17:11 +0000
@@ -1614,6 +1614,24 @@
 
     Entry.objects.all().delete()
 
+Updating objects
+================
+
+The ``create(**kwargs)`` method is a convenience method for updating and
+saving an object all in one step.  If we were to get an object::
+
+    p = Person.objects.get(pk=1)
+
+Then, we could update the person's first and last name like so::
+
+    p.update(first_name="Bruce", last_name="Springsteen")
+
+Note that this would be equivalent to the following::
+
+    p.first_name = "Bruce"
+    p.last_name = "Springsteen"
+    p.save()
+
 Extra instance methods
 ======================