diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 9d7636ad6a..f8328f2f27 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.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: diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index e96a775e5f..1085e7b6df 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -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 ------------------------------------- diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index e22660a08b..ad15d4119c 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -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