Fixed #15233 -- reST/Sphinx markup corrections in numerous areas, mostly 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
This commit is contained in:
parent
a40685fdfc
commit
319de16ff0
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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,7 +1761,7 @@ 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
|
||||
|
@ -1769,14 +1771,14 @@ 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
|
||||
|
||||
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``.
|
||||
|
@ -1786,7 +1788,7 @@ 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
|
||||
|
@ -1796,7 +1798,7 @@ 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
|
||||
|
@ -1806,19 +1808,19 @@ 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
|
||||
|
||||
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.
|
||||
|
||||
.. 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
|
||||
|
@ -1829,7 +1831,7 @@ 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
|
||||
|
@ -1839,19 +1841,19 @@ 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
|
||||
|
||||
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.
|
||||
|
||||
.. 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
|
||||
|
|
|
@ -35,8 +35,8 @@ 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.
|
||||
|
@ -47,54 +47,56 @@ arguments to it. The transformation is as follows:
|
|||
|
||||
.. 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``
|
||||
|
||||
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
|
||||
-------
|
||||
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:
|
||||
|
||||
Extra methods that ``SortedDict`` adds 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().
|
||||
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])
|
||||
|
||||
.. 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
|
||||
|
||||
.. 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.
|
||||
|
|
|
@ -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,12 +944,15 @@ 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:**
|
||||
|
||||
* ``template_name``: The full name of a template to use for
|
||||
|
@ -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
|
||||
================================
|
||||
|
||||
|
|
|
@ -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
|
||||
================
|
||||
|
|
|
@ -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,23 +184,24 @@ 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``
|
||||
.. 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."
|
||||
|
||||
``UploadedFile.charset``
|
||||
.. 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.temporary_file_path()``
|
||||
.. attribute:: UploadedFile.temporary_file_path()
|
||||
|
||||
Only files uploaded onto disk will have this method; it returns the full
|
||||
path to the temporary uploaded file.
|
||||
|
||||
|
|
|
@ -765,6 +765,8 @@ following would happen:
|
|||
Utility methods
|
||||
===============
|
||||
|
||||
.. module:: django.core.urlresolvers
|
||||
|
||||
reverse()
|
||||
---------
|
||||
|
||||
|
|
Loading…
Reference in New Issue