Ticket #14842: indent-options.diff

File indent-options.diff, 13.5 KB (added by Adam Vandenberg, 14 years ago)
  • docs/ref/models/options.txt

    diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
    index cfae675..3dfcdff 100644
    a b This document explains all the possible :ref:`metadata options  
    66<meta-options>` that you can give your model in its internal ``class
    77Meta``.
    88
     9Available ``Meta`` options
     10==========================
     11
     12.. currentmodule:: django.db.models
     13
     14``abstract``
     15------------
     16
     17.. attribute:: Options.abstract
     18
     19If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
     20
     21``app_label``
     22-------------
     23
     24.. attribute:: Options.app_label
     25
     26If a model exists outside of the standard :file:`models.py` (for instance, if
     27the app's models are in submodules of ``myapp.models``), the model must define
     28which app it is part of::
     29
     30    app_label = 'myapp'
     31
     32``db_table``
     33------------
     34
     35.. attribute:: Options.db_table
     36
     37The name of the database table to use for the model::
     38
     39    db_table = 'music_album'
     40
    941.. _table-names:
    1042
    1143Table names
    12 ===========
     44~~~~~~~~~~~
    1345
    1446To save you time, Django automatically derives the name of the database table
    1547from the name of your model class and the app that contains it. A model's
    1648database table name is constructed by joining the model's "app label" -- the
    17 name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
    18 class name, with an underscore between them.
     49name you used in ``manage.py startapp`` -- to the model's class name, with an
     50underscore between them.
    1951
    2052For example, if you have an app ``bookstore`` (as created by
    2153``manage.py startapp bookstore``), a model defined as ``class Book`` will have
    If your database table name is an SQL reserved word, or contains characters that  
    2860aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
    2961Django quotes column and table names behind the scenes.
    3062
    31 Available ``Meta`` options
    32 ==========================
    33 
    34 .. currentmodule:: django.db.models
    35 
    36 .. attribute:: Options.abstract
    37 
    38     If ``True``, this model will be an
    39     :ref:`abstract base class <abstract-base-classes>`.
    40 
    41 .. attribute:: Options.app_label
    42 
    43     If a model exists outside of the standard :file:`models.py` (for instance,
    44     if the app's models are in submodules of ``myapp.models``), the model must
    45     define which app it is part of::
    46 
    47         app_label = 'myapp'
    48 
    49 .. attribute:: Options.db_table
    50 
    51     The name of the database table to use for the model::
    52 
    53         db_table = 'music_album'
    54 
     63``db_tablespace``
     64-----------------
    5565
    5666.. attribute:: Options.db_tablespace
    5767
    58     .. versionadded:: 1.0
     68.. versionadded:: 1.0
     69
     70The name of the database tablespace to use for the model. If the backend doesn't
     71support tablespaces, this option is ignored.
    5972
    60     The name of the database tablespace to use for the model. If the backend
    61     doesn't support tablespaces, this option is ignored.
     73``get_latest_by``
     74-----------------
    6275
    6376.. attribute:: Options.get_latest_by
    6477
    65     The name of a :class:`DateField` or :class:`DateTimeField` in the model.
    66     This specifies the default field to use in your model :class:`Manager`'s
    67     :class:`~QuerySet.latest` method.
     78The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
     79specifies the default field to use in your model :class:`Manager`'s
     80:class:`~QuerySet.latest` method.
    6881
    69     Example::
     82Example::
    7083
    71         get_latest_by = "order_date"
     84    get_latest_by = "order_date"
    7285
    73     See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
     86See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
     87
     88``managed``
     89-----------------------
    7490
    7591.. attribute:: Options.managed
    7692
    77     .. versionadded:: 1.1
     93.. versionadded:: 1.1
     94
     95Defaults to ``True``, meaning Django will create the appropriate database
     96tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
     97management command. That is, Django *manages* the database tables' lifecycles.
    7898
    79     Defaults to ``True``, meaning Django will create the appropriate database
    80     tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
    81     management command. That is, Django *manages* the database tables'
    82     lifecycles.
     99If ``False``, no database table creation or deletion operations will be
     100performed for this model. This is useful if the model represents an existing
     101table or a database view that has been created by some other means. This is
     102the *only* difference when ``managed`` is ``False``. All other aspects of
     103model handling are exactly the same as normal. This includes
    83104
    84     If ``False``, no database table creation or deletion operations will be
    85     performed for this model. This is useful if the model represents an
    86     existing table or a database view that has been created by some other
    87     means. This is the *only* difference when ``managed=False``. All other
    88     aspects of model handling are exactly the same as normal. This includes:
     105    1. Adding an automatic primary key field to the model if you don't declare
     106       it.  To avoid confusion for later code readers, it's recommended to
     107       specify all the columns from the database table you are modeling when
     108       using unmanaged models.
    89109
    90         1. Adding an automatic primary key field to the model if you don't
    91            declare it.  To avoid confusion for later code readers, it's
    92            recommended to specify all the columns from the database table you
    93            are modeling when using unmanaged models.
     110    2. If a model with ``managed=False`` contains a
     111       :class:`~django.db.models.ManyToManyField` that points to another
     112       unmanaged model, then the intermediate table for the many-to-many join
     113       will also not be created. However, a the intermediary table between one
     114       managed and one unmanaged model *will* be created.
    94115
    95         2. If a model with ``managed=False`` contains a
    96            :class:`~django.db.models.ManyToManyField` that points to another
    97            unmanaged model, then the intermediate table for the many-to-many
    98            join will also not be created. However, a the intermediary table
    99            between one managed and one unmanaged model *will* be created.
     116       If you need to change this default behavior, create the intermediary
     117       table as an explicit model (with ``managed`` set as needed) and use the
     118       :attr:`ManyToManyField.through` attribute to make the relation use your
     119       custom model.
    100120
    101            If you need to change this default behavior, create the intermediary
    102            table as an explicit model (with ``managed`` set as needed) and use
    103            the :attr:`~ManyToManyField.through` attribute to make the relation
    104            use your custom model.
     121For tests involving models with ``managed=False``, it's up to you to ensure
     122the correct tables are created as part of the test setup.
    105123
    106     For tests involving models with ``managed=False``, it's up to you to ensure
    107     the correct tables are created as part of the test setup.
     124If you're interested in changing the Python-level behavior of a model class,
     125you *could* use ``managed=False`` and create a copy of an existing model.
     126However, there's a better approach for that situation: :ref:`proxy-models`.
    108127
    109     If you're interested in changing the Python-level behavior of a model class,
    110     you *could* use ``managed=False`` and create a copy of an existing model.
    111     However, there's a better approach for that situation: :ref:`proxy-models`.
     128``order_with_respect_to``
     129-------------------------
    112130
    113131.. attribute:: Options.order_with_respect_to
    114132
    115     Marks this object as "orderable" with respect to the given field. This is
    116     almost always used with related objects to allow them to be ordered with
    117     respect to a parent object. For example, if an ``Answer`` relates to a
    118     ``Question`` object, and a question has more than one answer, and the order
    119     of answers matters, you'd do this::
     133Marks this object as "orderable" with respect to the given field. This is almost
     134always used with related objects to allow them to be ordered with respect to a
     135parent object. For example, if an ``Answer`` relates to a ``Question`` object,
     136and a question has more than one answer, and the order of answers matters, you'd
     137do this::
     138
     139    class Answer(models.Model):
     140        question = models.ForeignKey(Question)
     141        # ...
    120142
    121         class Answer(models.Model):
    122             question = models.ForeignKey(Question)
    123             # ...
     143        class Meta:
     144            order_with_respect_to = 'question'
    124145
    125             class Meta:
    126                 order_with_respect_to = 'question'
     146``ordering``
     147------------
    127148
    128149.. attribute:: Options.ordering
    129150
    130     The default ordering for the object, for use when obtaining lists of
    131     objects::
     151The default ordering for the object, for use when obtaining lists of objects::
    132152
    133         ordering = ['-order_date']
     153    ordering = ['-order_date']
    134154
    135     This is a tuple or list of strings. Each string is a field name with an
    136     optional "-" prefix, which indicates descending order. Fields without a
    137     leading "-" will be ordered ascending. Use the string "?" to order
    138     randomly.
     155This is a tuple or list of strings. Each string is a field name with an optional
     156"-" prefix, which indicates descending order. Fields without a leading "-" will
     157be ordered ascending. Use the string "?" to order randomly.
    139158
    140     .. note::
     159.. note::
    141160
    142         Regardless of how many fields are in :attr:`~Options.ordering`, the
    143         admin site uses only the first field.
     161    Regardless of how many fields are in :attr:`~Options.ordering`, the admin
     162    site uses only the first field.
    144163
    145     For example, to order by a ``pub_date`` field ascending, use this::
     164For example, to order by a ``pub_date`` field ascending, use this::
    146165
    147         ordering = ['pub_date']
     166    ordering = ['pub_date']
    148167
    149     To order by ``pub_date`` descending, use this::
     168To order by ``pub_date`` descending, use this::
    150169
    151         ordering = ['-pub_date']
     170    ordering = ['-pub_date']
    152171
    153     To order by ``pub_date`` descending, then by ``author`` ascending, use
    154     this::
     172To order by ``pub_date`` descending, then by ``author`` ascending, use this::
    155173
    156         ordering = ['-pub_date', 'author']
     174    ordering = ['-pub_date', 'author']
     175
     176``permissions``
     177---------------
    157178
    158179.. attribute:: Options.permissions
    159180
    160     Extra permissions to enter into the permissions table when creating this
    161     object. Add, delete and change permissions are automatically created for
    162     each object that has ``admin`` set. This example specifies an extra
    163     permission, ``can_deliver_pizzas``::
     181Extra permissions to enter into the permissions table when creating this object.
     182Add, delete and change permissions are automatically created for each object
     183that has ``admin`` set. This example specifies an extra permission,
     184``can_deliver_pizzas``::
     185
     186    permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
    164187
    165         permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
     188This is a list or tuple of 2-tuples in the format ``(permission_code,
     189human_readable_permission_name)``.
    166190
    167     This is a list or tuple of 2-tuples in the format ``(permission_code,
    168     human_readable_permission_name)``.
     191``proxy``
     192---------
    169193
    170194.. attribute:: Options.proxy
    171195
    172     .. versionadded:: 1.1
     196.. versionadded:: 1.1
     197
     198If set to ``True``, a model which subclasses another model will be treated as
     199a :ref:`proxy model <proxy-models>`.
    173200
    174     If set to ``True``, a model which subclasses another model will be treated
    175     as a :ref:`proxy model <proxy-models>`.
     201``unique_together``
     202-------------------
    176203
    177204.. attribute:: Options.unique_together
    178205
    179     Sets of field names that, taken together, must be unique::
     206Sets of field names that, taken together, must be unique::
    180207
    181         unique_together = (("driver", "restaurant"),)
     208    unique_together = (("driver", "restaurant"),)
    182209
    183     This is a list of lists of fields that must be unique when considered
    184     together. It's used in the Django admin and is enforced at the database level
    185     (i.e., the appropriate ``UNIQUE`` statements are included in the
    186     ``CREATE TABLE`` statement).
     210This is a list of lists of fields that must be unique when considered together.
     211It's used in the Django admin and is enforced at the database level (i.e., the
     212appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
     213statement).
    187214
    188     .. versionadded:: 1.0
     215.. versionadded:: 1.0
    189216
    190     For convenience, unique_together can be a single list when dealing with a
    191     single set of fields::
     217For convenience, unique_together can be a single list when dealing with a single
     218set of fields::
    192219
    193         unique_together = ("driver", "restaurant")
     220    unique_together = ("driver", "restaurant")
     221
     222``verbose_name``
     223----------------
    194224
    195225.. attribute:: Options.verbose_name
    196226
    197     A human-readable name for the object, singular::
     227A human-readable name for the object, singular::
     228
     229    verbose_name = "pizza"
    198230
    199         verbose_name = "pizza"
     231If this isn't given, Django will use a munged version of the class name:
     232``CamelCase`` becomes ``camel case``.
    200233
    201     If this isn't given, Django will use a munged version of the class name:
    202     ``CamelCase`` becomes ``camel case``.
     234``verbose_name_plural``
     235-----------------------
    203236
    204237.. attribute:: Options.verbose_name_plural
    205238
    206     The plural name for the object::
     239The plural name for the object::
    207240
    208         verbose_name_plural = "stories"
     241    verbose_name_plural = "stories"
    209242
    210     If this isn't given, Django will use
    211     :attr:`~Options.verbose_name` + ``"s"``.
     243If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
Back to Top