From eff675b91eac5cf1fbfc730184bb582ce8175693 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sun, 15 Jul 2007 04:41:59 +0000 Subject: [PATCH] Clarified the documentation on the steps that happen during a save, and how raw save affects those steps. git-svn-id: http://code.djangoproject.com/svn/django/trunk@5700 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/db-api.txt | 75 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 13 deletions(-) diff --git a/docs/db-api.txt b/docs/db-api.txt index a3b62e87aa4..214620ee1dd 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -118,25 +118,74 @@ happens. Explicitly specifying auto-primary-key values is mostly useful for bulk-saving objects, when you're confident you won't have primary-key collision. -Raw saves ---------- +What happens when you save? +--------------------------- + +When you save an object, Django performs the following steps: + + 1. **Emit a ``pre_save`` signal.** This provides a notification that + an object is about to be saved. You can register a listener that + will be invoked whenever this signal is emitted. + + 2. **Pre-process the data.** Each field on the object is asked to + perform any automated data modification that the field may need + to perform. + + Most fields do *no* pre-processing - the field data is kept as-is. + Pre-processing is only used on fields that have special behavior. + For example, if your model has a ``DateField`` with ``auto_now=True``, + the pre-save phase will alter the data in the object to ensure that + the date field contains the current date stamp. + + 3. **Prepare the data for the database.** Each field is asked to provide + their current value in a datatype that can be written to the database. + + Again, most fields require *no* data preparation. Simple data types, + such as integers and strings, are 'ready to write' as a Python object. + However, more complex data types often require some modification. For + example, ``DateFields`` use a Python ``datetime`` object to store data. + Databases don't store ``datetime`` objects, so the field value + must be converted into an ISO compliant date string for insertion + into the database. + + 4. **Insert the data into the database.** The pre-processed, prepared + data is then composed into an SQL statement for insertion into the + database. + + 5. **Emit a ``post_save`` signal.** As with the ``pre_save`` signal, this + is used to provide notification that an object has been successfully + saved. + +Raw Saves +~~~~~~~~~ **New in Django development version** -When you save an Django object, some pre-processing might occur on the the -object's data before it's saved to the database. For example, if your model has -a ``DateField`` with ``auto_now=True`` set, the pre-save phase will alter the -data in the object to ensure that the date field contains the current date -stamp. +The pre-processing step performed by Django is extremely useful for +implementing special field behavior (such as the ``auto_now`` feature of +``DateField``), but it does modify the data stored in a field. This can cause +problems if you are relying upon the data you provide being used as-is. For +example, if you are setting up conditions for a test, you will 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. -Although these automated changes can be useful, sometimes you just want to save -the data as-is. In these cases, you can invoke a **raw save** by passing +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) # Saves object, but does no pre-processing + b4.save(raw=True) # Save object, but do no pre-processing -A raw save saves all the data in your object, but performs no pre-save processing -on the data in the object. +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 use 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). Saving changes to objects ========================= @@ -160,7 +209,7 @@ object of the right type to the field in question:: joe = Author.objects.create(name="Joe") entry.author = joe entry.save() - + Django will complain if you try to assign an object of the wrong type. How Django knows to UPDATE vs. INSERT