PageRenderTime 123ms CodeModel.GetById 60ms app.highlight 2ms RepoModel.GetById 59ms app.codeStats 0ms

/docs/ref/models/options.txt

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