Ticket #14842: indent-options3.diff

docs/ref/models/options.txt

@@ -6 +6 @@
 <meta-options>` that you can give your model in its internal ``class
 Meta``.
 
-Available ``Meta`` options
-==========================
-
-.. currentmodule:: django.db.models
-
-``abstract``
-------------
-
-.. attribute:: Options.abstract
-
-If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
-
-``app_label``
--------------
-
-.. attribute:: Options.app_label
-
-If a model exists outside of the standard :file:`models.py` (for instance, if
-the app's models are in submodules of ``myapp.models``), the model must define
-which app it is part of::
-
-    app_label = 'myapp'
-
-``db_table``
-------------
-
-.. attribute:: Options.db_table
-
-The name of the database table to use for the model::
-
-    db_table = 'music_album'
-
 .. _table-names:
 
 Table names
-~~~~~~~~~~~
+===========
 
 To save you time, Django automatically derives the name of the database table
 from the name of your model class and the app that contains it. A model's
 database table name is constructed by joining the model's "app label" -- the
-name you used in ``manage.py startapp`` -- to the model's class name, with an
-underscore between them.
+name you used in :djadmin:`manage.py startapp <startapp>` -- to the model's
+class name, with an underscore between them.
 
 For example, if you have an app ``bookstore`` (as created by
 ``manage.py startapp bookstore``), a model defined as ``class Book`` will have
@@ -60 +28 @@
 aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
 Django quotes column and table names behind the scenes.
 
-``db_tablespace``
------------------
+Available ``Meta`` options
+==========================
 
-.. attribute:: Options.db_tablespace
+.. currentmodule:: django.db.models
 
-.. versionadded:: 1.0
+.. attribute:: Options.abstract
 
-The name of the database tablespace to use for the model. If the backend doesn't
-support tablespaces, this option is ignored.
+    If ``True``, this model will be an
+    :ref:`abstract base class <abstract-base-classes>`.
 
-``get_latest_by``
------------------
+.. attribute:: Options.app_label
 
-.. attribute:: Options.get_latest_by
+    If a model exists outside of the standard :file:`models.py` (for instance,
+    if the app's models are in submodules of ``myapp.models``), the model must
+    define which app it is part of::
 
-The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
-specifies the default field to use in your model :class:`Manager`'s
-:class:`~QuerySet.latest` method.
+        app_label = 'myapp'
 
-Example::
+.. attribute:: Options.db_table
 
-    get_latest_by = "order_date"
+    The name of the database table to use for the model::
 
-See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
+        db_table = 'music_album'
 
-``managed``
------------------------
 
-.. attribute:: Options.managed
+.. attribute:: Options.db_tablespace
 
-.. versionadded:: 1.1
+    .. versionadded:: 1.0
 
-Defaults to ``True``, meaning Django will create the appropriate database
-tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
-management command. That is, Django *manages* the database tables' lifecycles.
+    The name of the database tablespace to use for the model. If the backend
+    doesn't support tablespaces, this option is ignored.
 
-If ``False``, no database table creation or deletion operations will be
-performed for this model. This is useful if the model represents an existing
-table or a database view that has been created by some other means. This is
-the *only* difference when ``managed`` is ``False``. All other aspects of
-model handling are exactly the same as normal. This includes
+.. attribute:: Options.get_latest_by
 
-    1. Adding an automatic primary key field to the model if you don't declare
-       it.  To avoid confusion for later code readers, it's recommended to
-       specify all the columns from the database table you are modeling when
-       using unmanaged models.
+    The name of a :class:`DateField` or :class:`DateTimeField` in the model.
+    This specifies the default field to use in your model :class:`Manager`'s
+    :class:`~QuerySet.latest` method.
 
-    2. If a model with ``managed=False`` contains a
-       :class:`~django.db.models.ManyToManyField` that points to another
-       unmanaged model, then the intermediate table for the many-to-many join
-       will also not be created. However, a the intermediary table between one
-       managed and one unmanaged model *will* be created.
+    Example::
 
-       If you need to change this default behavior, create the intermediary
-       table as an explicit model (with ``managed`` set as needed) and use the
-       :attr:`ManyToManyField.through` attribute to make the relation use your
-       custom model.
+        get_latest_by = "order_date"
 
-For tests involving models with ``managed=False``, it's up to you to ensure
-the correct tables are created as part of the test setup.
+    See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
 
-If you're interested in changing the Python-level behavior of a model class,
-you *could* use ``managed=False`` and create a copy of an existing model.
-However, there's a better approach for that situation: :ref:`proxy-models`.
+.. attribute:: Options.managed
 
-``order_with_respect_to``
--------------------------
+    .. versionadded:: 1.1
 
-.. attribute:: Options.order_with_respect_to
+    Defaults to ``True``, meaning Django will create the appropriate database
+    tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
+    management command. That is, Django *manages* the database tables'
+    lifecycles.
 
-Marks this object as "orderable" with respect to the given field. This is almost
-always used with related objects to allow them to be ordered with respect to a
-parent object. For example, if an ``Answer`` relates to a ``Question`` object,
-and a question has more than one answer, and the order of answers matters, you'd
-do this::
+    If ``False``, no database table creation or deletion operations will be
+    performed for this model. This is useful if the model represents an
+    existing table or a database view that has been created by some other
+    means. This is the *only* difference when ``managed=False``. All other
+    aspects of model handling are exactly the same as normal. This includes:
 
-    class Answer(models.Model):
-        question = models.ForeignKey(Question)
-        # ...
+        1. Adding an automatic primary key field to the model if you don't
+           declare it.  To avoid confusion for later code readers, it's
+           recommended to specify all the columns from the database table you
+           are modeling when using unmanaged models.
 
-        class Meta:
-            order_with_respect_to = 'question'
+        2. If a model with ``managed=False`` contains a
+           :class:`~django.db.models.ManyToManyField` that points to another
+           unmanaged model, then the intermediate table for the many-to-many
+           join will also not be created. However, a the intermediary table
+           between one managed and one unmanaged model *will* be created.
 
-When ``order_with_respect_to`` is set, two additional methods are provided to
-retrieve and to set the order of the related objects: ``get_RELATED_order()``
-and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
-example, assuming that a ``Question`` object has multiple related ``Answer``
-objects, the list returned contains the primary keys of the related ``Answer``
-objects::
+           If you need to change this default behavior, create the intermediary
+           table as an explicit model (with ``managed`` set as needed) and use
+           the :attr:`~ManyToManyField.through` attribute to make the relation
+           use your custom model.
 
-    >>> question = Question.objects.get(id=1)
-    >>> question.get_answer_order()
-    [1, 2, 3]
+    For tests involving models with ``managed=False``, it's up to you to ensure
+    the correct tables are created as part of the test setup.
 
-The order of a ``Question`` object's related ``Answer`` objects can be set by
-passing in a list of ``Answer`` primary keys::
+    If you're interested in changing the Python-level behavior of a model class,
+    you *could* use ``managed=False`` and create a copy of an existing model.
+    However, there's a better approach for that situation: :ref:`proxy-models`.
 
-    >>> question.set_answer_order([3, 1, 2])
+.. attribute:: Options.order_with_respect_to
 
-The related objects also get two methods, ``get_next_in_order()`` and
-``get_previous_in_order()``, which can be used to access those objects in their
-proper order. Assuming the ``Answer`` objects are ordered by ``id``::
+    Marks this object as "orderable" with respect to the given field. This is
+    almost always used with related objects to allow them to be ordered with
+    respect to a parent object. For example, if an ``Answer`` relates to a
+    ``Question`` object, and a question has more than one answer, and the order
+    of answers matters, you'd do this::
 
-    >>> answer = Answer.objects.get(id=2)
-    >>> answer.get_next_in_order()
-    <Answer: 3>
-    >>> answer.get_previous_in_order()
-    <Answer: 1>
+        class Answer(models.Model):
+            question = models.ForeignKey(Question)
+            # ...
 
-``ordering``
-------------
+            class Meta:
+                order_with_respect_to = 'question'
 
 .. attribute:: Options.ordering
 
-The default ordering for the object, for use when obtaining lists of objects::
+    The default ordering for the object, for use when obtaining lists of
+    objects::
 
-    ordering = ['-order_date']
+        ordering = ['-order_date']
 
-This is a tuple or list of strings. Each string is a field name with an optional
-"-" prefix, which indicates descending order. Fields without a leading "-" will
-be ordered ascending. Use the string "?" to order randomly.
+    This is a tuple or list of strings. Each string is a field name with an
+    optional "-" prefix, which indicates descending order. Fields without a
+    leading "-" will be ordered ascending. Use the string "?" to order
+    randomly.
 
-.. note::
+    .. note::
 
-    Regardless of how many fields are in :attr:`~Options.ordering`, the admin
-    site uses only the first field.
+        Regardless of how many fields are in :attr:`~Options.ordering`, the
+        admin site uses only the first field.
 
-For example, to order by a ``pub_date`` field ascending, use this::
+    For example, to order by a ``pub_date`` field ascending, use this::
 
-    ordering = ['pub_date']
+        ordering = ['pub_date']
 
-To order by ``pub_date`` descending, use this::
+    To order by ``pub_date`` descending, use this::
 
-    ordering = ['-pub_date']
+        ordering = ['-pub_date']
 
-To order by ``pub_date`` descending, then by ``author`` ascending, use this::
+    To order by ``pub_date`` descending, then by ``author`` ascending, use
+    this::
 
-    ordering = ['-pub_date', 'author']
+        ordering = ['-pub_date', 'author']
 
-``permissions``
----------------
+    When ``order_with_respect_to`` is set, two additional methods are provided
+    to retrieve and to set the order of the related objects:
+    ``get_RELATED_order()`` and ``set_RELATED_order()``, where ``RELATED`` is
+    the lowercased model name. For example, assuming that a ``Question`` object
+    has multiple related ``Answer`` objects, the list returned contains the
+    primary keys of the related ``Answer`` objects::
 
-.. attribute:: Options.permissions
+        >>> question = Question.objects.get(id=1)
+        >>> question.get_answer_order()
+        [1, 2, 3]
 
-Extra permissions to enter into the permissions table when creating this object.
-Add, delete and change permissions are automatically created for each object
-that has ``admin`` set. This example specifies an extra permission,
-``can_deliver_pizzas``::
+    The order of a ``Question`` object's related ``Answer`` objects can be set
+    by passing in a list of ``Answer`` primary keys::
 
-    permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
+        >>> question.set_answer_order([3, 1, 2])
 
-This is a list or tuple of 2-tuples in the format ``(permission_code,
-human_readable_permission_name)``.
+    The related objects also get two methods, ``get_next_in_order()`` and
+    ``get_previous_in_order()``, which can be used to access those objects in
+    their proper order. Assuming the ``Answer`` objects are ordered by ``id``::
 
-``proxy``
----------
+        >>> answer = Answer.objects.get(id=2)
+        >>> answer.get_next_in_order()
+        <Answer: 3>
+        >>> answer.get_previous_in_order()
+        <Answer: 1>
 
-.. attribute:: Options.proxy
+.. attribute:: Options.permissions
 
-.. versionadded:: 1.1
+    Extra permissions to enter into the permissions table when creating this
+    object. Add, delete and change permissions are automatically created for
+    each object that has ``admin`` set. This example specifies an extra
+    permission, ``can_deliver_pizzas``::
 
-If set to ``True``, a model which subclasses another model will be treated as
-a :ref:`proxy model <proxy-models>`.
+        permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
 
-``unique_together``
--------------------
+    This is a list or tuple of 2-tuples in the format ``(permission_code,
+    human_readable_permission_name)``.
 
-.. attribute:: Options.unique_together
+.. attribute:: Options.proxy
 
-Sets of field names that, taken together, must be unique::
+    .. versionadded:: 1.1
 
-    unique_together = (("driver", "restaurant"),)
+    If set to ``True``, a model which subclasses another model will be treated
+    as a :ref:`proxy model <proxy-models>`.
 
-This is a list of lists of fields that must be unique when considered together.
-It's used in the Django admin and is enforced at the database level (i.e., the
-appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
-statement).
+.. attribute:: Options.unique_together
 
-.. versionadded:: 1.0
+    Sets of field names that, taken together, must be unique::
 
-For convenience, unique_together can be a single list when dealing with a single
-set of fields::
+        unique_together = (("driver", "restaurant"),)
 
-    unique_together = ("driver", "restaurant")
+    This is a list of lists of fields that must be unique when considered
+    together. It's used in the Django admin and is enforced at the database level
+    (i.e., the appropriate ``UNIQUE`` statements are included in the
+    ``CREATE TABLE`` statement).
 
-``verbose_name``
-----------------
+    .. versionadded:: 1.0
 
-.. attribute:: Options.verbose_name
+    For convenience, unique_together can be a single list when dealing with a
+    single set of fields::
+
+        unique_together = ("driver", "restaurant")
 
-A human-readable name for the object, singular::
+.. attribute:: Options.verbose_name
 
-    verbose_name = "pizza"
+    A human-readable name for the object, singular::
 
-If this isn't given, Django will use a munged version of the class name:
-``CamelCase`` becomes ``camel case``.
+        verbose_name = "pizza"
 
-``verbose_name_plural``
------------------------
+    If this isn't given, Django will use a munged version of the class name:
+    ``CamelCase`` becomes ``camel case``.
 
 .. attribute:: Options.verbose_name_plural
 
-The plural name for the object::
+    The plural name for the object::
+
+        verbose_name_plural = "stories"
+
+    If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
 
-    verbose_name_plural = "stories"
+.. method:: Options.get_field(name, many_to_many=True)
 
 If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.