Django

Code

Changeset 5700

Show
Ignore:
Timestamp:
07/14/07 23:41:59 (1 year ago)
Author:
russellm
Message:

Clarified the documentation on the steps that happen during a save, and how raw save affects those steps.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/db-api.txt

    r5698 r5700  
    119119objects, when you're confident you won't have primary-key collision. 
    120120 
    121 Raw saves 
    122 --------- 
     121What happens when you save? 
     122--------------------------- 
     123 
     124When you save an object, Django performs the following steps: 
     125 
     126    1. **Emit a ``pre_save`` signal.** This provides a notification that 
     127       an object is about to be saved. You can register a listener that 
     128       will be invoked whenever this signal is emitted. 
     129 
     130    2. **Pre-process the data.** Each field on the object is asked to 
     131       perform any automated data modification that the field may need 
     132       to perform. 
     133 
     134       Most fields do *no* pre-processing - the field data is kept as-is. 
     135       Pre-processing is only used on fields that have special behavior. 
     136       For example, if your model has a ``DateField`` with ``auto_now=True``, 
     137       the pre-save phase will alter the data in the object to ensure that 
     138       the date field contains the current date stamp. 
     139 
     140    3. **Prepare the data for the database.** Each field is asked to provide 
     141       their current value in a datatype that can be written to the database. 
     142 
     143       Again, most fields require *no* data preparation. Simple data types, 
     144       such as integers and strings, are 'ready to write' as a Python object. 
     145       However, more complex data types often require some modification. For 
     146       example, ``DateFields`` use a Python ``datetime`` object to store data. 
     147       Databases don't store ``datetime`` objects, so the field value 
     148       must be converted into an ISO compliant date string for insertion 
     149       into the database. 
     150 
     151    4. **Insert the data into the database.** The pre-processed, prepared 
     152       data is then composed into an SQL statement for insertion into the 
     153       database. 
     154 
     155    5. **Emit a ``post_save`` signal.** As with the ``pre_save`` signal, this 
     156       is used to provide notification that an object has been successfully 
     157       saved. 
     158 
     159Raw Saves 
     160~~~~~~~~~ 
    123161 
    124162**New in Django development version** 
    125163 
    126 When you save an Django object, some pre-processing might occur on the the 
    127 object's data before it's saved to the database. For example, if your model has 
    128 a ``DateField`` with ``auto_now=True`` set, the pre-save phase will alter the 
    129 data in the object  to ensure that the date field contains the current date 
    130 stamp. 
    131  
    132 Although these automated changes can be useful, sometimes you just want to save 
    133 the data as-is. In these cases, you can invoke a **raw save**  by passing 
     164The pre-processing step performed by Django is extremely useful for 
     165implementing special field behavior (such as the ``auto_now`` feature of 
     166``DateField``), but it does modify the data stored in a field. This can cause 
     167problems if you are relying upon the data you provide being used as-is. For 
     168example, if you are setting up conditions for a test, you will want the test 
     169conditions to be repeatable. If pre-processing is performed, the data used 
     170to specify test conditions may be modified, changing the conditions for the 
     171test each time the test is run. 
     172 
     173In cases such as this, you need to prevent pre-processing from being performed 
     174when you save an object. To do this, you can invoke a **raw save**  by passing 
    134175``raw=True`` as an argument to the ``save()`` method:: 
    135176 
    136     b4.save(raw=True)  # Saves object, but does no pre-processing 
    137  
    138 A raw save saves all the data in your object, but performs no pre-save processing 
    139 on the data in the object. 
     177    b4.save(raw=True) # Save object, but do no pre-processing 
     178 
     179A raw save skips the usual data pre-processing that is performed during the 
     180save. All other steps in the save (pre-save signal, data preparation, data 
     181insertion, and post-save signal) are performed as normal. 
     182 
     183.. admonition:: When to use a raw save 
     184 
     185    Generally speaking, you shouldn't need use use a raw save. Disabling field 
     186    pre-processing is an extraordinary measure that should only be required 
     187    in extraordinary circumstances (such as setting up reliable test 
     188    conditions). 
    140189 
    141190Saving changes to objects 
    …… 
    161210    entry.author = joe 
    162211    entry.save() 
    163      
     212 
    164213Django will complain if you try to assign an object of the wrong type. 
    165214