PageRenderTime 31ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

Plain Text | 262 lines | 175 code | 87 blank | 0 comment | 0 complexity | 5e464a0a1c0e3d181a90f3a62ece387f MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ======================
  2. Model ``Meta`` options
  3. ======================
  4. This document explains all the possible :ref:`metadata options
  5. <meta-options>` that you can give your model in its internal
  6. ``class Meta``.
  7. Available ``Meta`` options
  8. ==========================
  9. .. currentmodule:: django.db.models
  10. ``abstract``
  11. ------------
  12. .. attribute:: Options.abstract
  13. If ``abstract = True``, this model will be an
  14. :ref:`abstract base class <abstract-base-classes>`.
  15. ``app_label``
  16. -------------
  17. .. attribute:: Options.app_label
  18. If a model exists outside of the standard :file:`` (for instance,
  19. if the app's models are in submodules of ``myapp.models``), the model must
  20. define which app it is part of::
  21. app_label = 'myapp'
  22. ``db_table``
  23. ------------
  24. .. attribute:: Options.db_table
  25. The name of the database table to use for the model::
  26. db_table = 'music_album'
  27. .. _table-names:
  28. Table names
  29. ~~~~~~~~~~~
  30. To save you time, Django automatically derives the name of the database table
  31. from the name of your model class and the app that contains it. A model's
  32. database table name is constructed by joining the model's "app label" -- the
  33. name you used in :djadmin:` startapp <startapp>` -- to the model's
  34. class name, with an underscore between them.
  35. For example, if you have an app ``bookstore`` (as created by
  36. `` startapp bookstore``), a model defined as ``class Book`` will have
  37. a database table named ``bookstore_book``.
  38. To override the database table name, use the ``db_table`` parameter in
  39. ``class Meta``.
  40. If your database table name is an SQL reserved word, or contains characters that
  41. aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
  42. Django quotes column and table names behind the scenes.
  43. ``db_tablespace``
  44. -----------------
  45. .. attribute:: Options.db_tablespace
  46. The name of the database tablespace to use for the model. If the backend
  47. doesn't support tablespaces, this option is ignored.
  48. ``get_latest_by``
  49. -----------------
  50. .. attribute:: Options.get_latest_by
  51. The name of a :class:`DateField` or :class:`DateTimeField` in the model.
  52. This specifies the default field to use in your model :class:`Manager`'s
  53. :class:`~QuerySet.latest` method.
  54. Example::
  55. get_latest_by = "order_date"
  56. See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
  57. ``managed``
  58. -----------
  59. .. attribute:: Options.managed
  60. Defaults to ``True``, meaning Django will create the appropriate database
  61. tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
  62. management command. That is, Django *manages* the database tables' lifecycles.
  63. If ``False``, no database table creation or deletion operations will be
  64. performed for this model. This is useful if the model represents an existing
  65. table or a database view that has been created by some other means. This is
  66. the *only* difference when ``managed=False``. All other aspects of
  67. model handling are exactly the same as normal. This includes
  68. 1. Adding an automatic primary key field to the model if you don't declare
  69. it. To avoid confusion for later code readers, it's recommended to
  70. specify all the columns from the database table you are modeling when
  71. using unmanaged models.
  72. 2. If a model with ``managed=False`` contains a
  73. :class:`~django.db.models.ManyToManyField` that points to another
  74. unmanaged model, then the intermediate table for the many-to-many join
  75. will also not be created. However, the intermediary table between one
  76. managed and one unmanaged model *will* be created.
  77. If you need to change this default behavior, create the intermediary
  78. table as an explicit model (with ``managed`` set as needed) and use the
  79. :attr:`ManyToManyField.through` attribute to make the relation use your
  80. custom model.
  81. For tests involving models with ``managed=False``, it's up to you to ensure
  82. the correct tables are created as part of the test setup.
  83. If you're interested in changing the Python-level behavior of a model class,
  84. you *could* use ``managed=False`` and create a copy of an existing model.
  85. However, there's a better approach for that situation: :ref:`proxy-models`.
  86. ``order_with_respect_to``
  87. -------------------------
  88. .. attribute:: Options.order_with_respect_to
  89. Marks this object as "orderable" with respect to the given field. This is almost
  90. always used with related objects to allow them to be ordered with respect to a
  91. parent object. For example, if an ``Answer`` relates to a ``Question`` object,
  92. and a question has more than one answer, and the order of answers matters, you'd
  93. do this::
  94. class Answer(models.Model):
  95. question = models.ForeignKey(Question)
  96. # ...
  97. class Meta:
  98. order_with_respect_to = 'question'
  99. When ``order_with_respect_to`` is set, two additional methods are provided to
  100. retrieve and to set the order of the related objects: ``get_RELATED_order()``
  101. and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
  102. example, assuming that a ``Question`` object has multiple related ``Answer``
  103. objects, the list returned contains the primary keys of the related ``Answer``
  104. objects::
  105. >>> question = Question.objects.get(id=1)
  106. >>> question.get_answer_order()
  107. [1, 2, 3]
  108. The order of a ``Question`` object's related ``Answer`` objects can be set by
  109. passing in a list of ``Answer`` primary keys::
  110. >>> question.set_answer_order([3, 1, 2])
  111. The related objects also get two methods, ``get_next_in_order()`` and
  112. ``get_previous_in_order()``, which can be used to access those objects in their
  113. proper order. Assuming the ``Answer`` objects are ordered by ``id``::
  114. >>> answer = Answer.objects.get(id=2)
  115. >>> answer.get_next_in_order()
  116. <Answer: 3>
  117. >>> answer.get_previous_in_order()
  118. <Answer: 1>
  119. ``ordering``
  120. ------------
  121. .. attribute:: Options.ordering
  122. The default ordering for the object, for use when obtaining lists of objects::
  123. ordering = ['-order_date']
  124. This is a tuple or list of strings. Each string is a field name with an optional
  125. "-" prefix, which indicates descending order. Fields without a leading "-" will
  126. be ordered ascending. Use the string "?" to order randomly.
  127. .. note::
  128. Regardless of how many fields are in :attr:`~Options.ordering`, the admin
  129. site uses only the first field.
  130. For example, to order by a ``pub_date`` field ascending, use this::
  131. ordering = ['pub_date']
  132. To order by ``pub_date`` descending, use this::
  133. ordering = ['-pub_date']
  134. To order by ``pub_date`` descending, then by ``author`` ascending, use this::
  135. ordering = ['-pub_date', 'author']
  136. ``permissions``
  137. ---------------
  138. .. attribute:: Options.permissions
  139. Extra permissions to enter into the permissions table when creating this object.
  140. Add, delete and change permissions are automatically created for each object
  141. that has ``admin`` set. This example specifies an extra permission,
  142. ``can_deliver_pizzas``::
  143. permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
  144. This is a list or tuple of 2-tuples in the format ``(permission_code,
  145. human_readable_permission_name)``.
  146. ``proxy``
  147. ---------
  148. .. attribute:: Options.proxy
  149. If ``proxy = True``, a model which subclasses another model will be treated as
  150. a :ref:`proxy model <proxy-models>`.
  151. ``unique_together``
  152. -------------------
  153. .. attribute:: Options.unique_together
  154. Sets of field names that, taken together, must be unique::
  155. unique_together = (("driver", "restaurant"),)
  156. This is a list of lists of fields that must be unique when considered together.
  157. It's used in the Django admin and is enforced at the database level (i.e., the
  158. appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
  159. statement).
  160. For convenience, unique_together can be a single list when dealing with a single
  161. set of fields::
  162. unique_together = ("driver", "restaurant")
  163. ``verbose_name``
  164. ----------------
  165. .. attribute:: Options.verbose_name
  166. A human-readable name for the object, singular::
  167. verbose_name = "pizza"
  168. If this isn't given, Django will use a munged version of the class name:
  169. ``CamelCase`` becomes ``camel case``.
  170. ``verbose_name_plural``
  171. -----------------------
  172. .. attribute:: Options.verbose_name_plural
  173. The plural name for the object::
  174. verbose_name_plural = "stories"
  175. If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.