Fixed #15233 -- reST/Sphinx markup corrections in numerous areas, mostly...

============================

.. class:: InlineModelAdmin

.. class:: TabularInline

.. class:: StackedInline

    The admin interface has the ability to edit models on the same page as a

    parent model. These are called inlines. Suppose you have these two models::

    Django provides two subclasses of ``InlineModelAdmin`` and they are:

        * ``TabularInline``

        * ``StackedInline``

        * :class:`~django.contrib.admin.TabularInline`

        * :class:`~django.contrib.admin.StackedInline`

    The difference between these two is merely the template used to render

    them.

Form preview

============

.. module:: django.contrib.formtools

.. module:: django.contrib.formtools.preview

    :synopsis: Displays an HTML form, forces a preview, then does something

               with the submission.

      b. If it's not valid, redisplays the form with error messages.

   3. When the "confirmation" form is submitted from the preview page, calls

      a hook that you define -- a

      :meth:`~django.contrib.formtools.FormPreview.done()` method that gets

      :meth:`~django.contrib.formtools.preview.FormPreview.done()` method that gets

      passed the valid data.

The framework enforces the required preview by passing a shared-secret hash to

              :file:`django/contrib/formtools/templates` directory, and add that

              directory to your :setting:`TEMPLATE_DIRS` setting.

    2. Create a :class:`~django.contrib.formtools.FormPreview` subclass that

       overrides the :meth:`~django.contrib.formtools.FormPreview.done()`

    2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that

       overrides the :meth:`~django.contrib.formtools.preview.FormPreview.done()`

       method::

           from django.contrib.formtools.preview import FormPreview

       is the end result of the form being submitted.

    3. Change your URLconf to point to an instance of your

       :class:`~django.contrib.formtools.FormPreview` subclass::

       :class:`~django.contrib.formtools.preview.FormPreview` subclass::

           from myapp.preview import SomeModelFormPreview

           from myapp.forms import SomeModelForm

.. class:: FormPreview

A :class:`~django.contrib.formtools.FormPreview` class is a simple Python class

A :class:`~django.contrib.formtools.preview.FormPreview` class is a simple Python class

that represents the preview workflow.

:class:`~django.contrib.formtools.FormPreview` classes must subclass

:class:`~django.contrib.formtools.preview.FormPreview` classes must subclass

``django.contrib.formtools.preview.FormPreview`` and override the

:meth:`~django.contrib.formtools.FormPreview.done()` method. They can live

:meth:`~django.contrib.formtools.preview.FormPreview.done()` method. They can live

anywhere in your codebase.

``FormPreview`` templates

By default, the form is rendered via the template :file:`formtools/form.html`,

and the preview page is rendered via the template :file:`formtools/preview.html`.

These values can be overridden for a particular form preview by setting

:attr:`~django.contrib.formtools.FormPreview.preview_template` and

:attr:`~django.contrib.formtools.FormPreview.form_template` attributes on the

:attr:`~django.contrib.formtools.preview.FormPreview.preview_template` and

:attr:`~django.contrib.formtools.preview.FormPreview.form_template` attributes on the

FormPreview subclass. See :file:`django/contrib/formtools/templates` for the

default templates.

    Takes two optional arguments, ``date_format`` and ``time_format``, which

    work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.

.. currentmodule:: django.forms.extras.widgets

.. class:: SelectDateWidget

    Wrapper around three select widgets: one each for month, day, and year.

Specifying widgets

------------------

.. currentmodule:: django.forms

.. attribute:: Form.widget

Aggregation functions

---------------------

.. currentmodule:: django.db.models

Django provides the following aggregation functions in the

``django.db.models`` module. For details on how to use these

aggregate functions, see

.. function:: get_max_age(response)

Returns the max-age from the response Cache-Control header as an integer (or

``None`` if it wasn't found or wasn't an integer).

    Returns the max-age from the response Cache-Control header as an integer

    (or ``None`` if it wasn't found or wasn't an integer).

.. function:: patch_response_headers(response, cache_timeout=None)

    Each header is only added if it isn't already set.

``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting is

used by default.

    ``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting

    is used by default.

.. function:: add_never_cache_headers(response)

.. function:: patch_vary_headers(response, newheaders)

    Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object.

``newheaders`` is a list of header names that should be in ``Vary``. Existing

headers in ``Vary`` aren't removed.

    ``newheaders`` is a list of header names that should be in ``Vary``.

    Existing headers in ``Vary`` aren't removed.

.. function:: get_cache_key(request, key_prefix=None)

Returns a cache key based on the request path. It can be used in the request

phase because it pulls the list of headers to take into account from the

global path registry and uses those to build a cache key to check against.

    Returns a cache key based on the request path. It can be used in the

    request phase because it pulls the list of headers to take into account

    from the global path registry and uses those to build a cache key to

    check against.

    If there is no headerlist stored, the page needs to be rebuilt, so this

    function returns ``None``.

    Learns what headers to take into account for some request path from the

    response object. It stores those headers in a global path registry so that

later access to that path will know what headers to take into account without

building the response object itself. The headers are named in the ``Vary``

header of the response, but we want to prevent response generation.

    later access to that path will know what headers to take into account

    without building the response object itself. The headers are named in

    the ``Vary`` header of the response, but we want to prevent response

    generation.

The list of headers to use for cache key generation is stored in the same cache

as the pages themselves. If the cache ages some data out of the cache, this

just means that we have to build the response once to get at the Vary header

and so at the list of headers to use for the cache key.

    The list of headers to use for cache key generation is stored in the same

    cache as the pages themselves. If the cache ages some data out of the

    cache, this just means that we have to build the response once to get at

    the Vary header and so at the list of headers to use for the cache key.

SortedDict

==========

.. module:: django.utils.datastructures

   :synopsis: A dictionary that keeps its keys in the order in which they're inserted.

.. class:: django.utils.datastructures.SortedDict

.. class:: SortedDict

Methods

-------

Extra methods that ``SortedDict`` adds to the standard Python ``dict`` class.

    The :class:`django.utils.datastructures.SortedDict` class is a dictionary

    that keeps its keys in the order in which they're inserted.

    ``SortedDict`` adds two additional methods to the standard Python ``dict``

    class:

    .. method:: insert(index, key, value)

        Returns the value of the item at the given zero-based index.

Creating new SortedDict

-----------------------

Creating a new SortedDict

-------------------------

Creating a new ``SortedDict`` must be done in a way where ordering is

guaranteed. For example::

.. class:: StrAndUnicode

A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8 bytestring.

Useful as a mix-in.

    A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8

    bytestring. Useful as a mix-in.

.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')

Returns a ``unicode`` object representing ``s``. Treats bytestrings using the

'encoding' codec.

    Returns a ``unicode`` object representing ``s``. Treats bytestrings using

    the 'encoding' codec.

If ``strings_only`` is ``True``, don't convert (some) non-string-like objects.

    If ``strings_only`` is ``True``, don't convert (some) non-string-like

    objects.

.. function:: is_protected_type(obj)

.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')

Similar to ``smart_unicode``, except that lazy instances are resolved to strings,

rather than kept as lazy objects.

    Similar to ``smart_unicode``, except that lazy instances are resolved to

    strings, rather than kept as lazy objects.

If ``strings_only`` is ``True``, don't convert (some) non-string-like objects.

    If ``strings_only`` is ``True``, don't convert (some) non-string-like

    objects.

.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')

Returns a bytestring version of ``s``, encoded as specified in ``encoding``.

    Returns a bytestring version of ``s``, encoded as specified in

    ``encoding``.

If ``strings_only`` is ``True``, don't convert (some) non-string-like objects.

    If ``strings_only`` is ``True``, don't convert (some) non-string-like

    objects.

.. function:: iri_to_uri(iri)

Convert an Internationalized Resource Identifier (IRI) portion to a URI portion

that is suitable for inclusion in a URL.

    Convert an Internationalized Resource Identifier (IRI) portion to a URI

    portion that is suitable for inclusion in a URL.

This is the algorithm from section 3.1 of `RFC 3987`_.  However, since we are

assuming input is either UTF-8 or unicode already, we can simplify things a

little from the full method.

    This is the algorithm from section 3.1 of `RFC 3987`_.  However, since we

    are assuming input is either UTF-8 or unicode already, we can simplify

    things a little from the full method.

    .. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt

    Base class for all syndication feeds. Subclasses should provide write().

Methods

~~~~~~~

    .. method:: add_item(title, link, description, [author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs])

        Adds an item to the feed. All args are expected to be Python ``unicode``

    .. method:: root_attributes()

Return extra attributes to place on the root (i.e. feed/channel) element.

Called from write().

        Return extra attributes to place on the root (i.e. feed/channel)

        element. Called from write().

    .. method:: add_root_elements(handler)

Add elements in the root (i.e. feed/channel) element. Called from write().

        Add elements in the root (i.e. feed/channel) element.

        Called from write().

    .. method:: item_attributes(item)

Return extra attributes to place on each item (i.e. item/entry) element.

        Return extra attributes to place on each item (i.e. item/entry)

        element.

    .. method:: add_item_elements(handler, item)

    .. method:: write(outfile, encoding)

Outputs the feed in the given encoding to ``outfile``, which is a file-like

object. Subclasses should override this.

        Outputs the feed in the given encoding to ``outfile``, which is a

        file-like object. Subclasses should override this.

    .. method:: writeString(encoding)

    .. method:: latest_post_date()

Returns the latest item's ``pubdate``. If none of them have a ``pubdate``,

this returns the current date/time.

        Returns the latest item's ``pubdate``. If none of them have a

        ``pubdate``, this returns the current date/time.

Enclosure

---------

.. function:: urlquote(url, safe='/')

A version of Python's ``urllib.quote()`` function that can operate on unicode

strings. The url is first UTF-8 encoded before quoting. The returned string

can safely be used as part of an argument to a subsequent ``iri_to_uri()``

call without double-quoting occurring. Employs lazy execution.

    A version of Python's ``urllib.quote()`` function that can operate on

    unicode strings. The url is first UTF-8 encoded before quoting. The

    returned string can safely be used as part of an argument to a subsequent

    ``iri_to_uri()`` call without double-quoting occurring. Employs lazy

    execution.

.. function:: urlquote_plus(url, safe='')

A version of Python's urllib.quote_plus() function that can operate on unicode

strings. The url is first UTF-8 encoded before quoting. The returned string can

safely be used as part of an argument to a subsequent iri_to_uri() call without

double-quoting occurring. Employs lazy execution.

    A version of Python's urllib.quote_plus() function that can operate on

    unicode strings. The url is first UTF-8 encoded before quoting. The

    returned string can safely be used as part of an argument to a subsequent

    ``iri_to_uri()`` call without double-quoting occurring. Employs lazy

    execution.

.. function:: urlencode(query, doseq=0)

A version of Python's urllib.urlencode() function that can operate on unicode

strings. The parameters are first case to UTF-8 encoded strings and then

encoded as per normal.

    A version of Python's urllib.urlencode() function that can operate on

    unicode strings. The parameters are first case to UTF-8 encoded strings

    and then encoded as per normal.

.. function:: cookie_date(epoch_seconds=None)

    Formats the time to ensure compatibility with Netscape's cookie standard.

Accepts a floating point number expressed in seconds since the epoch, in UTC -

such as that outputted by ``time.time()``. If set to ``None``, defaults to the current

time.

    Accepts a floating point number expressed in seconds since the epoch in

    UTC--such as that outputted by ``time.time()``. If set to ``None``,

    defaults to the current time.

    Outputs a string in the format ``Wdy, DD-Mon-YYYY HH:MM:SS GMT``.

    .. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt

Accepts a floating point number expressed in seconds since the epoch, in UTC -

such as that outputted by ``time.time()``. If set to ``None``, defaults to the current

time.

    Accepts a floating point number expressed in seconds since the epoch in

    UTC--such as that outputted by ``time.time()``. If set to ``None``,

    defaults to the current time.

    Outputs a string in the format ``Wdy, DD Mon YYYY HH:MM:SS GMT``.

.. function:: base36_to_int(s)

Converted a base 36 string to an integer

    Converts a base 36 string to an integer.

.. function:: int_to_base36(i)

Converts an integer to a base36 string

    Converts an integer to a base 36 string.

``django.utils.safestring``

===========================

.. class:: SafeUnicode

A unicode subclass that has been specifically marked as "safe" for HTML output

purposes.

    A unicode subclass that has been specifically marked as "safe" for HTML

    output purposes.

.. function:: mark_safe(s)

.. function:: mark_for_escaping(s)

Explicitly mark a string as requiring HTML escaping upon output. Has no effect

on ``SafeData`` subclasses.

    Explicitly mark a string as requiring HTML escaping upon output. Has no

    effect on ``SafeData`` subclasses.

Can be called multiple times on a single string (the resulting escaping is only

applied once).

    Can be called multiple times on a single string (the resulting escaping is

    only applied once).

``django.utils.translation``

============================

.. function:: gettext_noop(message)

Marks strings for translation but doesn't translate them now. This can be used

to store strings in global variables that should stay in the base language

(because they might be used externally) and will be translated later.

    Marks strings for translation but doesn't translate them now. This can be

    used to store strings in global variables that should stay in the base

    language (because they might be used externally) and will be translated

    later.

.. function:: ngettext(singular, plural, number)

    Translates ``singular`` and ``plural`` and returns the appropriate string

based on ``number`` in a UTF-8 bytestring

    based on ``number`` in a UTF-8 bytestring.

.. function:: ungettext(singular, plural, number)

Translates ``singular`` and ``plural`` and returns the appropriate string based

on ``number`` in a unicode string

    Translates ``singular`` and ``plural`` and returns the appropriate string

    based on ``number`` in a unicode string.

.. function:: ngettext_lazy(singular, plural, number)

.. function:: ungettext_lazy(singular, plural, number)

.. function:: deactivate()

De-installs the currently active translation object so that further _ calls will

resolve against the default translation object, again.

    De-installs the currently active translation object so that further _ calls

    will resolve against the default translation object, again.

.. function:: deactivate_all()

    Makes the active translation object a NullTranslations() instance. This is

useful when we want delayed translations to appear as the original string for

some reason.

    useful when we want delayed translations to appear as the original string

    for some reason.

.. function:: get_language()