Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5709 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 2a500b3551a5ab565592f575d27d946c837d2d6b 1 parent 0dbc0ab
@adrianholovaty adrianholovaty authored
Showing with 24 additions and 20 deletions.
  1. +24 −20 docs/db-api.txt
View
44 docs/db-api.txt
@@ -125,27 +125,31 @@ 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.
+ 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.
-
- 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
+ its current value in a data type that can be written to the database.
+
+ 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 @@ When you save an object, Django performs the following steps:
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 @@ 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
+ 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
=========================
Please sign in to comment.
Something went wrong with that request. Please try again.