Ticket #14842: indent-options3.diff

File indent-options3.diff, 16.0 KB (added by Adam Vandenberg, 14 years ago)

Trying again.

  • docs/ref/models/options.txt

    diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
    index 1b04c46..69b8eb2 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
    9 Available ``Meta`` options
    10 ==========================
    11 
    12 .. currentmodule:: django.db.models
    13 
    14 ``abstract``
    15 ------------
    16 
    17 .. attribute:: Options.abstract
    18 
    19 If ``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 
    26 If a model exists outside of the standard :file:`models.py` (for instance, if
    27 the app's models are in submodules of ``myapp.models``), the model must define
    28 which app it is part of::
    29 
    30     app_label = 'myapp'
    31 
    32 ``db_table``
    33 ------------
    34 
    35 .. attribute:: Options.db_table
    36 
    37 The name of the database table to use for the model::
    38 
    39     db_table = 'music_album'
    40 
    419.. _table-names:
    4210
    4311Table names
    44 ~~~~~~~~~~~
     12===========
    4513
    4614To save you time, Django automatically derives the name of the database table
    4715from the name of your model class and the app that contains it. A model's
    4816database table name is constructed by joining the model's "app label" -- the
    49 name you used in ``manage.py startapp`` -- to the model's class name, with an
    50 underscore between them.
     17name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
     18class name, with an underscore between them.
    5119
    5220For example, if you have an app ``bookstore`` (as created by
    5321``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  
    6028aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
    6129Django quotes column and table names behind the scenes.
    6230
    63 ``db_tablespace``
    64 -----------------
     31Available ``Meta`` options
     32==========================
    6533
    66 .. attribute:: Options.db_tablespace
     34.. currentmodule:: django.db.models
    6735
    68 .. versionadded:: 1.0
     36.. attribute:: Options.abstract
    6937
    70 The name of the database tablespace to use for the model. If the backend doesn't
    71 support tablespaces, this option is ignored.
     38    If ``True``, this model will be an
     39    :ref:`abstract base class <abstract-base-classes>`.
    7240
    73 ``get_latest_by``
    74 -----------------
     41.. attribute:: Options.app_label
    7542
    76 .. attribute:: Options.get_latest_by
     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::
    7746
    78 The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
    79 specifies the default field to use in your model :class:`Manager`'s
    80 :class:`~QuerySet.latest` method.
     47        app_label = 'myapp'
    8148
    82 Example::
     49.. attribute:: Options.db_table
    8350
    84     get_latest_by = "order_date"
     51    The name of the database table to use for the model::
    8552
    86 See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
     53        db_table = 'music_album'
    8754
    88 ``managed``
    89 -----------------------
    9055
    91 .. attribute:: Options.managed
     56.. attribute:: Options.db_tablespace
    9257
    93 .. versionadded:: 1.1
     58    .. versionadded:: 1.0
    9459
    95 Defaults to ``True``, meaning Django will create the appropriate database
    96 tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
    97 management command. That is, Django *manages* the database tables' lifecycles.
     60    The name of the database tablespace to use for the model. If the backend
     61    doesn't support tablespaces, this option is ignored.
    9862
    99 If ``False``, no database table creation or deletion operations will be
    100 performed for this model. This is useful if the model represents an existing
    101 table or a database view that has been created by some other means. This is
    102 the *only* difference when ``managed`` is ``False``. All other aspects of
    103 model handling are exactly the same as normal. This includes
     63.. attribute:: Options.get_latest_by
    10464
    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.
     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.
    10968
    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.
     69    Example::
    11570
    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.
     71        get_latest_by = "order_date"
    12072
    121 For tests involving models with ``managed=False``, it's up to you to ensure
    122 the correct tables are created as part of the test setup.
     73    See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
    12374
    124 If you're interested in changing the Python-level behavior of a model class,
    125 you *could* use ``managed=False`` and create a copy of an existing model.
    126 However, there's a better approach for that situation: :ref:`proxy-models`.
     75.. attribute:: Options.managed
    12776
    128 ``order_with_respect_to``
    129 -------------------------
     77    .. versionadded:: 1.1
    13078
    131 .. attribute:: Options.order_with_respect_to
     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.
    13283
    133 Marks this object as "orderable" with respect to the given field. This is almost
    134 always used with related objects to allow them to be ordered with respect to a
    135 parent object. For example, if an ``Answer`` relates to a ``Question`` object,
    136 and a question has more than one answer, and the order of answers matters, you'd
    137 do this::
     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:
    13889
    139     class Answer(models.Model):
    140         question = models.ForeignKey(Question)
    141         # ...
     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.
    14294
    143         class Meta:
    144             order_with_respect_to = 'question'
     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.
    145100
    146 When ``order_with_respect_to`` is set, two additional methods are provided to
    147 retrieve and to set the order of the related objects: ``get_RELATED_order()``
    148 and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
    149 example, assuming that a ``Question`` object has multiple related ``Answer``
    150 objects, the list returned contains the primary keys of the related ``Answer``
    151 objects::
     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.
    152105
    153     >>> question = Question.objects.get(id=1)
    154     >>> question.get_answer_order()
    155     [1, 2, 3]
     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.
    156108
    157 The order of a ``Question`` object's related ``Answer`` objects can be set by
    158 passing in a list of ``Answer`` primary keys::
     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`.
    159112
    160     >>> question.set_answer_order([3, 1, 2])
     113.. attribute:: Options.order_with_respect_to
    161114
    162 The related objects also get two methods, ``get_next_in_order()`` and
    163 ``get_previous_in_order()``, which can be used to access those objects in their
    164 proper order. Assuming the ``Answer`` objects are ordered by ``id``::
     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::
    165120
    166     >>> answer = Answer.objects.get(id=2)
    167     >>> answer.get_next_in_order()
    168     <Answer: 3>
    169     >>> answer.get_previous_in_order()
    170     <Answer: 1>
     121        class Answer(models.Model):
     122            question = models.ForeignKey(Question)
     123            # ...
    171124
    172 ``ordering``
    173 ------------
     125            class Meta:
     126                order_with_respect_to = 'question'
    174127
    175128.. attribute:: Options.ordering
    176129
    177 The default ordering for the object, for use when obtaining lists of objects::
     130    The default ordering for the object, for use when obtaining lists of
     131    objects::
    178132
    179     ordering = ['-order_date']
     133        ordering = ['-order_date']
    180134
    181 This is a tuple or list of strings. Each string is a field name with an optional
    182 "-" prefix, which indicates descending order. Fields without a leading "-" will
    183 be ordered ascending. Use the string "?" to order randomly.
     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.
    184139
    185 .. note::
     140    .. note::
    186141
    187     Regardless of how many fields are in :attr:`~Options.ordering`, the admin
    188     site uses only the first field.
     142        Regardless of how many fields are in :attr:`~Options.ordering`, the
     143        admin site uses only the first field.
    189144
    190 For example, to order by a ``pub_date`` field ascending, use this::
     145    For example, to order by a ``pub_date`` field ascending, use this::
    191146
    192     ordering = ['pub_date']
     147        ordering = ['pub_date']
    193148
    194 To order by ``pub_date`` descending, use this::
     149    To order by ``pub_date`` descending, use this::
    195150
    196     ordering = ['-pub_date']
     151        ordering = ['-pub_date']
    197152
    198 To order by ``pub_date`` descending, then by ``author`` ascending, use this::
     153    To order by ``pub_date`` descending, then by ``author`` ascending, use
     154    this::
    199155
    200     ordering = ['-pub_date', 'author']
     156        ordering = ['-pub_date', 'author']
    201157
    202 ``permissions``
    203 ---------------
     158    When ``order_with_respect_to`` is set, two additional methods are provided
     159    to retrieve and to set the order of the related objects:
     160    ``get_RELATED_order()`` and ``set_RELATED_order()``, where ``RELATED`` is
     161    the lowercased model name. For example, assuming that a ``Question`` object
     162    has multiple related ``Answer`` objects, the list returned contains the
     163    primary keys of the related ``Answer`` objects::
    204164
    205 .. attribute:: Options.permissions
     165        >>> question = Question.objects.get(id=1)
     166        >>> question.get_answer_order()
     167        [1, 2, 3]
    206168
    207 Extra permissions to enter into the permissions table when creating this object.
    208 Add, delete and change permissions are automatically created for each object
    209 that has ``admin`` set. This example specifies an extra permission,
    210 ``can_deliver_pizzas``::
     169    The order of a ``Question`` object's related ``Answer`` objects can be set
     170    by passing in a list of ``Answer`` primary keys::
    211171
    212     permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
     172        >>> question.set_answer_order([3, 1, 2])
    213173
    214 This is a list or tuple of 2-tuples in the format ``(permission_code,
    215 human_readable_permission_name)``.
     174    The related objects also get two methods, ``get_next_in_order()`` and
     175    ``get_previous_in_order()``, which can be used to access those objects in
     176    their proper order. Assuming the ``Answer`` objects are ordered by ``id``::
    216177
    217 ``proxy``
    218 ---------
     178        >>> answer = Answer.objects.get(id=2)
     179        >>> answer.get_next_in_order()
     180        <Answer: 3>
     181        >>> answer.get_previous_in_order()
     182        <Answer: 1>
    219183
    220 .. attribute:: Options.proxy
     184.. attribute:: Options.permissions
    221185
    222 .. versionadded:: 1.1
     186    Extra permissions to enter into the permissions table when creating this
     187    object. Add, delete and change permissions are automatically created for
     188    each object that has ``admin`` set. This example specifies an extra
     189    permission, ``can_deliver_pizzas``::
    223190
    224 If set to ``True``, a model which subclasses another model will be treated as
    225 a :ref:`proxy model <proxy-models>`.
     191        permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
    226192
    227 ``unique_together``
    228 -------------------
     193    This is a list or tuple of 2-tuples in the format ``(permission_code,
     194    human_readable_permission_name)``.
    229195
    230 .. attribute:: Options.unique_together
     196.. attribute:: Options.proxy
    231197
    232 Sets of field names that, taken together, must be unique::
     198    .. versionadded:: 1.1
    233199
    234     unique_together = (("driver", "restaurant"),)
     200    If set to ``True``, a model which subclasses another model will be treated
     201    as a :ref:`proxy model <proxy-models>`.
    235202
    236 This is a list of lists of fields that must be unique when considered together.
    237 It's used in the Django admin and is enforced at the database level (i.e., the
    238 appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
    239 statement).
     203.. attribute:: Options.unique_together
    240204
    241 .. versionadded:: 1.0
     205    Sets of field names that, taken together, must be unique::
    242206
    243 For convenience, unique_together can be a single list when dealing with a single
    244 set of fields::
     207        unique_together = (("driver", "restaurant"),)
    245208
    246     unique_together = ("driver", "restaurant")
     209    This is a list of lists of fields that must be unique when considered
     210    together. It's used in the Django admin and is enforced at the database level
     211    (i.e., the appropriate ``UNIQUE`` statements are included in the
     212    ``CREATE TABLE`` statement).
    247213
    248 ``verbose_name``
    249 ----------------
     214    .. versionadded:: 1.0
    250215
    251 .. attribute:: Options.verbose_name
     216    For convenience, unique_together can be a single list when dealing with a
     217    single set of fields::
     218
     219        unique_together = ("driver", "restaurant")
    252220
    253 A human-readable name for the object, singular::
     221.. attribute:: Options.verbose_name
    254222
    255     verbose_name = "pizza"
     223    A human-readable name for the object, singular::
    256224
    257 If this isn't given, Django will use a munged version of the class name:
    258 ``CamelCase`` becomes ``camel case``.
     225        verbose_name = "pizza"
    259226
    260 ``verbose_name_plural``
    261 -----------------------
     227    If this isn't given, Django will use a munged version of the class name:
     228    ``CamelCase`` becomes ``camel case``.
    262229
    263230.. attribute:: Options.verbose_name_plural
    264231
    265 The plural name for the object::
     232    The plural name for the object::
     233
     234        verbose_name_plural = "stories"
     235
     236    If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
    266237
    267     verbose_name_plural = "stories"
     238.. method:: Options.get_field(name, many_to_many=True)
    268239
    269240If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
Back to Top