diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index 1b04c46..69b8eb2 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -6,48 +6,16 @@ This document explains all the possible :ref:`metadata options ` that you can give your model in its internal ``class Meta``. -Available ``Meta`` options -========================== - -.. currentmodule:: django.db.models - -``abstract`` ------------- - -.. attribute:: Options.abstract - -If ``True``, this model will be an :ref:`abstract base class `. - -``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 ``manage.py startapp`` -- to the model's class name, with an -underscore between them. +name you used in :djadmin:`manage.py 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 @@ -60,210 +28,213 @@ 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. -``db_tablespace`` ------------------ +Available ``Meta`` options +========================== -.. attribute:: Options.db_tablespace +.. currentmodule:: django.db.models -.. versionadded:: 1.0 +.. attribute:: Options.abstract -The name of the database tablespace to use for the model. If the backend doesn't -support tablespaces, this option is ignored. + If ``True``, this model will be an + :ref:`abstract base class `. -``get_latest_by`` ------------------ +.. attribute:: Options.app_label -.. attribute:: Options.get_latest_by + 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:: -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. + app_label = 'myapp' -Example:: +.. attribute:: Options.db_table - get_latest_by = "order_date" + The name of the database table to use for the model:: -See the docs for :meth:`~django.db.models.QuerySet.latest` for more. + db_table = 'music_album' -``managed`` ------------------------ -.. attribute:: Options.managed +.. attribute:: Options.db_tablespace -.. versionadded:: 1.1 + .. versionadded:: 1.0 -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. + The name of the database tablespace to use for the model. If the backend + doesn't support tablespaces, this option is ignored. -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 +.. attribute:: Options.get_latest_by - 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. + 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. - 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, a the intermediary table between one - managed and one unmanaged model *will* be created. + Example:: - 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. + get_latest_by = "order_date" -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. + See the docs for :meth:`~django.db.models.QuerySet.latest` for more. -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`. +.. attribute:: Options.managed -``order_with_respect_to`` -------------------------- + .. versionadded:: 1.1 -.. attribute:: Options.order_with_respect_to + 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. -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:: + 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: - class Answer(models.Model): - question = models.ForeignKey(Question) - # ... + 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. - class Meta: - order_with_respect_to = 'question' + 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, a the intermediary table + between one managed and one unmanaged model *will* be created. -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:: + 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. - >>> question = Question.objects.get(id=1) - >>> question.get_answer_order() - [1, 2, 3] + 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. -The order of a ``Question`` object's related ``Answer`` objects can be set by -passing in a list of ``Answer`` primary keys:: + 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`. - >>> question.set_answer_order([3, 1, 2]) +.. attribute:: Options.order_with_respect_to -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``:: + 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:: - >>> answer = Answer.objects.get(id=2) - >>> answer.get_next_in_order() - - >>> answer.get_previous_in_order() - + class Answer(models.Model): + question = models.ForeignKey(Question) + # ... -``ordering`` ------------- + class Meta: + order_with_respect_to = 'question' .. 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`` ---------------- + 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:: -.. attribute:: Options.permissions + >>> question = Question.objects.get(id=1) + >>> question.get_answer_order() + [1, 2, 3] -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``:: + The order of a ``Question`` object's related ``Answer`` objects can be set + by passing in a list of ``Answer`` primary keys:: - permissions = (("can_deliver_pizzas", "Can deliver pizzas"),) + >>> question.set_answer_order([3, 1, 2]) -This is a list or tuple of 2-tuples in the format ``(permission_code, -human_readable_permission_name)``. + 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``:: -``proxy`` ---------- + >>> answer = Answer.objects.get(id=2) + >>> answer.get_next_in_order() + + >>> answer.get_previous_in_order() + -.. attribute:: Options.proxy +.. attribute:: Options.permissions -.. versionadded:: 1.1 + 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``:: -If set to ``True``, a model which subclasses another model will be treated as -a :ref:`proxy model `. + permissions = (("can_deliver_pizzas", "Can deliver pizzas"),) -``unique_together`` -------------------- + This is a list or tuple of 2-tuples in the format ``(permission_code, + human_readable_permission_name)``. -.. attribute:: Options.unique_together +.. attribute:: Options.proxy -Sets of field names that, taken together, must be unique:: + .. versionadded:: 1.1 - unique_together = (("driver", "restaurant"),) + If set to ``True``, a model which subclasses another model will be treated + as a :ref:`proxy model `. -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). +.. attribute:: Options.unique_together -.. versionadded:: 1.0 + Sets of field names that, taken together, must be unique:: -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") + 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). -``verbose_name`` ----------------- + .. versionadded:: 1.0 -.. attribute:: Options.verbose_name + For convenience, unique_together can be a single list when dealing with a + single set of fields:: + + unique_together = ("driver", "restaurant") -A human-readable name for the object, singular:: +.. attribute:: Options.verbose_name - verbose_name = "pizza" + A human-readable name for the object, singular:: -If this isn't given, Django will use a munged version of the class name: -``CamelCase`` becomes ``camel case``. + verbose_name = "pizza" -``verbose_name_plural`` ------------------------ + If this isn't given, Django will use a munged version of the class name: + ``CamelCase`` becomes ``camel case``. .. attribute:: Options.verbose_name_plural -The plural name for the object:: + The plural name for the object:: + + verbose_name_plural = "stories" + + If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``. - verbose_name_plural = "stories" +.. method:: Options.get_field(name, many_to_many=True) If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.