Ticket #14842: indent-options2.diff

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

Rebased on master, takes into account new ordering docs.

  • docs/ref/models/options.txt 

    diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 1b04c46..30d38be 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==========================
     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
    6555
    6656.. attribute:: Options.db_tablespace
    6757
    68 .. versionadded:: 1.0
     58    .. versionadded:: 1.0
    6959
    70 The name of the database tablespace to use for the model. If the backend doesn't
    71 support tablespaces, this option is ignored.
    72 
    73 ``get_latest_by``
    74 -----------------
     60    The name of the database tablespace to use for the model. If the backend
     61    doesn't support tablespaces, this option is ignored.
    7562
    7663.. attribute:: Options.get_latest_by
    7764
    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.
     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.
    8168
    82 Example::
     69    Example::
    8370
    84     get_latest_by = "order_date"
     71        get_latest_by = "order_date"
    8572
    86 See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
    87 
    88 ``managed``
    89 -----------------------
     73    See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
    9074
    9175.. attribute:: Options.managed
    9276
    93 .. versionadded:: 1.1
    94 
    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.
    98 
    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
    104 
    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.
    109 
    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.
    115 
    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.
    120 
    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.
    123 
    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`.
    127 
    128 ``order_with_respect_to``
    129 -------------------------
     77    .. versionadded:: 1.1
     78
     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.
     83
     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:
     89
     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.
     94
     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.
     100
     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.
     105
     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.
     108
     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`.
    130112
    131113.. attribute:: Options.order_with_respect_to
    132114
    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::
    138 
    139     class Answer(models.Model):
    140         question = models.ForeignKey(Question)
    141         # ...
    142 
    143         class Meta:
    144             order_with_respect_to = 'question'
    145 
    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::
    152 
    153     >>> question = Question.objects.get(id=1)
    154     >>> question.get_answer_order()
    155     [1, 2, 3]
    156 
    157 The order of a ``Question`` object's related ``Answer`` objects can be set by
    158 passing in a list of ``Answer`` primary keys::
    159 
    160     >>> question.set_answer_order([3, 1, 2])
    161 
    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``::
    165 
    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>
    171 
    172 ``ordering``
    173 ------------
     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::
     120
     121        class Answer(models.Model):
     122            question = models.ForeignKey(Question)
     123            # ...
     124
     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::
     164
     165        >>> question = Question.objects.get(id=1)
     166        >>> question.get_answer_order()
     167        [1, 2, 3]
     168
     169    The order of a ``Question`` object's related ``Answer`` objects can be set
     170    by passing in a list of ``Answer`` primary keys::
     171
     172        >>> question.set_answer_order([3, 1, 2])
     173
     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``::
     177
     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>
    204183
    205184.. attribute:: Options.permissions
    206185
    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``::
     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``::
    211190
    212     permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
     191        permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
    213192
    214 This is a list or tuple of 2-tuples in the format ``(permission_code,
    215 human_readable_permission_name)``.
    216 
    217 ``proxy``
    218 ---------
     193    This is a list or tuple of 2-tuples in the format ``(permission_code,
     194    human_readable_permission_name)``.
    219195
    220196.. attribute:: Options.proxy
    221197
    222 .. versionadded:: 1.1
     198    .. versionadded:: 1.1
    223199
    224 If set to ``True``, a model which subclasses another model will be treated as
    225 a :ref:`proxy model <proxy-models>`.
    226 
    227 ``unique_together``
    228 -------------------
     200    If set to ``True``, a model which subclasses another model will be treated
     201    as a :ref:`proxy model <proxy-models>`.
    229202
    230203.. attribute:: Options.unique_together
    231204
    232 Sets of field names that, taken together, must be unique::
     205    Sets of field names that, taken together, must be unique::
    233206
    234     unique_together = (("driver", "restaurant"),)
     207        unique_together = (("driver", "restaurant"),)
    235208
    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).
     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).
    240213
    241 .. versionadded:: 1.0
     214    .. versionadded:: 1.0
    242215
    243 For convenience, unique_together can be a single list when dealing with a single
    244 set of fields::
     216    For convenience, unique_together can be a single list when dealing with a
     217    single set of fields::
    245218
    246     unique_together = ("driver", "restaurant")
    247 
    248 ``verbose_name``
    249 ----------------
     219        unique_together = ("driver", "restaurant")
    250220
    251221.. attribute:: Options.verbose_name
    252222
    253 A human-readable name for the object, singular::
     223    A human-readable name for the object, singular::
    254224
    255     verbose_name = "pizza"
     225        verbose_name = "pizza"
    256226
    257 If this isn't given, Django will use a munged version of the class name:
    258 ``CamelCase`` becomes ``camel case``.
    259 
    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::
    266233
    267     verbose_name_plural = "stories"
     234        verbose_name_plural = "stories"
    268235
    269 If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
     236    If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
     237
     238
     239Meta information at runtime
     240===========================
     241
     242Model instances have a ``_meta`` attribute, which is an instance of
     243:class:`django.db.models.Options`. Any of the properties listed above are
     244available on ``_meta`` as well as those listed below.
     245
     246.. attribute:: Options.auto_field
     247
     248    If the model has an :class:`~django.db.models.AutoField`, this property
     249    will return that field. Otherwise, this property will be undefined.
     250    Check :attr:`Options.has_auto_field` before trying to access.
     251
     252.. attribute:: Options.has_auto_field
     253
     254    ``True`` if this model has an :class:`~django.db.models.AutoField`. If
     255    ``True``, :attr:`Options.auto_field` returns this field.
     256
     257.. attribute:: Options.pk
     258
     259    Returns the :attr:`~Field.primary_key` field for this Model, either one
     260    explicitly defined or the generated :class:`~django.db.models.AutoField`.
     261
     262.. method:: Options.get_field(name, many_to_many=True)
     263
     264    Returns the field with the given name. If the field does not exist for
     265    this model, raises :exc:`~django.db.models.fields.FieldDoesNotExist`.
Back to Top