[1.2.X] Fixed #14842 - Indent the model Meta options. Thanks adamv.
Backport of r15110 from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15111 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Timo Graham
parent
6c51b80c04
commit
cd2cf87243
|
|
@ -3,8 +3,8 @@ Model ``Meta`` options
|
|||
======================
|
||||
|
||||
This document explains all the possible :ref:`metadata options
|
||||
<meta-options>` that you can give your model in its internal ``class
|
||||
Meta``.
|
||||
<meta-options>` that you can give your model in its internal
|
||||
``class Meta``.
|
||||
|
||||
Available ``Meta`` options
|
||||
==========================
|
||||
|
|
@ -16,27 +16,28 @@ Available ``Meta`` options
|
|||
|
||||
.. attribute:: Options.abstract
|
||||
|
||||
If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
|
||||
If ``abstract = True``, this model will be an
|
||||
:ref:`abstract base class <abstract-base-classes>`.
|
||||
|
||||
``app_label``
|
||||
-------------
|
||||
|
||||
.. attribute:: Options.app_label
|
||||
|
||||
If a model exists outside of the standard :file:`models.py` (for instance, if
|
||||
the app's models are in submodules of ``myapp.models``), the model must define
|
||||
which app it is part of::
|
||||
If a model exists outside of the standard :file:`models.py` (for instance,
|
||||
if the app's models are in submodules of ``myapp.models``), the model must
|
||||
define which app it is part of::
|
||||
|
||||
app_label = 'myapp'
|
||||
app_label = 'myapp'
|
||||
|
||||
``db_table``
|
||||
------------
|
||||
|
||||
.. attribute:: Options.db_table
|
||||
|
||||
The name of the database table to use for the model::
|
||||
The name of the database table to use for the model::
|
||||
|
||||
db_table = 'music_album'
|
||||
db_table = 'music_album'
|
||||
|
||||
.. _table-names:
|
||||
|
||||
|
|
@ -46,8 +47,8 @@ Table names
|
|||
To save you time, Django automatically derives the name of the database table
|
||||
from the name of your model class and the app that contains it. A model's
|
||||
database table name is constructed by joining the model's "app label" -- the
|
||||
name you used in ``manage.py startapp`` -- to the model's class name, with an
|
||||
underscore between them.
|
||||
name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
|
||||
class name, with an underscore between them.
|
||||
|
||||
For example, if you have an app ``bookstore`` (as created by
|
||||
``manage.py startapp bookstore``), a model defined as ``class Book`` will have
|
||||
|
|
@ -65,201 +66,201 @@ Django quotes column and table names behind the scenes.
|
|||
|
||||
.. attribute:: Options.db_tablespace
|
||||
|
||||
The name of the database tablespace to use for the model. If the backend doesn't
|
||||
support tablespaces, this option is ignored.
|
||||
The name of the database tablespace to use for the model. If the backend
|
||||
doesn't support tablespaces, this option is ignored.
|
||||
|
||||
``get_latest_by``
|
||||
-----------------
|
||||
|
||||
.. attribute:: Options.get_latest_by
|
||||
|
||||
The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
|
||||
specifies the default field to use in your model :class:`Manager`'s
|
||||
:class:`~QuerySet.latest` method.
|
||||
The name of a :class:`DateField` or :class:`DateTimeField` in the model.
|
||||
This specifies the default field to use in your model :class:`Manager`'s
|
||||
:class:`~QuerySet.latest` method.
|
||||
|
||||
Example::
|
||||
Example::
|
||||
|
||||
get_latest_by = "order_date"
|
||||
get_latest_by = "order_date"
|
||||
|
||||
See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
|
||||
See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
|
||||
|
||||
``managed``
|
||||
-----------------------
|
||||
-----------
|
||||
|
||||
.. attribute:: Options.managed
|
||||
|
||||
.. versionadded:: 1.1
|
||||
.. versionadded:: 1.1
|
||||
|
||||
Defaults to ``True``, meaning Django will create the appropriate database
|
||||
tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
|
||||
management command. That is, Django *manages* the database tables' lifecycles.
|
||||
Defaults to ``True``, meaning Django will create the appropriate database
|
||||
tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
|
||||
management command. That is, Django *manages* the database tables' lifecycles.
|
||||
|
||||
If ``False``, no database table creation or deletion operations will be
|
||||
performed for this model. This is useful if the model represents an existing
|
||||
table or a database view that has been created by some other means. This is
|
||||
the *only* difference when ``managed`` is ``False``. All other aspects of
|
||||
model handling are exactly the same as normal. This includes
|
||||
If ``False``, no database table creation or deletion operations will be
|
||||
performed for this model. This is useful if the model represents an existing
|
||||
table or a database view that has been created by some other means. This is
|
||||
the *only* difference when ``managed=False``. All other aspects of
|
||||
model handling are exactly the same as normal. This includes
|
||||
|
||||
1. Adding an automatic primary key field to the model if you don't declare
|
||||
it. To avoid confusion for later code readers, it's recommended to
|
||||
specify all the columns from the database table you are modeling when
|
||||
using unmanaged models.
|
||||
1. Adding an automatic primary key field to the model if you don't declare
|
||||
it. To avoid confusion for later code readers, it's recommended to
|
||||
specify all the columns from the database table you are modeling when
|
||||
using unmanaged models.
|
||||
|
||||
2. If a model with ``managed=False`` contains a
|
||||
:class:`~django.db.models.ManyToManyField` that points to another
|
||||
unmanaged model, then the intermediate table for the many-to-many join
|
||||
will also not be created. However, the intermediary table between one
|
||||
managed and one unmanaged model *will* be created.
|
||||
2. If a model with ``managed=False`` contains a
|
||||
:class:`~django.db.models.ManyToManyField` that points to another
|
||||
unmanaged model, then the intermediate table for the many-to-many join
|
||||
will also not be created. However, the intermediary table between one
|
||||
managed and one unmanaged model *will* be created.
|
||||
|
||||
If you need to change this default behavior, create the intermediary
|
||||
table as an explicit model (with ``managed`` set as needed) and use the
|
||||
:attr:`ManyToManyField.through` attribute to make the relation use your
|
||||
custom model.
|
||||
If you need to change this default behavior, create the intermediary
|
||||
table as an explicit model (with ``managed`` set as needed) and use the
|
||||
:attr:`ManyToManyField.through` attribute to make the relation use your
|
||||
custom model.
|
||||
|
||||
For tests involving models with ``managed=False``, it's up to you to ensure
|
||||
the correct tables are created as part of the test setup.
|
||||
For tests involving models with ``managed=False``, it's up to you to ensure
|
||||
the correct tables are created as part of the test setup.
|
||||
|
||||
If you're interested in changing the Python-level behavior of a model class,
|
||||
you *could* use ``managed=False`` and create a copy of an existing model.
|
||||
However, there's a better approach for that situation: :ref:`proxy-models`.
|
||||
If you're interested in changing the Python-level behavior of a model class,
|
||||
you *could* use ``managed=False`` and create a copy of an existing model.
|
||||
However, there's a better approach for that situation: :ref:`proxy-models`.
|
||||
|
||||
``order_with_respect_to``
|
||||
-------------------------
|
||||
|
||||
.. attribute:: Options.order_with_respect_to
|
||||
|
||||
Marks this object as "orderable" with respect to the given field. This is almost
|
||||
always used with related objects to allow them to be ordered with respect to a
|
||||
parent object. For example, if an ``Answer`` relates to a ``Question`` object,
|
||||
and a question has more than one answer, and the order of answers matters, you'd
|
||||
do this::
|
||||
Marks this object as "orderable" with respect to the given field. This is almost
|
||||
always used with related objects to allow them to be ordered with respect to a
|
||||
parent object. For example, if an ``Answer`` relates to a ``Question`` object,
|
||||
and a question has more than one answer, and the order of answers matters, you'd
|
||||
do this::
|
||||
|
||||
class Answer(models.Model):
|
||||
question = models.ForeignKey(Question)
|
||||
# ...
|
||||
class Answer(models.Model):
|
||||
question = models.ForeignKey(Question)
|
||||
# ...
|
||||
|
||||
class Meta:
|
||||
order_with_respect_to = 'question'
|
||||
class Meta:
|
||||
order_with_respect_to = 'question'
|
||||
|
||||
When ``order_with_respect_to`` is set, two additional methods are provided to
|
||||
retrieve and to set the order of the related objects: ``get_RELATED_order()``
|
||||
and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
|
||||
example, assuming that a ``Question`` object has multiple related ``Answer``
|
||||
objects, the list returned contains the primary keys of the related ``Answer``
|
||||
objects::
|
||||
When ``order_with_respect_to`` is set, two additional methods are provided to
|
||||
retrieve and to set the order of the related objects: ``get_RELATED_order()``
|
||||
and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
|
||||
example, assuming that a ``Question`` object has multiple related ``Answer``
|
||||
objects, the list returned contains the primary keys of the related ``Answer``
|
||||
objects::
|
||||
|
||||
>>> question = Question.objects.get(id=1)
|
||||
>>> question.get_answer_order()
|
||||
[1, 2, 3]
|
||||
>>> question = Question.objects.get(id=1)
|
||||
>>> question.get_answer_order()
|
||||
[1, 2, 3]
|
||||
|
||||
The order of a ``Question`` object's related ``Answer`` objects can be set by
|
||||
passing in a list of ``Answer`` primary keys::
|
||||
The order of a ``Question`` object's related ``Answer`` objects can be set by
|
||||
passing in a list of ``Answer`` primary keys::
|
||||
|
||||
>>> question.set_answer_order([3, 1, 2])
|
||||
>>> question.set_answer_order([3, 1, 2])
|
||||
|
||||
The related objects also get two methods, ``get_next_in_order()`` and
|
||||
``get_previous_in_order()``, which can be used to access those objects in their
|
||||
proper order. Assuming the ``Answer`` objects are ordered by ``id``::
|
||||
The related objects also get two methods, ``get_next_in_order()`` and
|
||||
``get_previous_in_order()``, which can be used to access those objects in their
|
||||
proper order. Assuming the ``Answer`` objects are ordered by ``id``::
|
||||
|
||||
>>> answer = Answer.objects.get(id=2)
|
||||
>>> answer.get_next_in_order()
|
||||
<Answer: 3>
|
||||
>>> answer.get_previous_in_order()
|
||||
<Answer: 1>
|
||||
>>> answer = Answer.objects.get(id=2)
|
||||
>>> answer.get_next_in_order()
|
||||
<Answer: 3>
|
||||
>>> answer.get_previous_in_order()
|
||||
<Answer: 1>
|
||||
|
||||
``ordering``
|
||||
------------
|
||||
|
||||
.. attribute:: Options.ordering
|
||||
|
||||
The default ordering for the object, for use when obtaining lists of objects::
|
||||
The default ordering for the object, for use when obtaining lists of objects::
|
||||
|
||||
ordering = ['-order_date']
|
||||
ordering = ['-order_date']
|
||||
|
||||
This is a tuple or list of strings. Each string is a field name with an optional
|
||||
"-" prefix, which indicates descending order. Fields without a leading "-" will
|
||||
be ordered ascending. Use the string "?" to order randomly.
|
||||
This is a tuple or list of strings. Each string is a field name with an optional
|
||||
"-" prefix, which indicates descending order. Fields without a leading "-" will
|
||||
be ordered ascending. Use the string "?" to order randomly.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
Regardless of how many fields are in :attr:`~Options.ordering`, the admin
|
||||
site uses only the first field.
|
||||
Regardless of how many fields are in :attr:`~Options.ordering`, the admin
|
||||
site uses only the first field.
|
||||
|
||||
For example, to order by a ``pub_date`` field ascending, use this::
|
||||
For example, to order by a ``pub_date`` field ascending, use this::
|
||||
|
||||
ordering = ['pub_date']
|
||||
ordering = ['pub_date']
|
||||
|
||||
To order by ``pub_date`` descending, use this::
|
||||
To order by ``pub_date`` descending, use this::
|
||||
|
||||
ordering = ['-pub_date']
|
||||
ordering = ['-pub_date']
|
||||
|
||||
To order by ``pub_date`` descending, then by ``author`` ascending, use this::
|
||||
To order by ``pub_date`` descending, then by ``author`` ascending, use this::
|
||||
|
||||
ordering = ['-pub_date', 'author']
|
||||
ordering = ['-pub_date', 'author']
|
||||
|
||||
``permissions``
|
||||
---------------
|
||||
|
||||
.. attribute:: Options.permissions
|
||||
|
||||
Extra permissions to enter into the permissions table when creating this object.
|
||||
Add, delete and change permissions are automatically created for each object
|
||||
that has ``admin`` set. This example specifies an extra permission,
|
||||
``can_deliver_pizzas``::
|
||||
Extra permissions to enter into the permissions table when creating this object.
|
||||
Add, delete and change permissions are automatically created for each object
|
||||
that has ``admin`` set. This example specifies an extra permission,
|
||||
``can_deliver_pizzas``::
|
||||
|
||||
permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
|
||||
permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
|
||||
|
||||
This is a list or tuple of 2-tuples in the format ``(permission_code,
|
||||
human_readable_permission_name)``.
|
||||
This is a list or tuple of 2-tuples in the format ``(permission_code,
|
||||
human_readable_permission_name)``.
|
||||
|
||||
``proxy``
|
||||
---------
|
||||
|
||||
.. attribute:: Options.proxy
|
||||
|
||||
.. versionadded:: 1.1
|
||||
.. versionadded:: 1.1
|
||||
|
||||
If set to ``True``, a model which subclasses another model will be treated as
|
||||
a :ref:`proxy model <proxy-models>`.
|
||||
If ``proxy = True``, a model which subclasses another model will be treated as
|
||||
a :ref:`proxy model <proxy-models>`.
|
||||
|
||||
``unique_together``
|
||||
-------------------
|
||||
|
||||
.. attribute:: Options.unique_together
|
||||
|
||||
Sets of field names that, taken together, must be unique::
|
||||
Sets of field names that, taken together, must be unique::
|
||||
|
||||
unique_together = (("driver", "restaurant"),)
|
||||
unique_together = (("driver", "restaurant"),)
|
||||
|
||||
This is a list of lists of fields that must be unique when considered together.
|
||||
It's used in the Django admin and is enforced at the database level (i.e., the
|
||||
appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
|
||||
statement).
|
||||
This is a list of lists of fields that must be unique when considered together.
|
||||
It's used in the Django admin and is enforced at the database level (i.e., the
|
||||
appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
|
||||
statement).
|
||||
|
||||
For convenience, unique_together can be a single list when dealing with a single
|
||||
set of fields::
|
||||
For convenience, unique_together can be a single list when dealing with a single
|
||||
set of fields::
|
||||
|
||||
unique_together = ("driver", "restaurant")
|
||||
unique_together = ("driver", "restaurant")
|
||||
|
||||
``verbose_name``
|
||||
----------------
|
||||
|
||||
.. attribute:: Options.verbose_name
|
||||
|
||||
A human-readable name for the object, singular::
|
||||
A human-readable name for the object, singular::
|
||||
|
||||
verbose_name = "pizza"
|
||||
verbose_name = "pizza"
|
||||
|
||||
If this isn't given, Django will use a munged version of the class name:
|
||||
``CamelCase`` becomes ``camel case``.
|
||||
If this isn't given, Django will use a munged version of the class name:
|
||||
``CamelCase`` becomes ``camel case``.
|
||||
|
||||
``verbose_name_plural``
|
||||
-----------------------
|
||||
|
||||
.. attribute:: Options.verbose_name_plural
|
||||
|
||||
The plural name for the object::
|
||||
The plural name for the object::
|
||||
|
||||
verbose_name_plural = "stories"
|
||||
verbose_name_plural = "stories"
|
||||
|
||||
If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
|
||||
If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
|
||||
|
|
|
|||
Loading…
Reference in New Issue