mirror of
https://github.com/django/django.git
synced 2024-12-25 02:26:12 +00:00
285 lines
9.6 KiB
Plaintext
285 lines
9.6 KiB
Plaintext
======================
|
|
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``.
|
|
|
|
Available ``Meta`` options
|
|
==========================
|
|
|
|
.. currentmodule:: django.db.models
|
|
|
|
``abstract``
|
|
------------
|
|
|
|
.. attribute:: Options.abstract
|
|
|
|
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::
|
|
|
|
app_label = 'myapp'
|
|
|
|
``db_table``
|
|
------------
|
|
|
|
.. attribute:: Options.db_table
|
|
|
|
The name of the database table to use for the model::
|
|
|
|
db_table = 'music_album'
|
|
|
|
.. _table-names:
|
|
|
|
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 :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
|
|
a database table named ``bookstore_book``.
|
|
|
|
To override the database table name, use the ``db_table`` parameter in
|
|
``class Meta``.
|
|
|
|
If your database table name is an SQL reserved word, or contains characters that
|
|
aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
|
|
Django quotes column and table names behind the scenes.
|
|
|
|
.. admonition:: Use lowercase table names for MySQL
|
|
|
|
It is strongly advised that you use lowercase table names when you override
|
|
the table name via ``db_table``, particularly if you are using the MySQL
|
|
backend. See the :ref:`MySQL notes <mysql-notes>` for more details.
|
|
|
|
|
|
``db_tablespace``
|
|
-----------------
|
|
|
|
.. attribute:: Options.db_tablespace
|
|
|
|
The name of the :doc:`database tablespace </topics/db/tablespaces>` to use
|
|
for this model. The default is the project's :setting:`DEFAULT_TABLESPACE`
|
|
setting, if set. 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.
|
|
|
|
Example::
|
|
|
|
get_latest_by = "order_date"
|
|
|
|
See the docs for :meth:`~django.db.models.query.QuerySet.latest` for more.
|
|
|
|
``managed``
|
|
-----------
|
|
|
|
.. attribute:: Options.managed
|
|
|
|
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=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.
|
|
|
|
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.
|
|
|
|
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`.
|
|
|
|
``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::
|
|
|
|
class Answer(models.Model):
|
|
question = models.ForeignKey(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::
|
|
|
|
>>> 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::
|
|
|
|
>>> 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``::
|
|
|
|
>>> answer = Answer.objects.get(id=2)
|
|
>>> answer.get_next_in_order()
|
|
<Answer: 3>
|
|
>>> answer.get_previous_in_order()
|
|
<Answer: 1>
|
|
|
|
.. admonition:: Changing order_with_respect_to
|
|
|
|
``order_with_respect_to`` adds an additional field/database column
|
|
named ``_order``, so be sure to handle that as you would any other
|
|
change to your models if you add or change ``order_with_respect_to``
|
|
after your initial :djadmin:`syncdb`.
|
|
|
|
``ordering``
|
|
------------
|
|
|
|
.. attribute:: Options.ordering
|
|
|
|
The default ordering for the object, for use when obtaining lists of objects::
|
|
|
|
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.
|
|
|
|
For example, to order by a ``pub_date`` field ascending, use this::
|
|
|
|
ordering = ['pub_date']
|
|
|
|
To order by ``pub_date`` descending, use this::
|
|
|
|
ordering = ['-pub_date']
|
|
|
|
To order by ``pub_date`` descending, then by ``author`` ascending, use this::
|
|
|
|
ordering = ['-pub_date', 'author']
|
|
|
|
.. versionchanged:: 1.4
|
|
The Django admin honors all elements in the list/tuple; before 1.4, only
|
|
the first one was respected.
|
|
|
|
``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``::
|
|
|
|
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)``.
|
|
|
|
``proxy``
|
|
---------
|
|
|
|
.. attribute:: Options.proxy
|
|
|
|
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::
|
|
|
|
unique_together = (("driver", "restaurant"),)
|
|
|
|
This is a tuple of tuples 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 tuple when dealing with a single
|
|
set of fields::
|
|
|
|
unique_together = ("driver", "restaurant")
|
|
|
|
A :class:`~django.db.models.ManyToManyField` cannot be included in
|
|
unique_together. (It's not clear what that would even mean!) If you
|
|
need to validate uniqueness related to a
|
|
:class:`~django.db.models.ManyToManyField`, try using a signal or
|
|
an explicit :attr:`through <ManyToManyField.through>` model.
|
|
|
|
``verbose_name``
|
|
----------------
|
|
|
|
.. attribute:: Options.verbose_name
|
|
|
|
A human-readable name for the object, singular::
|
|
|
|
verbose_name = "pizza"
|
|
|
|
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::
|
|
|
|
verbose_name_plural = "stories"
|
|
|
|
If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
|