Permalink
Browse files

Fixed #8679: use full signature of Model.save() in docs and remove no…

…-longer-used 'raw' argument

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8754 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 5e26fce commit 6ba55eee30de948f46f39afda2638f7504d63dd9 @ubernostrum ubernostrum committed Aug 31, 2008
Showing with 9 additions and 40 deletions.
  1. +2 −2 docs/ref/contrib/sitemaps.txt
  2. +1 −33 docs/ref/models/instances.txt
  3. +6 −5 docs/topics/db/models.txt
@@ -325,8 +325,8 @@ method::
class Entry(models.Model):
# ...
- def save(self):
- super(Entry, self).save()
+ def save(self, force_insert=False, force_update=False):
+ super(Entry, self).save(force_insert, force_update)
try:
ping_google()
except Exception:
@@ -33,7 +33,7 @@ To save an object back to the database, call ``save()``:
.. method:: Model.save([force_insert=False, force_update=False])
-Of course, there's some subtleties; see the sections below.
+Of course, there are some subtleties; see the sections below.
**New in Django development version:** The signature of the ``save()`` method
has changed from earlier versions (``force_insert`` and ``force_update`` have
@@ -144,38 +144,6 @@ When you save an object, Django performs the following steps:
is used to provide notification that an object has been successfully
saved. (These signals are not yet documented.)
-Raw saves
-~~~~~~~~~
-
-**New in Django development version**
-
-The pre-processing step (#2 in the previous section) is useful, but it modifies
-the data stored in a field. This can cause problems if you're relying upon the
-data you provide being used as-is.
-
-For example, if you're setting up conditions for a test, you'll want the test
-conditions to be repeatable. If pre-processing is performed, the data used
-to specify test conditions may be modified, changing the conditions for the
-test each time the test is run.
-
-In cases such as this, you need to prevent pre-processing from being performed
-when you save an object. To do this, you can invoke a **raw save** by passing
-``raw=True`` as an argument to the ``save()`` method::
-
- b4.save(raw=True) # Save object, but do no pre-processing
-
-A raw save skips the usual data pre-processing that is performed during the
-save. All other steps in the save (pre-save signal, data preparation, data
-insertion, and post-save signal) are performed as normal.
-
-.. admonition:: When to use a raw save
-
- Generally speaking, you shouldn't need to use a raw save. Disabling field
- pre-processing is an extraordinary measure that should only be required
- in extraordinary circumstances, such as setting up reliable test
- conditions.
-
-
How Django knows to UPDATE vs. INSERT
-------------------------------------
View
@@ -683,15 +683,16 @@ You're free to override these methods (and any other model method) to alter
behavior.
A classic use-case for overriding the built-in methods is if you want something
-to happen whenever you save an object. For example::
+to happen whenever you save an object. For example (see
+:meth:`~Model.save` for documentation of the parameters it accepts)::
class Blog(models.Model):
name = models.CharField(max_length=100)
tagline = models.TextField()
- def save(self):
+ def save(self, force_insert=False, force_update=False):
do_something()
- super(Blog, self).save() # Call the "real" save() method.
+ super(Blog, self).save(force_inset, force_update) # Call the "real" save() method.
do_something_else()
You can also prevent saving::
@@ -700,11 +701,11 @@ You can also prevent saving::
name = models.CharField(max_length=100)
tagline = models.TextField()
- def save(self):
+ def save(self, force_insert=False, force_update=False):
if self.name == "Yoko Ono's blog":
return # Yoko shall never have her own blog!
else:
- super(Blog, self).save() # Call the "real" save() method.
+ super(Blog, self).save(force_inset, force_update) # 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

0 comments on commit 6ba55ee

Please sign in to comment.