From 96848352f97e8c2deb976ce4c8418c0d0aa6be5e Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Fri, 8 Jan 2010 00:17:33 +0000
Subject: [PATCH] Added `using` to the list of documented arguments for save()
 on a model; updated the docs to suggest using ``*args, **kwargs`` when
 implementing model save methods. Thanks to Jeff Croft for the report.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12118 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/ref/models/instances.txt | 36 +++++++++++++++++++++++------------
 docs/topics/db/models.txt     | 26 +++++++++++++++++--------
 2 files changed, 42 insertions(+), 20 deletions(-)

diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 5999038979..f2eb54c217 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -66,15 +66,20 @@ Saving objects
 
 To save an object back to the database, call ``save()``:
 
-.. method:: Model.save([force_insert=False, force_update=False])
-
-Of course, there are some subtleties; see the sections below.
+.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS])
 
 .. versionadded:: 1.0
+   The ``force_insert`` and ``force_update`` arguments were added.
 
-The signature of the ``save()`` method has changed from earlier versions
-(``force_insert`` and ``force_update`` have been added). If you are overriding
-these methods, be sure to use the correct signature.
+.. versionadded:: 1.1
+   The ``using`` argument was added.
+
+If you want customized saving behavior, you can override this
+``save()`` method. See :ref:`overriding-model-methods` for more
+details.
+
+The model save process also has some subtleties; see the sections
+below.
 
 Auto-incrementing primary keys
 ------------------------------
@@ -265,14 +270,21 @@ For more details, see the documentation on :ref:`F() expressions
 Deleting objects
 ================
 
-.. method:: Model.delete()
+.. method:: Model.delete([using=DEFAULT_DB_ALIAS])
 
-   Issues a SQL ``DELETE`` for the object. This only deletes the object in the
-   database; the Python instance will still be around, and will still have data
-   in its fields.
+.. versionadded:: 1.1
+   The ``using`` argument was added.
 
-   For more details, including how to delete objects in bulk, see
-   :ref:`topics-db-queries-delete`.
+Issues a SQL ``DELETE`` for the object. This only deletes the object
+in the database; the Python instance will still be around, and will
+still have data in its fields.
+
+For more details, including how to delete objects in bulk, see
+:ref:`topics-db-queries-delete`.
+
+If you want customized deletion behavior, you can override this
+``delete()`` method. See :ref:`overriding-model-methods` for more
+details.
 
 .. _model-instance-methods:
 
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index a28e7e8805..1e69009827 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -707,6 +707,8 @@ below -- but there are a couple that you'll almost always want to define:
         Any object that has a URL that uniquely identifies it should define this
         method.
 
+.. _overriding-model-methods:
+
 Overriding predefined model methods
 -----------------------------------
 
@@ -726,9 +728,9 @@ to happen whenever you save an object. For example (see
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
-        def save(self, force_insert=False, force_update=False):
+        def save(self, *args, **kwargs):
             do_something()
-            super(Blog, self).save(force_insert, force_update) # Call the "real" save() method.
+            super(Blog, self).save(*args, **kwargs) # Call the "real" save() method.
             do_something_else()
 
 You can also prevent saving::
@@ -737,16 +739,24 @@ You can also prevent saving::
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
-        def save(self, force_insert=False, force_update=False):
+        def save(self, *args, **kwargs):
             if self.name == "Yoko Ono's blog":
                 return # Yoko shall never have her own blog!
             else:
-                super(Blog, self).save(force_insert, force_update) # Call the "real" save() method.
+                super(Blog, self).save(*args, **kwargs) # Call the "real" save() method.
 
-It's important to remember to call the superclass method -- that's that
-``super(Blog, self).save()`` business -- to ensure that the object still gets
-saved into the database. If you forget to call the superclass method, the
-default behavior won't happen and the database won't get touched.
+It's important to remember to call the superclass method -- that's
+that ``super(Blog, self).save(*args, **kwargs)`` business -- to ensure
+that the object still gets saved into the database. If you forget to
+call the superclass method, the default behavior won't happen and the
+database won't get touched.
+
+It's also important that you pass through the arguments that can be
+passed to the model method -- that's what the ``*args, **kwargs`` bit
+does. Django will, from time to time, extend the capabilities of
+built-in model methods, adding new arguments. If you use ``*args,
+**kwargs`` in your method definitions, you are guaranteed that your
+code will automatically support those arguments when they are added.
 
 Executing custom SQL
 --------------------