test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Documentation edits for model instance docs. 

First of two parts. Mostly adding cross references to other parts of the
documentation.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16701 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Malcolm Tredinnick 2011-08-28 02:05:20 +00:00
parent f85b96121a
commit a0eb58e90b
1 changed files with 132 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

256
docs/ref/models/instances.txt
View File

@ -23,7 +23,7 @@ class:
The keyword arguments are simply the names of the fields you've defined on your The keyword arguments are simply the names of the fields you've defined on your
model. Note that instantiating a model in no way touches your database; for model. Note that instantiating a model in no way touches your database; for
that, you need to ``save()``. that, you need to :meth:`~Model.save()`.
.. _validating-objects: .. _validating-objects:
@ -39,31 +39,34 @@ There are three steps involved in validating a model:
3. Validate the field uniqueness 3. Validate the field uniqueness
All three steps are performed when you call a model's All three steps are performed when you call a model's
``full_clean()`` method. :meth:`~Model.full_clean()` method.
When you use a ``ModelForm``, the call to ``is_valid()`` will perform When you use a :class:`~django.forms.ModelForm`, the call to
these validation steps for all the fields that are included on the :meth:`~django.forms.Form.is_valid()` will perform these validation steps for
form. (See the :doc:`ModelForm documentation all the fields that are included on the form. See the :doc:`ModelForm
</topics/forms/modelforms>` for more information.) You should only need documentation </topics/forms/modelforms>` for more information. You should only
to call a model's ``full_clean()`` method if you plan to handle need to call a model's :meth:`~Model.full_clean()` method if you plan to handle
validation errors yourself, or if you have excluded fields from the validation errors yourself, or if you have excluded fields from the
ModelForm that require validation. :class:`~django.forms.ModelForm` that require validation.
.. method:: Model.full_clean(exclude=None) .. method:: Model.full_clean(exclude=None)
This method calls ``Model.clean_fields()``, ``Model.clean()``, and This method calls :meth:`Model.clean_fields()`, :meth:`Model.clean()`, and
``Model.validate_unique()``, in that order and raises a ``ValidationError`` :meth:`Model.validate_unique()`, in that order and raises a
that has a ``message_dict`` attribute containing errors from all three stages. :exc:`~django.core.exceptions.ValidationError` that has a ``message_dict``
attribute containing errors from all three stages.
The optional ``exclude`` argument can be used to provide a list of field names The optional ``exclude`` argument can be used to provide a list of field names
that can be excluded from validation and cleaning. ``ModelForm`` uses this that can be excluded from validation and cleaning.
argument to exclude fields that aren't present on your form from being :class:`~django.forms.ModelForm` uses this argument to exclude fields that
validated since any errors raised could not be corrected by the user. aren't present on your form from being validated since any errors raised could
not be corrected by the user.
Note that ``full_clean()`` will *not* be called automatically when you Note that ``full_clean()`` will *not* be called automatically when you call
call your model's ``save()`` method, nor as a result of ``ModelForm`` your model's :meth:`~Model.save()` method, nor as a result of
validation. You'll need to call it manually when you want to run model :class:`~django.forms.ModelForm` validation. You'll need to call it manually
validation outside of a ``ModelForm``. when you want to run one-step model validation for your own manually created
models.
Example:: Example::
@ -79,9 +82,10 @@ The first step ``full_clean()`` performs is to clean each individual field.
This method will validate all fields on your model. The optional ``exclude`` This method will validate all fields on your model. The optional ``exclude``
argument lets you provide a list of field names to exclude from validation. It argument lets you provide a list of field names to exclude from validation. It
will raise a ``ValidationError`` if any fields fail validation. will raise a :exc:`~django.core.exceptions.ValidationError` if any fields fail
validation.
The second step ``full_clean()`` performs is to call ``Model.clean()``. The second step ``full_clean()`` performs is to call :meth:`Model.clean()`.
This method should be overridden to perform custom validation on your model. This method should be overridden to perform custom validation on your model.
.. method:: Model.clean() .. method:: Model.clean()
@ -100,10 +104,10 @@ access to more than a single field::
if self.status == 'published' and self.pub_date is None: if self.status == 'published' and self.pub_date is None:
self.pub_date = datetime.datetime.now() self.pub_date = datetime.datetime.now()
Any ``ValidationError`` raised by ``Model.clean()`` will be stored under a Any :exc:`~django.core.exceptions.ValidationError` exceptions raised by
special key that is used for errors that are tied to the entire model instead ``Model.clean()`` will be stored in a special key error dictionary key,
of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``:: ``NON_FIELD_ERRORS``, that is used for errors that are tied to the entire model
instead of to a specific field::
from django.core.exceptions import ValidationError, NON_FIELD_ERRORS from django.core.exceptions import ValidationError, NON_FIELD_ERRORS
try: try:
@ -115,15 +119,15 @@ Finally, ``full_clean()`` will check any unique constraints on your model.
.. method:: Model.validate_unique(exclude=None) .. method:: Model.validate_unique(exclude=None)
This method is similar to ``clean_fields``, but validates all uniqueness This method is similar to :meth:`~Model.clean_fields`, but validates all
constraints on your model instead of individual field values. The optional uniqueness constraints on your model instead of individual field values. The
``exclude`` argument allows you to provide a list of field names to exclude optional ``exclude`` argument allows you to provide a list of field names to
from validation. It will raise a ``ValidationError`` if any fields fail exclude from validation. It will raise a
validation. :exc:`~django.core.exceptions.ValidationError` if any fields fail validation.
Note that if you provide an ``exclude`` argument to ``validate_unique``, any Note that if you provide an ``exclude`` argument to ``validate_unique()``, any
``unique_together`` constraint that contains one of the fields you provided :attr:`~django.db.models.Options.unique_together` constraint involving one of
will not be checked. the fields you provided will not be checked.
Saving objects Saving objects
@ -136,19 +140,17 @@ To save an object back to the database, call ``save()``:
.. versionadded:: 1.2 .. versionadded:: 1.2
The ``using`` argument was added. The ``using`` argument was added.
If you want customized saving behavior, you can override this If you want customized saving behavior, you can override this ``save()``
``save()`` method. See :ref:`overriding-model-methods` for more method. See :ref:`overriding-model-methods` for more details.
details.
The model save process also has some subtleties; see the sections The model save process also has some subtleties; see the sections below.
below.
Auto-incrementing primary keys Auto-incrementing primary keys
------------------------------ ------------------------------
If a model has an ``AutoField`` -- an auto-incrementing primary key -- then If a model has an :class:`~django.db.models.AutoField` — an auto-incrementing
that auto-incremented value will be calculated and saved as an attribute on primary key — then that auto-incremented value will be calculated and saved as
your object the first time you call ``save()``:: an attribute on your object the first time you call ``save()``::
>>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') >>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b2.id # Returns None, because b doesn't have an ID yet. >>> b2.id # Returns None, because b doesn't have an ID yet.
@ -158,9 +160,10 @@ your object the first time you call ``save()``::
There's no way to tell what the value of an ID will be before you call There's no way to tell what the value of an ID will be before you call
``save()``, because that value is calculated by your database, not by Django. ``save()``, because that value is calculated by your database, not by Django.
(For convenience, each model has an ``AutoField`` named ``id`` by default For convenience, each model has an :class:`~django.db.models.AutoField` named
unless you explicitly specify ``primary_key=True`` on a field. See the ``id`` by default unless you explicitly specify ``primary_key=True`` on a field
documentation for ``AutoField`` for more details. in your model. See the documentation for :class:`~django.db.models.AutoField`
for more details.
The ``pk`` property The ``pk`` property
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
@ -177,9 +180,9 @@ correct field in the model.
Explicitly specifying auto-primary-key values Explicitly specifying auto-primary-key values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a model has an ``AutoField`` but you want to define a new object's ID If a model has an :class:`~django.db.models.AutoField` but you want to define a
explicitly when saving, just define it explicitly before saving, rather than new object's ID explicitly when saving, just define it explicitly before
relying on the auto-assignment of the ID:: saving, rather than relying on the auto-assignment of the ID::
>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id # Returns 3. >>> b3.id # Returns 3.
@ -217,13 +220,13 @@ When you save an object, Django performs the following steps:
perform any automated data modification that the field may need perform any automated data modification that the field may need
to perform. 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. Pre-processing is only used on fields that have special behavior. For
For example, if your model has a ``DateField`` with ``auto_now=True``, example, if your model has a :class:`~django.db.models.DateField` with
the pre-save phase will alter the data in the object to ensure that ``auto_now=True``, the pre-save phase will alter the data in the object
the date field contains the current date stamp. (Our documentation to ensure that the date field contains the current date stamp. (Our
doesn't yet include a list of all the fields with this "special documentation doesn't yet include a list of all the fields with this
behavior.") "special behavior.")
3. **Prepare the data for the database.** Each field is asked to provide 3. **Prepare the data for the database.** Each field is asked to provide
its current value in a data type that can be written to the database. its current value in a data type that can be written to the database.
@ -232,10 +235,10 @@ When you save an object, Django performs the following steps:
integers and strings, are 'ready to write' as a Python object. However, integers and strings, are 'ready to write' as a Python object. However,
more complex data types often require some modification. more complex data types often require some modification.
For example, ``DateFields`` use a Python ``datetime`` object to store For example, :class:`~django.db.models.DateField` fields use a Python
data. Databases don't store ``datetime`` objects, so the field value ``datetime`` object to store data. Databases don't store ``datetime``
must be converted into an ISO-compliant date string for insertion objects, so the field value must be converted into an ISO-compliant date
into the database. string for insertion into the database.
4. **Insert the data into the database.** The pre-processed, prepared 4. **Insert the data into the database.** The pre-processed, prepared
data is then composed into an SQL statement for insertion into the data is then composed into an SQL statement for insertion into the
@ -273,12 +276,13 @@ auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below.
Forcing an INSERT or UPDATE Forcing an INSERT or UPDATE
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some rare circumstances, it's necessary to be able to force the ``save()`` In some rare circumstances, it's necessary to be able to force the
method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``. :meth:`~Model.save()` method to perform an SQL ``INSERT`` and not fall back to
Or vice-versa: update, if possible, but not insert a new row. In these cases doing an ``UPDATE``. Or vice-versa: update, if possible, but not insert a new
you can pass the ``force_insert=True`` or ``force_update=True`` parameters to row. In these cases you can pass the ``force_insert=True`` or
the ``save()`` method. Passing both parameters is an error, since you cannot ``force_update=True`` parameters to the :meth:`~Model.save()` method.
both insert *and* update at the same time. Obviously, passing both parameters is an error: you cannot both insert *and*
update at the same time!
It should be very rare that you'll need to use these parameters. Django will It should be very rare that you'll need to use these parameters. Django will
almost always do the right thing and trying to override that will lead to almost always do the right thing and trying to override that will lead to
@ -299,11 +303,16 @@ achieve this is to do something like::
If the old ``number_sold`` value retrieved from the database was 10, then If the old ``number_sold`` value retrieved from the database was 10, then
the value of 11 will be written back to the database. the value of 11 will be written back to the database.
This can be optimized slightly by expressing the update relative to the This sequence has a standard update problem in that it contains a race
original field value, rather than as an explicit assignment of a new value. condition. If another thread of execution has already saved an updated value
Django provides :ref:`F() expressions <query-expressions>` as a way of after the current thread retrieved the old value, the current thread will only
save the old value plus one, rather than the new (current) value plus one.
The process can be made robust and slightly faster by expressing the update
relative to the original field value, rather than as an explicit assignment of
a new value. Django provides :ref:`F() expressions <query-expressions>` for
performing this kind of relative update. Using ``F()`` expressions, the performing this kind of relative update. Using ``F()`` expressions, the
previous example would be expressed as:: previous example is expressed as::
>>> from django.db.models import F >>> from django.db.models import F
>>> product = Product.objects.get(name='Venezuelan Beaver Cheese') >>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
@ -311,8 +320,8 @@ previous example would be expressed as::
>>> product.save() >>> product.save()
This approach doesn't use the initial value from the database. Instead, it This approach doesn't use the initial value from the database. Instead, it
makes the database do the update based on whatever value is current at the makes the database do the update based on whatever value is current at the time
time that the save() is executed. that the :meth:`~Model.save()` is executed.
Once the object has been saved, you must reload the object in order to access Once the object has been saved, you must reload the object in order to access
the actual value that was applied to the updated field:: the actual value that was applied to the updated field::
@ -333,16 +342,15 @@ Deleting objects
.. versionadded:: 1.2 .. versionadded:: 1.2
The ``using`` argument was added. The ``using`` argument was added.
Issues a SQL ``DELETE`` for the object. This only deletes the object Issues a SQL ``DELETE`` for the object. This only deletes the object in the
in the database; the Python instance will still be around, and will database; the Python instance will still exist and will still have data in
still have data in its fields. its fields.
For more details, including how to delete objects in bulk, see For more details, including how to delete objects in bulk, see
:ref:`topics-db-queries-delete`. :ref:`topics-db-queries-delete`.
If you want customized deletion behavior, you can override this If you want customized deletion behavior, you can override the ``delete()``
``delete()`` method. See :ref:`overriding-model-methods` for more method. See :ref:`overriding-model-methods` for more details.
details.
.. _model-instance-methods: .. _model-instance-methods:
@ -351,21 +359,45 @@ Other model instance methods
A few object methods have special purposes. A few object methods have special purposes.
``__unicode__``
---------------
.. method:: Model.__unicode__()
The ``__unicode__()`` method is called whenever you call ``unicode()`` on an
object. Django uses ``unicode(obj)`` (or the related function, :meth:`str(obj)
<Model.__str__>`) in a number of places. Most notably, to display an object in
the Django admin site and as the value inserted into a template when it
displays an object. Thus, you should always return a nice, human-readable
representation of the model from the ``__unicode__()`` method.
For example::
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
def __unicode__(self):
return u'%s %s' % (self.first_name, self.last_name)
If you define a ``__unicode__()`` method on your model and not a
:meth:`~Model.__str__()` method, Django will automatically provide you with a
:meth:`~Model.__str__()` that calls ``__unicode__()`` and then converts the
result correctly to a UTF-8 encoded string object. This is recommended
development practice: define only ``__unicode__()`` and let Django take care of
the conversion to string objects when required.
``__str__`` ``__str__``
----------- -----------
.. method:: Model.__str__() .. method:: Model.__str__()
``__str__()`` is a Python "magic method" that defines what should be returned The ``__str__()`` method is called whenever you call ``str()`` on an object. The main use for this method directly inside Django is when the ``repr()`` output of a model is displayed anywhere (for example, in debugging output).
if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related Thus, you should return a nice, human-readable string for the object's
function, ``unicode(obj)`` -- see below) in a number of places, most notably ``__str__()``. It isn't required to put ``__str__()`` methods everywhere if you have sensible :meth:`~Model.__unicode__()` methods.
as the value displayed to render an object in the Django admin site and as the
value inserted into a template when it displays an object. Thus, you should
always return a nice, human-readable string for the object's ``__str__``.
Although this isn't required, it's strongly encouraged (see the description of
``__unicode__``, below, before putting ``__str__`` methods everywhere).
For example:: The previous :meth:`~Model.__unicode__()` example could be similarly written
using ``__str__()`` like this::
class Person(models.Model): class Person(models.Model):
first_name = models.CharField(max_length=50) first_name = models.CharField(max_length=50)
@ -376,38 +408,13 @@ For example::
# first_name and last_name will be unicode strings. # first_name and last_name will be unicode strings.
return smart_str('%s %s' % (self.first_name, self.last_name)) return smart_str('%s %s' % (self.first_name, self.last_name))
``__unicode__``
---------------
.. method:: Model.__unicode__()
The ``__unicode__()`` method is called whenever you call ``unicode()`` on an
object. Since Django's database backends will return Unicode strings in your
model's attributes, you would normally want to write a ``__unicode__()``
method for your model. The example in the previous section could be written
more simply as::
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
def __unicode__(self):
return u'%s %s' % (self.first_name, self.last_name)
If you define a ``__unicode__()`` method on your model and not a ``__str__()``
method, Django will automatically provide you with a ``__str__()`` that calls
``__unicode__()`` and then converts the result correctly to a UTF-8 encoded
string object. This is recommended development practice: define only
``__unicode__()`` and let Django take care of the conversion to string objects
when required.
``get_absolute_url`` ``get_absolute_url``
-------------------- --------------------
.. method:: Model.get_absolute_url() .. method:: Model.get_absolute_url()
Define a ``get_absolute_url()`` method to tell Django how to calculate the Define a ``get_absolute_url()`` method to tell Django how to calculate the
URL for an object. For example:: canonical URL for an object. For example::
def get_absolute_url(self): def get_absolute_url(self):
return "/people/%i/" % self.id return "/people/%i/" % self.id
@ -520,15 +527,15 @@ More details on named URL patterns are in the :doc:`URL dispatch documentation
Extra instance methods Extra instance methods
====================== ======================
In addition to ``save()``, ``delete()``, a model object might get any or all In addition to :meth:`~Model.save()`, :meth:`~Model.delete()`, a model object
of the following methods: might have some of the following methods:
.. method:: Model.get_FOO_display() .. method:: Model.get_FOO_display()
For every field that has ``choices`` set, the object will have a For every field that has :attr:`~django.db.models.Field.choices` set, the
``get_FOO_display()`` method, where ``FOO`` is the name of the field. This object will have a ``get_FOO_display()`` method, where ``FOO`` is the name of
method returns the "human-readable" value of the field. For example, in the the field. This method returns the "human-readable" value of the field. For
following model:: example, in the following model::
GENDER_CHOICES = ( GENDER_CHOICES = (
('M', 'Male'), ('M', 'Male'),
@ -550,16 +557,17 @@ following model::
.. method:: Model.get_next_by_FOO(\**kwargs) .. method:: Model.get_next_by_FOO(\**kwargs)
.. method:: Model.get_previous_by_FOO(\**kwargs) .. method:: Model.get_previous_by_FOO(\**kwargs)
For every ``DateField`` and ``DateTimeField`` that does not have ``null=True``, For every :class:`~django.db.models.DateField` and
the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()`` :class:`~django.db.models.DateTimeField` that does not have :attr:`null=True
methods, where ``FOO`` is the name of the field. This returns the next and <django.db.models.Field.null>`, the object will have ``get_next_by_FOO()`` and
previous object with respect to the date field, raising the appropriate ``get_previous_by_FOO()`` methods, where ``FOO`` is the name of the field. This
``DoesNotExist`` exception when appropriate. returns the next and previous object with respect to the date field, raising
the appropriate :exc:`~django.db.DoesNotExist` exception when appropriate.
Both methods accept optional keyword arguments, which should be in the format Both methods accept optional keyword arguments, which should be in the format
described in :ref:`Field lookups <field-lookups>`. described in :ref:`Field lookups <field-lookups>`.
Note that in the case of identical date values, these methods will use the ID Note that in the case of identical date values, these methods will use the
as a fallback check. This guarantees that no records are skipped or duplicated. primary key as a tie-breaker. This guarantees that no records are skipped or
duplicated. That also means you cannot use those methods on unsaved objects.
That also means you cannot use those methods on unsaved objects.