Author: russellm
Date: 2010-01-07 18:17:33 -0600 (Thu, 07 Jan 2010)
New Revision: 12118
Modified:
django/trunk/docs/ref/models/instances.txt
django/trunk/docs/topics/db/models.txt
Log:
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.
Modified: django/trunk/docs/ref/models/instances.txt
===================================================================
--- django/trunk/docs/ref/models/instances.txt 2010-01-07 11:38:14 UTC (rev
12117)
+++ django/trunk/docs/ref/models/instances.txt 2010-01-08 00:17:33 UTC (rev
12118)
@@ -66,16 +66,21 @@
To save an object back to the database, call ``save()``:
-.. method:: Model.save([force_insert=False, force_update=False])
+.. method:: Model.save([force_insert=False, force_update=False,
using=DEFAULT_DB_ALIAS])
-Of course, there are some subtleties; see the sections below.
-
.. 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,15 +270,22 @@
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:
Other model instance methods
Modified: django/trunk/docs/topics/db/models.txt
===================================================================
--- django/trunk/docs/topics/db/models.txt 2010-01-07 11:38:14 UTC (rev
12117)
+++ django/trunk/docs/topics/db/models.txt 2010-01-08 00:17:33 UTC (rev
12118)
@@ -707,6 +707,8 @@
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 @@
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,17 +739,25 @@
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
--------------------
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
