Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #15233 -- reST/Sphinx markup corrections in numerous areas, mos…

…tly centering around bad crossref targets. Thanks to Aryeh Leib Taurog for the draft patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15549 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 319de16ff0687072eefe5487b088af9e7ba11fd0 1 parent a40685f
Gabriel Hurley authored
6 docs/ref/contrib/admin/index.txt
View
@@ -1110,6 +1110,8 @@ information.
============================
.. 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::
@@ -1134,8 +1136,8 @@ information.
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.
20 docs/ref/contrib/formtools/form-preview.txt
View
@@ -2,7 +2,7 @@
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.
@@ -26,7 +26,7 @@ application takes care of the following workflow:
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
@@ -50,8 +50,8 @@ How to use ``FormPreview``
: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
@@ -70,7 +70,7 @@ How to use ``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
@@ -89,11 +89,11 @@ How to use ``FormPreview``
.. 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
@@ -102,8 +102,8 @@ anywhere in your codebase.
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.
3  docs/ref/forms/widgets.txt
View
@@ -160,6 +160,8 @@ commonly used groups of widgets:
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.
@@ -180,6 +182,7 @@ commonly used groups of widgets:
Specifying widgets
------------------
+.. currentmodule:: django.forms
.. attribute:: Form.widget
84 docs/ref/models/querysets.txt
View
@@ -1749,6 +1749,8 @@ SQL equivalents::
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
@@ -1759,100 +1761,100 @@ Avg
.. class:: Avg(field)
-Returns the mean value of the given field.
+ Returns the mean value of the given field.
- * Default alias: ``<field>__avg``
- * Return type: float
+ * Default alias: ``<field>__avg``
+ * Return type: float
Count
~~~~~
.. class:: Count(field, distinct=False)
-Returns the number of objects that are related through the provided field.
+ Returns the number of objects that are related through the provided field.
- * Default alias: ``<field>__count``
- * Return type: integer
+ * Default alias: ``<field>__count``
+ * Return type: integer
-Has one optional argument:
+ Has one optional argument:
-.. attribute:: distinct
+ .. attribute:: distinct
- If distinct=True, the count will only include unique instances. This has
- the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
+ If distinct=True, the count will only include unique instances. This has
+ the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
Max
~~~
.. class:: Max(field)
-Returns the maximum value of the given field.
+ Returns the maximum value of the given field.
- * Default alias: ``<field>__max``
- * Return type: same as input field
+ * Default alias: ``<field>__max``
+ * Return type: same as input field
Min
~~~
.. class:: Min(field)
-Returns the minimum value of the given field.
+ Returns the minimum value of the given field.
- * Default alias: ``<field>__min``
- * Return type: same as input field
+ * Default alias: ``<field>__min``
+ * Return type: same as input field
StdDev
~~~~~~
.. class:: StdDev(field, sample=False)
-Returns the standard deviation of the data in the provided field.
+ Returns the standard deviation of the data in the provided field.
- * Default alias: ``<field>__stddev``
- * Return type: float
+ * Default alias: ``<field>__stddev``
+ * Return type: float
-Has one optional argument:
+ Has one optional argument:
-.. attribute:: sample
+ .. attribute:: sample
- By default, ``StdDev`` returns the population standard deviation. However,
- if ``sample=True``, the return value will be the sample standard deviation.
+ By default, ``StdDev`` returns the population standard deviation. However,
+ if ``sample=True``, the return value will be the sample standard deviation.
-.. admonition:: SQLite
+ .. admonition:: SQLite
- SQLite doesn't provide ``StdDev`` out of the box. An implementation is
- available as an extension module for SQLite. Consult the SQlite
- documentation for instructions on obtaining and installing this extension.
+ SQLite doesn't provide ``StdDev`` out of the box. An implementation is
+ available as an extension module for SQLite. Consult the SQlite
+ documentation for instructions on obtaining and installing this extension.
Sum
~~~
.. class:: Sum(field)
-Computes the sum of all values of the given field.
+ Computes the sum of all values of the given field.
- * Default alias: ``<field>__sum``
- * Return type: same as input field
+ * Default alias: ``<field>__sum``
+ * Return type: same as input field
Variance
~~~~~~~~
.. class:: Variance(field, sample=False)
-Returns the variance of the data in the provided field.
+ Returns the variance of the data in the provided field.
- * Default alias: ``<field>__variance``
- * Return type: float
+ * Default alias: ``<field>__variance``
+ * Return type: float
-Has one optional argument:
+ Has one optional argument:
-.. attribute:: sample
+ .. attribute:: sample
- By default, ``Variance`` returns the population variance. However,
- if ``sample=True``, the return value will be the sample variance.
+ By default, ``Variance`` returns the population variance. However,
+ if ``sample=True``, the return value will be the sample variance.
-.. admonition:: SQLite
+ .. admonition:: SQLite
- SQLite doesn't provide ``Variance`` out of the box. An implementation is
- available as an extension module for SQLite. Consult the SQlite
- documentation for instructions on obtaining and installing this extension.
+ SQLite doesn't provide ``Variance`` out of the box. An implementation is
+ available as an extension module for SQLite. Consult the SQlite
+ documentation for instructions on obtaining and installing this extension.
356 docs/ref/utils.txt
View
@@ -35,66 +35,68 @@ to distinguish caches by the ``Accept-language`` header.
.. function:: patch_cache_control(response, **kwargs)
-This function patches the ``Cache-Control`` header by adding all keyword
-arguments to it. The transformation is as follows:
+ This function patches the ``Cache-Control`` header by adding all keyword
+ arguments to it. The transformation is as follows:
- * All keyword parameter names are turned to lowercase, and underscores
- are converted to hyphens.
- * If the value of a parameter is ``True`` (exactly ``True``, not just a
- true value), only the parameter name is added to the header.
- * All other parameters are added with their value, after applying
- ``str()`` to it.
+ * All keyword parameter names are turned to lowercase, and underscores
+ are converted to hyphens.
+ * If the value of a parameter is ``True`` (exactly ``True``, not just a
+ true value), only the parameter name is added to the header.
+ * All other parameters are added with their value, after applying
+ ``str()`` to it.
.. 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)
-Adds some useful headers to the given ``HttpResponse`` object:
+ Adds some useful headers to the given ``HttpResponse`` object:
- * ``ETag``
- * ``Last-Modified``
- * ``Expires``
- * ``Cache-Control``
+ * ``ETag``
+ * ``Last-Modified``
+ * ``Expires``
+ * ``Cache-Control``
-Each header is only added if it isn't already set.
+ 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)
-Adds headers to a response to indicate that a page should never be cached.
+ Adds headers to a response to indicate that a page should never be cached.
.. 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.
+ 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.
.. 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``.
+ If there is no headerlist stored, the page needs to be rebuilt, so this
+ function returns ``None``.
.. function:: learn_cache_key(request, response, cache_timeout=None, key_prefix=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.
+ 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.
-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
==========
@@ -102,23 +104,23 @@ 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)
+ .. method:: insert(index, key, value)
-Inserts the key, value pair before the item with the given index.
+ Inserts the key, value pair before the item with the given index.
-.. method:: value_for_index(index)
+ .. method:: value_for_index(index)
-Returns the value of the item at the given zero-based index.
+ 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::
@@ -138,48 +140,52 @@ results. Instead do::
.. 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)
-Determine if the object instance is of a protected type.
+ Determine if the object instance is of a protected type.
-Objects of protected types are preserved as-is when passed to
-``force_unicode(strings_only=True)``.
+ Objects of protected types are preserved as-is when passed to
+ ``force_unicode(strings_only=True)``.
.. 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
+ .. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt
-Returns an ASCII string containing the encoded result.
+ Returns an ASCII string containing the encoded result.
``django.utils.feedgenerator``
==============================
@@ -213,65 +219,64 @@ http://diveintomark.org/archives/2004/02/04/incompatible-rss
.. function:: get_tag_uri(url, date)
-Creates a TagURI.
+ Creates a TagURI.
-See http://diveintomark.org/archives/2004/05/28/howto-atom-id
+ See http://diveintomark.org/archives/2004/05/28/howto-atom-id
SyndicationFeed
---------------
.. class:: SyndicationFeed
-Base class for all syndication feeds. Subclasses should provide write().
-
-Methods
-~~~~~~~
+ Base class for all syndication feeds. Subclasses should provide write().
-.. 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])
+ .. 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``
-objects except ``pubdate``, which is a ``datetime.datetime`` object, and
-``enclosure``, which is an instance of the ``Enclosure`` class.
+ Adds an item to the feed. All args are expected to be Python ``unicode``
+ objects except ``pubdate``, which is a ``datetime.datetime`` object, and
+ ``enclosure``, which is an instance of the ``Enclosure`` class.
-.. method:: num_items()
+ .. method:: num_items()
-.. method:: root_attributes()
+ .. 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)
+ .. 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)
+ .. 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:: add_item_elements(handler, item)
-Add elements on each item (i.e. item/entry) element.
+ Add elements on each item (i.e. item/entry) element.
-.. method:: write(outfile, encoding)
+ .. 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:: writeString(encoding)
-Returns the feed in the given encoding as a string.
+ Returns the feed in the given encoding as a string.
-.. method:: latest_post_date()
+ .. 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
---------
.. class:: Enclosure
-Represents an RSS enclosure
+ Represents an RSS enclosure
RssFeed
-------
@@ -283,14 +288,14 @@ Rss201rev2Feed
.. class:: Rss201rev2Feed(RssFeed)
-Spec: http://blogs.law.harvard.edu/tech/rss
+ Spec: http://blogs.law.harvard.edu/tech/rss
Atom1Feed
---------
.. class:: Atom1Feed(SyndicationFeed)
-Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
+ Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
``django.utils.http``
=====================
@@ -300,54 +305,56 @@ Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
.. 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.
+ 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``.
+ Outputs a string in the format ``Wdy, DD-Mon-YYYY HH:MM:SS GMT``.
.. function:: http_date(epoch_seconds=None)
-Formats the time to match the RFC 1123 date format as specified by HTTP
-`RFC 2616`_ section 3.3.1.
+ Formats the time to match the RFC 1123 date format as specified by HTTP
+ `RFC 2616`_ section 3.3.1.
-.. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt
+ .. _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``.
+ 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``
===========================
@@ -363,28 +370,28 @@ appropriate entities.
.. class:: SafeString
-A string subclass that has been specifically marked as "safe" (requires no
-further escaping) for HTML output purposes.
+ A string subclass that has been specifically marked as "safe" (requires no
+ further escaping) for HTML output purposes.
.. 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)
-Explicitly mark a string as safe for (HTML) output purposes. The returned
-object can be used everywhere a string or unicode object is appropriate.
+ Explicitly mark a string as safe for (HTML) output purposes. The returned
+ object can be used everywhere a string or unicode object is appropriate.
-Can be called multiple times on a single string.
+ Can be called multiple times on a single string.
.. 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``
============================
@@ -397,97 +404,98 @@ For a complete discussion on the usage of the following see the
.. function:: gettext(message)
-Translates ``message`` and returns it in a UTF-8 bytestring
+ Translates ``message`` and returns it in a UTF-8 bytestring
.. function:: ugettext(message)
-Translates ``message`` and returns it in a unicode string
+ Translates ``message`` and returns it in a unicode string
.. function:: gettext_lazy(message)
.. function:: ugettext_lazy(message)
-Same as the non-lazy versions above, but using lazy execution.
+ Same as the non-lazy versions above, but using lazy execution.
-See :ref:`lazy translations documentation <lazy-translations>`.
+ See :ref:`lazy translations documentation <lazy-translations>`.
.. 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
+ Translates ``singular`` and ``plural`` and returns the appropriate string
+ 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)
-Same as the non-lazy versions above, but using lazy execution.
+ Same as the non-lazy versions above, but using lazy execution.
-See :ref:`lazy translations documentation <lazy-translations>`.
+ See :ref:`lazy translations documentation <lazy-translations>`.
.. function:: string_concat(*strings)
-Lazy variant of string concatenation, needed for translations that are
-constructed from multiple parts.
+ Lazy variant of string concatenation, needed for translations that are
+ constructed from multiple parts.
.. function:: activate(language)
-Fetches the translation object for a given tuple of application name and
-language and installs it as the current translation object for the current
-thread.
+ Fetches the translation object for a given tuple of application name and
+ language and installs it as the current translation object for the current
+ thread.
.. 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.
+ 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.
.. function:: get_language()
-Returns the currently selected language code.
+ Returns the currently selected language code.
.. function:: get_language_bidi()
-Returns selected language's BiDi layout:
+ Returns selected language's BiDi layout:
- * ``False`` = left-to-right layout
- * ``True`` = right-to-left layout
+ * ``False`` = left-to-right layout
+ * ``True`` = right-to-left layout
.. function:: get_date_formats()
-Checks whether translation files provide a translation for some technical
-message ID to store date and time formats. If it doesn't contain one, the
-formats provided in the settings will be used.
+ Checks whether translation files provide a translation for some technical
+ message ID to store date and time formats. If it doesn't contain one, the
+ formats provided in the settings will be used.
.. function:: get_language_from_request(request)
-Analyzes the request to find what language the user wants the system to show.
-Only languages listed in settings.LANGUAGES are taken into account. If the user
-requests a sublanguage where we have a main language, we send out the main
-language.
+ Analyzes the request to find what language the user wants the system to show.
+ Only languages listed in settings.LANGUAGES are taken into account. If the user
+ requests a sublanguage where we have a main language, we send out the main
+ language.
.. function:: to_locale(language)
-Turns a language name (en-us) into a locale name (en_US).
+ Turns a language name (en-us) into a locale name (en_US).
.. function:: templatize(src)
-Turns a Django template into something that is understood by xgettext. It does
-so by translating the Django translation tags into standard gettext function
-invocations.
+ Turns a Django template into something that is understood by xgettext. It does
+ so by translating the Django translation tags into standard gettext function
+ invocations.
``django.utils.tzinfo``
=======================
@@ -497,8 +505,8 @@ invocations.
.. class:: FixedOffset
-Fixed offset in minutes east from UTC.
+ Fixed offset in minutes east from UTC.
.. class:: LocalTimezone
-Proxy timezone information from time module.
+ Proxy timezone information from time module.
46 docs/topics/auth.txt
View
@@ -615,6 +615,8 @@ Django provides two functions in :mod:`django.contrib.auth`:
Manually checking a user's password
-----------------------------------
+.. currentmodule:: django.contrib.auth.models
+
.. function:: check_password()
If you'd like to manually authenticate a user by comparing a plain-text
@@ -627,6 +629,8 @@ Manually checking a user's password
How to log a user out
---------------------
+.. currentmodule:: django.contrib.auth
+
.. function:: logout()
To log out a user who has been logged in via
@@ -871,11 +875,13 @@ The login_required decorator
Other built-in views
--------------------
+.. module:: django.contrib.auth.views
+
In addition to the :func:`~views.login` view, the authentication system
includes a few other useful built-in views located in
:mod:`django.contrib.auth.views`:
-.. function:: views.logout(request, [next_page, template_name, redirect_field_name])
+.. function:: logout(request, [next_page, template_name, redirect_field_name])
Logs a user out.
@@ -895,7 +901,7 @@ includes a few other useful built-in views located in
* ``title``: The string "Logged out", localized.
-.. function:: views.logout_then_login(request[, login_url])
+.. function:: logout_then_login(request[, login_url])
Logs a user out, then redirects to the login page.
@@ -904,7 +910,7 @@ includes a few other useful built-in views located in
* ``login_url``: The URL of the login page to redirect to. This will
default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
-.. function:: views.password_change(request[, template_name, post_change_redirect, password_change_form])
+.. function:: password_change(request[, template_name, post_change_redirect, password_change_form])
Allows a user to change their password.
@@ -928,7 +934,7 @@ includes a few other useful built-in views located in
* ``form``: The password change form.
-.. function:: views.password_change_done(request[, template_name])
+.. function:: password_change_done(request[, template_name])
The page shown after a user has changed their password.
@@ -938,11 +944,14 @@ includes a few other useful built-in views located in
default to :file:`registration/password_change_done.html` if not
supplied.
-.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email])
+.. function:: password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email])
Allows a user to reset their password by generating a one-time use link
that can be used to reset the password, and sending that link to the
user's registered e-mail address.
+
+ .. versionchanged:: 1.3
+ The ``from_email`` argument was added.
**Optional arguments:**
@@ -964,8 +973,6 @@ includes a few other useful built-in views located in
* ``post_reset_redirect``: The URL to redirect to after a successful
password change.
- .. versionchanged:: 1.3
-
* ``from_email``: A valid e-mail address. By default Django uses
the :setting:`DEFAULT_FROM_EMAIL`.
@@ -973,7 +980,7 @@ includes a few other useful built-in views located in
* ``form``: The form for resetting the user's password.
-.. function:: views.password_reset_done(request[, template_name])
+.. function:: password_reset_done(request[, template_name])
The page shown after a user has reset their password.
@@ -983,7 +990,7 @@ includes a few other useful built-in views located in
default to :file:`registration/password_reset_done.html` if not
supplied.
-.. function:: views.redirect_to_login(next[, login_url, redirect_field_name])
+.. function:: redirect_to_login(next[, login_url, redirect_field_name])
Redirects to the login page, and then back to another URL after a
successful login.
@@ -1001,6 +1008,7 @@ includes a few other useful built-in views located in
URL to redirect to after log out. Overrides ``next`` if the given
``GET`` parameter is passed.
+
.. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect])
Presents a form for entering a new password.
@@ -1073,7 +1081,7 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
Limiting access to logged-in users that pass a test
---------------------------------------------------
-.. currentmodule:: django.contrib.auth
+.. currentmodule:: django.contrib.auth.decorators
To limit access based on certain permissions or some other test, you'd do
essentially the same thing as described in the previous section.
@@ -1088,7 +1096,7 @@ checks to make sure the user is logged in and has the permission
return HttpResponse("You can't vote in this poll.")
# ...
-.. function:: decorators.user_passes_test()
+.. function:: user_passes_test()
As a shortcut, you can use the convenient ``user_passes_test`` decorator::
@@ -1126,7 +1134,7 @@ checks to make sure the user is logged in and has the permission
The permission_required decorator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. function:: decorators.permission_required()
+.. function:: permission_required()
It's a relatively common task to check whether a user has a particular
permission. For that reason, Django provides a shortcut for that case: the
@@ -1155,6 +1163,8 @@ The permission_required decorator
As in the :func:`~decorators.login_required` decorator, ``login_url``
defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
+.. currentmodule:: django.contrib.auth
+
Limiting access to generic views
--------------------------------
@@ -1249,7 +1259,9 @@ closing tasks.)
API reference
-------------
-.. class:: models.Permission
+.. currentmodule:: django.contrib.auth.models
+
+.. class:: Permission
Just like users, permissions are implemented in a Django model that lives
in `django/contrib/auth/models.py`_.
@@ -1262,16 +1274,16 @@ Fields
:class:`~django.contrib.auth.models.Permission` objects have the following
fields:
-.. attribute:: models.Permission.name
+.. attribute:: Permission.name
Required. 50 characters or fewer. Example: ``'Can vote'``.
-.. attribute:: models.Permission.content_type
+.. attribute:: Permission.content_type
Required. A reference to the ``django_content_type`` database table, which
contains a record for each installed Django model.
-.. attribute:: models.Permission.codename
+.. attribute:: Permission.codename
Required. 100 characters or fewer. Example: ``'can_vote'``.
@@ -1281,6 +1293,8 @@ Methods
:class:`~django.contrib.auth.models.Permission` objects have the standard
data-access methods like any other :doc:`Django model </ref/models/instances>`.
+.. currentmodule:: django.contrib.auth
+
Authentication data in templates
================================
2  docs/topics/http/decorators.txt
View
@@ -45,7 +45,7 @@ These decorators can be used to generate ``ETag`` and ``Last-Modified``
headers; see
:doc:`conditional view processing </topics/conditional-view-processing>`.
-.. currentmodule:: django.views.decorators.http
+.. currentmodule:: django.views.decorators.gzip
GZip compression
================
56 docs/topics/http/file-uploads.txt
View
@@ -2,7 +2,7 @@
File Uploads
============
-.. currentmodule:: django.core.files
+.. currentmodule:: django.core.files.uploadedfile
When Django handles a file upload, the file data ends up placed in
:attr:`request.FILES <django.http.HttpRequest.FILES>` (for more on the
@@ -59,33 +59,40 @@ into the form's constructor; this is how file data gets bound into a form.
Handling uploaded files
-----------------------
-The final piece of the puzzle is handling the actual file data from
-:attr:`request.FILES <django.http.HttpRequest.FILES>`. Each entry in this
-dictionary is an ``UploadedFile`` object -- a simple wrapper around an uploaded
-file. You'll usually use one of these methods to access the uploaded content:
+.. class:: UploadedFile
+
+ The final piece of the puzzle is handling the actual file data from
+ :attr:`request.FILES <django.http.HttpRequest.FILES>`. Each entry in this
+ dictionary is an ``UploadedFile`` object -- a simple wrapper around an uploaded
+ file. You'll usually use one of these methods to access the uploaded content:
+
+ .. method:: read()
- ``UploadedFile.read()``
Read the entire uploaded data from the file. Be careful with this
method: if the uploaded file is huge it can overwhelm your system if you
try to read it into memory. You'll probably want to use ``chunks()``
instead; see below.
- ``UploadedFile.multiple_chunks()``
+ .. method:: multiple_chunks()
+
Returns ``True`` if the uploaded file is big enough to require
reading in multiple chunks. By default this will be any file
larger than 2.5 megabytes, but that's configurable; see below.
- ``UploadedFile.chunks()``
+ .. method:: chunks()
+
A generator returning chunks of the file. If ``multiple_chunks()`` is
``True``, you should use this method in a loop instead of ``read()``.
In practice, it's often easiest simply to use ``chunks()`` all the time;
see the example below.
- ``UploadedFile.name``
+ .. attribute:: name
+
The name of the uploaded file (e.g. ``my_file.txt``).
- ``UploadedFile.size``
+ .. attribute:: size
+
The size, in bytes, of the uploaded file.
There are a few other methods and attributes available on ``UploadedFile``
@@ -177,25 +184,26 @@ Three settings control Django's file upload behavior:
``UploadedFile`` objects
========================
-.. class:: UploadedFile
-
In addition to those inherited from :class:`File`, all ``UploadedFile`` objects
define the following methods/attributes:
- ``UploadedFile.content_type``
- The content-type header uploaded with the file (e.g. ``text/plain`` or
- ``application/pdf``). Like any data supplied by the user, you shouldn't
- trust that the uploaded file is actually this type. You'll still need to
- validate that the file contains the content that the content-type header
- claims -- "trust but verify."
+.. attribute:: UploadedFile.content_type
+
+ The content-type header uploaded with the file (e.g. ``text/plain`` or
+ ``application/pdf``). Like any data supplied by the user, you shouldn't
+ trust that the uploaded file is actually this type. You'll still need to
+ validate that the file contains the content that the content-type header
+ claims -- "trust but verify."
+
+.. attribute:: UploadedFile.charset
+
+ For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
+ by the browser. Again, "trust but verify" is the best policy here.
- ``UploadedFile.charset``
- For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
- by the browser. Again, "trust but verify" is the best policy here.
+.. attribute:: UploadedFile.temporary_file_path()
- ``UploadedFile.temporary_file_path()``
- Only files uploaded onto disk will have this method; it returns the full
- path to the temporary uploaded file.
+ Only files uploaded onto disk will have this method; it returns the full
+ path to the temporary uploaded file.
.. note::
2  docs/topics/http/urls.txt
View
@@ -765,6 +765,8 @@ following would happen:
Utility methods
===============
+.. module:: django.core.urlresolvers
+
reverse()
---------
Please sign in to comment.
Something went wrong with that request. Please try again.