Django

Code

Changeset 5709

Show
Ignore:
Timestamp:
07/15/07 14:34:21 (1 year ago)
Author:
adrian
Message:

Edited docs/db-api.txt changes from [5700]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r5700 r5709  
    126126    1. **Emit a ``pre_save`` signal.** This provides a notification that 
    127127       an object is about to be saved. You can register a listener that 
    128        will be invoked whenever this signal is emitted. 
     128       will be invoked whenever this signal is emitted. (These signals are 
     129       not yet documented.) 
    129130 
    130131    2. **Pre-process the data.** Each field on the object is asked to 
    …… 
    132133       to perform. 
    133134 
    134        Most fields do *no* pre-processing - the field data is kept as-is. 
     135       Most fields do *no* pre-processing -- the field data is kept as-is. 
    135136       Pre-processing is only used on fields that have special behavior. 
    136137       For example, if your model has a ``DateField`` with ``auto_now=True``, 
    137138       the pre-save phase will alter the data in the object to ensure that 
    138        the date field contains the current date stamp. 
     139       the date field contains the current date stamp. (Our documentation 
     140       doesn't yet include a list of all the fields with this "special 
     141       behavior.") 
    139142 
    140143    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 
     144       its current value in a data type that can be written to the database. 
     145 
     146       Most fields require *no* data preparation. Simple data types, such as 
     147       integers and strings, are 'ready to write' as a Python object. However, 
     148       more complex data types often require some modification. 
     149 
     150       For example, ``DateFields`` use a Python ``datetime`` object to store 
     151       data. Databases don't store ``datetime`` objects, so the field value 
     152       must be converted into an ISO-compliant date string for insertion 
    149153       into the database. 
    150154 
    …… 
    155159    5. **Emit a ``post_save`` signal.** As with the ``pre_save`` signal, this 
    156160       is used to provide notification that an object has been successfully 
    157        saved. 
     161       saved. (These signals are not yet documented.) 
    158162 
    159163Raw Saves 
    …… 
    162166**New in Django development version** 
    163167 
    164 The pre-processing step performed by Django is extremely useful for 
    165 implementing 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 
    167 problems if you are relying upon the data you provide being used as-is. For 
    168 example, if you are setting up conditions for a test, you will want the test 
     168The pre-processing step (#2 in the previous section) is useful, but it modifies 
     169the data stored in a field. This can cause problems if you're relying upon the 
     170data you provide being used as-is. 
     171 
     172For example, if you're setting up conditions for a test, you'll want the test 
    169173conditions to be repeatable. If pre-processing is performed, the data used 
    170174to specify test conditions may be modified, changing the conditions for the 
    …… 
    183187.. admonition:: When to use a raw save 
    184188 
    185     Generally speaking, you shouldn't need use use a raw save. Disabling field 
     189    Generally speaking, you shouldn't need to use a raw save. Disabling field 
    186190    pre-processing is an extraordinary measure that should only be required 
    187     in extraordinary circumstances (such as setting up reliable test 
    188     conditions). 
     191    in extraordinary circumstances, such as setting up reliable test 
     192    conditions. 
    189193 
    190194Saving changes to objects