Author: adrian
Date: 2007-07-15 14:34:21 -0500 (Sun, 15 Jul 2007)
New Revision: 5709
Modified:
django/trunk/docs/db-api.txt
Log:
Edited docs/db-api.txt changes from [5700]
Modified: django/trunk/docs/db-api.txt
===================================================================
--- django/trunk/docs/db-api.txt 2007-07-15 10:10:44 UTC (rev 5708)
+++ django/trunk/docs/db-api.txt 2007-07-15 19:34:21 UTC (rev 5709)
@@ -125,27 +125,31 @@
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.
+ will be invoked whenever this signal is emitted. (These signals are
+ not yet documented.)
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.
+ 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.
+ the date field contains the current date stamp. (Our documentation
+ doesn't yet include a list of all the fields with this "special
+ behavior.")
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.
+ its current value in a data type 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
+ 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
@@ -154,18 +158,18 @@
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.
+ saved. (These signals are not yet documented.)
Raw Saves
~~~~~~~~~
**New in Django development version**
-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
+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.
@@ -182,10 +186,10 @@
.. admonition:: When to use a raw save
- Generally speaking, you shouldn't need use use a raw save. Disabling field
+ 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).
+ in extraordinary circumstances, such as setting up reliable test
+ conditions.
Saving changes to objects
=========================
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
