1
0
mirror of https://github.com/django/django.git synced 2024-12-23 01:25:58 +00:00

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

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5709 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2007-07-15 19:34:21 +00:00
parent 0dbc0ab338
commit 2a500b3551

View File

@ -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.
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 @@ 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
=========================