p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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:
Gabriel Hurley 2011-02-16 01:56:53 +00:00
parent a40685fdfc
commit 319de16ff0
9 changed files with 307 additions and 268 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/ref/contrib/admin/index.txt
View File

@ -1110,6 +1110,8 @@ information.
============================ ============================
.. class:: InlineModelAdmin .. class:: InlineModelAdmin
.. class:: TabularInline
.. class:: StackedInline
The admin interface has the ability to edit models on the same page as a 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:: 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: Django provides two subclasses of ``InlineModelAdmin`` and they are:
* ``TabularInline`` * :class:`~django.contrib.admin.TabularInline`
* ``StackedInline`` * :class:`~django.contrib.admin.StackedInline`
The difference between these two is merely the template used to render The difference between these two is merely the template used to render
them. them.

20
docs/ref/contrib/formtools/form-preview.txt
View File

@ -2,7 +2,7 @@
Form preview Form preview
============ ============
.. module:: django.contrib.formtools .. module:: django.contrib.formtools.preview
:synopsis: Displays an HTML form, forces a preview, then does something :synopsis: Displays an HTML form, forces a preview, then does something
with the submission. 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. b. If it's not valid, redisplays the form with error messages.
3. When the "confirmation" form is submitted from the preview page, calls 3. When the "confirmation" form is submitted from the preview page, calls
a hook that you define -- a 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. passed the valid data.
The framework enforces the required preview by passing a shared-secret hash to 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 :file:`django/contrib/formtools/templates` directory, and add that
directory to your :setting:`TEMPLATE_DIRS` setting. directory to your :setting:`TEMPLATE_DIRS` setting.
2. Create a :class:`~django.contrib.formtools.FormPreview` subclass that 2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that
overrides the :meth:`~django.contrib.formtools.FormPreview.done()` overrides the :meth:`~django.contrib.formtools.preview.FormPreview.done()`
method:: method::
from django.contrib.formtools.preview import FormPreview from django.contrib.formtools.preview import FormPreview
@ -70,7 +70,7 @@ How to use ``FormPreview``
is the end result of the form being submitted. is the end result of the form being submitted.
3. Change your URLconf to point to an instance of your 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.preview import SomeModelFormPreview
from myapp.forms import SomeModelForm from myapp.forms import SomeModelForm
@ -89,11 +89,11 @@ How to use ``FormPreview``
.. class:: 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. 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 ``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. anywhere in your codebase.
``FormPreview`` templates ``FormPreview`` templates
@ -102,8 +102,8 @@ anywhere in your codebase.
By default, the form is rendered via the template :file:`formtools/form.html`, 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`. 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 These values can be overridden for a particular form preview by setting
:attr:`~django.contrib.formtools.FormPreview.preview_template` and :attr:`~django.contrib.formtools.preview.FormPreview.preview_template` and
:attr:`~django.contrib.formtools.FormPreview.form_template` attributes on the :attr:`~django.contrib.formtools.preview.FormPreview.form_template` attributes on the
FormPreview subclass. See :file:`django/contrib/formtools/templates` for the FormPreview subclass. See :file:`django/contrib/formtools/templates` for the
default templates. default templates.

3
docs/ref/forms/widgets.txt
View File

@ -160,6 +160,8 @@ commonly used groups of widgets:
Takes two optional arguments, ``date_format`` and ``time_format``, which Takes two optional arguments, ``date_format`` and ``time_format``, which
work just like the ``format`` argument for ``DateInput`` and ``TimeInput``. work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
.. currentmodule:: django.forms.extras.widgets
.. class:: SelectDateWidget .. class:: SelectDateWidget
Wrapper around three select widgets: one each for month, day, and year. Wrapper around three select widgets: one each for month, day, and year.
@ -180,6 +182,7 @@ commonly used groups of widgets:
Specifying widgets Specifying widgets
------------------ ------------------
.. currentmodule:: django.forms
.. attribute:: Form.widget .. attribute:: Form.widget

84
docs/ref/models/querysets.txt
View File

@ -1749,6 +1749,8 @@ SQL equivalents::
Aggregation functions Aggregation functions
--------------------- ---------------------
.. currentmodule:: django.db.models
Django provides the following aggregation functions in the Django provides the following aggregation functions in the
``django.db.models`` module. For details on how to use these ``django.db.models`` module. For details on how to use these
aggregate functions, see aggregate functions, see
@ -1759,100 +1761,100 @@ Avg
.. class:: Avg(field) .. class:: Avg(field)
Returns the mean value of the given field. Returns the mean value of the given field.
* Default alias: ``<field>__avg`` * Default alias: ``<field>__avg``
* Return type: float * Return type: float
Count Count
~~~~~ ~~~~~
.. class:: Count(field, distinct=False) .. 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`` * Default alias: ``<field>__count``
* Return type: integer * 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 If distinct=True, the count will only include unique instances. This has
the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``. the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
Max Max
~~~ ~~~
.. class:: Max(field) .. class:: Max(field)
Returns the maximum value of the given field. Returns the maximum value of the given field.
* Default alias: ``<field>__max`` * Default alias: ``<field>__max``
* Return type: same as input field * Return type: same as input field
Min Min
~~~ ~~~
.. class:: Min(field) .. class:: Min(field)
Returns the minimum value of the given field. Returns the minimum value of the given field.
* Default alias: ``<field>__min`` * Default alias: ``<field>__min``
* Return type: same as input field * Return type: same as input field
StdDev StdDev
~~~~~~ ~~~~~~
.. class:: StdDev(field, sample=False) .. 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`` * Default alias: ``<field>__stddev``
* Return type: float * Return type: float
Has one optional argument: Has one optional argument:
.. attribute:: sample .. attribute:: sample
By default, ``StdDev`` returns the population standard deviation. However, By default, ``StdDev`` returns the population standard deviation. However,
if ``sample=True``, the return value will be the sample standard deviation. 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 SQLite doesn't provide ``StdDev`` out of the box. An implementation is
available as an extension module for SQLite. Consult the SQlite available as an extension module for SQLite. Consult the SQlite
documentation for instructions on obtaining and installing this extension. documentation for instructions on obtaining and installing this extension.
Sum Sum
~~~ ~~~
.. class:: Sum(field) .. 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`` * Default alias: ``<field>__sum``
* Return type: same as input field * Return type: same as input field
Variance Variance
~~~~~~~~ ~~~~~~~~
.. class:: Variance(field, sample=False) .. 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`` * Default alias: ``<field>__variance``
* Return type: float * Return type: float
Has one optional argument: Has one optional argument:
.. attribute:: sample .. attribute:: sample
By default, ``Variance`` returns the population variance. However, By default, ``Variance`` returns the population variance. However,
if ``sample=True``, the return value will be the sample variance. 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 SQLite doesn't provide ``Variance`` out of the box. An implementation is
available as an extension module for SQLite. Consult the SQlite available as an extension module for SQLite. Consult the SQlite
documentation for instructions on obtaining and installing this extension. documentation for instructions on obtaining and installing this extension.

356
docs/ref/utils.txt
View File

@ -35,66 +35,68 @@ to distinguish caches by the ``Accept-language`` header.
.. function:: patch_cache_control(response, **kwargs) .. function:: patch_cache_control(response, **kwargs)
This function patches the ``Cache-Control`` header by adding all keyword This function patches the ``Cache-Control`` header by adding all keyword
arguments to it. The transformation is as follows: arguments to it. The transformation is as follows:
* All keyword parameter names are turned to lowercase, and underscores * All keyword parameter names are turned to lowercase, and underscores
are converted to hyphens. are converted to hyphens.
* If the value of a parameter is ``True`` (exactly ``True``, not just a * If the value of a parameter is ``True`` (exactly ``True``, not just a
true value), only the parameter name is added to the header. true value), only the parameter name is added to the header.
* All other parameters are added with their value, after applying * All other parameters are added with their value, after applying
``str()`` to it. ``str()`` to it.
.. function:: get_max_age(response) .. function:: get_max_age(response)
Returns the max-age from the response Cache-Control header as an integer (or Returns the max-age from the response Cache-Control header as an integer
``None`` if it wasn't found or wasn't an integer). (or ``None`` if it wasn't found or wasn't an integer).
.. function:: patch_response_headers(response, cache_timeout=None) .. 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`` * ``ETag``
* ``Last-Modified`` * ``Last-Modified``
* ``Expires`` * ``Expires``
* ``Cache-Control`` * ``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 ``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting
used by default. is used by default.
.. function:: add_never_cache_headers(response) .. 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) .. function:: patch_vary_headers(response, newheaders)
Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object. Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object.
``newheaders`` is a list of header names that should be in ``Vary``. Existing ``newheaders`` is a list of header names that should be in ``Vary``.
headers in ``Vary`` aren't removed. Existing headers in ``Vary`` aren't removed.
.. function:: get_cache_key(request, key_prefix=None) .. function:: get_cache_key(request, key_prefix=None)
Returns a cache key based on the request path. It can be used in the request Returns a cache key based on the request path. It can be used in the
phase because it pulls the list of headers to take into account from the request phase because it pulls the list of headers to take into account
global path registry and uses those to build a cache key to check against. 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 If there is no headerlist stored, the page needs to be rebuilt, so this
function returns ``None``. function returns ``None``.
.. function:: learn_cache_key(request, response, cache_timeout=None, key_prefix=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 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 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 later access to that path will know what headers to take into account
building the response object itself. The headers are named in the ``Vary`` without building the response object itself. The headers are named in
header of the response, but we want to prevent response generation. 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 The list of headers to use for cache key generation is stored in the same
as the pages themselves. If the cache ages some data out of the cache, this cache as the pages themselves. If the cache ages some data out of the
just means that we have to build the response once to get at the Vary header cache, this just means that we have to build the response once to get at
and so at the list of headers to use for the cache key. the Vary header and so at the list of headers to use for the cache key.
SortedDict SortedDict
========== ==========
@ -102,23 +104,23 @@ SortedDict
.. module:: django.utils.datastructures .. module:: django.utils.datastructures
:synopsis: A dictionary that keeps its keys in the order in which they're inserted. :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 a new SortedDict
-------------------------
Creating new SortedDict
-----------------------
Creating a new ``SortedDict`` must be done in a way where ordering is Creating a new ``SortedDict`` must be done in a way where ordering is
guaranteed. For example:: guaranteed. For example::
@ -138,48 +140,52 @@ results. Instead do::
.. class:: StrAndUnicode .. class:: StrAndUnicode
A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8 bytestring. A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8
Useful as a mix-in. bytestring. Useful as a mix-in.
.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict') .. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
Returns a ``unicode`` object representing ``s``. Treats bytestrings using the Returns a ``unicode`` object representing ``s``. Treats bytestrings using
'encoding' codec. 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:: 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 Objects of protected types are preserved as-is when passed to
``force_unicode(strings_only=True)``. ``force_unicode(strings_only=True)``.
.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict') .. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
Similar to ``smart_unicode``, except that lazy instances are resolved to strings, Similar to ``smart_unicode``, except that lazy instances are resolved to
rather than kept as lazy objects. 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') .. 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) .. function:: iri_to_uri(iri)
Convert an Internationalized Resource Identifier (IRI) portion to a URI portion Convert an Internationalized Resource Identifier (IRI) portion to a URI
that is suitable for inclusion in a URL. portion that is suitable for inclusion in a URL.
This is the algorithm from section 3.1 of `RFC 3987`_. However, since we are This is the algorithm from section 3.1 of `RFC 3987`_. However, since we
assuming input is either UTF-8 or unicode already, we can simplify things a are assuming input is either UTF-8 or unicode already, we can simplify
little from the full method. 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`` ``django.utils.feedgenerator``
============================== ==============================
@ -213,65 +219,64 @@ http://diveintomark.org/archives/2004/02/04/incompatible-rss
.. function:: get_tag_uri(url, date) .. 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 SyndicationFeed
--------------- ---------------
.. class:: 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`` .. method:: num_items()
objects except ``pubdate``, which is a ``datetime.datetime`` object, and
``enclosure``, which is an instance of the ``Enclosure`` class.
.. 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. .. method:: add_root_elements(handler)
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)
.. 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 .. method:: writeString(encoding)
object. Subclasses should override this.
.. 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 Enclosure
--------- ---------
.. class:: Enclosure .. class:: Enclosure
Represents an RSS enclosure Represents an RSS enclosure
RssFeed RssFeed
------- -------
@ -283,14 +288,14 @@ Rss201rev2Feed
.. class:: Rss201rev2Feed(RssFeed) .. class:: Rss201rev2Feed(RssFeed)
Spec: http://blogs.law.harvard.edu/tech/rss Spec: http://blogs.law.harvard.edu/tech/rss
Atom1Feed Atom1Feed
--------- ---------
.. class:: Atom1Feed(SyndicationFeed) .. 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`` ``django.utils.http``
===================== =====================
@ -300,54 +305,56 @@ Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
.. function:: urlquote(url, safe='/') .. function:: urlquote(url, safe='/')
A version of Python's ``urllib.quote()`` function that can operate on unicode A version of Python's ``urllib.quote()`` function that can operate on
strings. The url is first UTF-8 encoded before quoting. The returned string unicode strings. The url is first UTF-8 encoded before quoting. The
can safely be used as part of an argument to a subsequent ``iri_to_uri()`` returned string can safely be used as part of an argument to a subsequent
call without double-quoting occurring. Employs lazy execution. ``iri_to_uri()`` call without double-quoting occurring. Employs lazy
execution.
.. function:: urlquote_plus(url, safe='') .. function:: urlquote_plus(url, safe='')
A version of Python's urllib.quote_plus() function that can operate on unicode A version of Python's urllib.quote_plus() function that can operate on
strings. The url is first UTF-8 encoded before quoting. The returned string can unicode strings. The url is first UTF-8 encoded before quoting. The
safely be used as part of an argument to a subsequent iri_to_uri() call without returned string can safely be used as part of an argument to a subsequent
double-quoting occurring. Employs lazy execution. ``iri_to_uri()`` call without double-quoting occurring. Employs lazy
execution.
.. function:: urlencode(query, doseq=0) .. function:: urlencode(query, doseq=0)
A version of Python's urllib.urlencode() function that can operate on unicode A version of Python's urllib.urlencode() function that can operate on
strings. The parameters are first case to UTF-8 encoded strings and then unicode strings. The parameters are first case to UTF-8 encoded strings
encoded as per normal. and then encoded as per normal.
.. function:: cookie_date(epoch_seconds=None) .. 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 - Accepts a floating point number expressed in seconds since the epoch in
such as that outputted by ``time.time()``. If set to ``None``, defaults to the current UTC--such as that outputted by ``time.time()``. If set to ``None``,
time. 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) .. function:: http_date(epoch_seconds=None)
Formats the time to match the RFC 1123 date format as specified by HTTP Formats the time to match the RFC 1123 date format as specified by HTTP
`RFC 2616`_ section 3.3.1. `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 - Accepts a floating point number expressed in seconds since the epoch in
such as that outputted by ``time.time()``. If set to ``None``, defaults to the current UTC--such as that outputted by ``time.time()``. If set to ``None``,
time. 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) .. 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) .. function:: int_to_base36(i)
Converts an integer to a base36 string Converts an integer to a base 36 string.
``django.utils.safestring`` ``django.utils.safestring``
=========================== ===========================
@ -363,28 +370,28 @@ appropriate entities.
.. class:: SafeString .. class:: SafeString
A string subclass that has been specifically marked as "safe" (requires no A string subclass that has been specifically marked as "safe" (requires no
further escaping) for HTML output purposes. further escaping) for HTML output purposes.
.. class:: SafeUnicode .. class:: SafeUnicode
A unicode subclass that has been specifically marked as "safe" for HTML output A unicode subclass that has been specifically marked as "safe" for HTML
purposes. output purposes.
.. function:: mark_safe(s) .. function:: mark_safe(s)
Explicitly mark a string as safe for (HTML) output purposes. The returned Explicitly mark a string as safe for (HTML) output purposes. The returned
object can be used everywhere a string or unicode object is appropriate. 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) .. function:: mark_for_escaping(s)
Explicitly mark a string as requiring HTML escaping upon output. Has no effect Explicitly mark a string as requiring HTML escaping upon output. Has no
on ``SafeData`` subclasses. effect on ``SafeData`` subclasses.
Can be called multiple times on a single string (the resulting escaping is only Can be called multiple times on a single string (the resulting escaping is
applied once). only applied once).
``django.utils.translation`` ``django.utils.translation``
============================ ============================
@ -397,97 +404,98 @@ For a complete discussion on the usage of the following see the
.. function:: gettext(message) .. 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) .. 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:: gettext_lazy(message)
.. function:: ugettext_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) .. function:: gettext_noop(message)
Marks strings for translation but doesn't translate them now. This can be used Marks strings for translation but doesn't translate them now. This can be
to store strings in global variables that should stay in the base language used to store strings in global variables that should stay in the base
(because they might be used externally) and will be translated later. language (because they might be used externally) and will be translated
later.
.. function:: ngettext(singular, plural, number) .. function:: ngettext(singular, plural, number)
Translates ``singular`` and ``plural`` and returns the appropriate string 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) .. function:: ungettext(singular, plural, number)
Translates ``singular`` and ``plural`` and returns the appropriate string based Translates ``singular`` and ``plural`` and returns the appropriate string
on ``number`` in a unicode string based on ``number`` in a unicode string.
.. function:: ngettext_lazy(singular, plural, number) .. function:: ngettext_lazy(singular, plural, number)
.. function:: ungettext_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) .. function:: string_concat(*strings)
Lazy variant of string concatenation, needed for translations that are Lazy variant of string concatenation, needed for translations that are
constructed from multiple parts. constructed from multiple parts.
.. function:: activate(language) .. function:: activate(language)
Fetches the translation object for a given tuple of application name and Fetches the translation object for a given tuple of application name and
language and installs it as the current translation object for the current language and installs it as the current translation object for the current
thread. thread.
.. function:: deactivate() .. function:: deactivate()
De-installs the currently active translation object so that further _ calls will De-installs the currently active translation object so that further _ calls
resolve against the default translation object, again. will resolve against the default translation object, again.
.. function:: deactivate_all() .. function:: deactivate_all()
Makes the active translation object a NullTranslations() instance. This is Makes the active translation object a NullTranslations() instance. This is
useful when we want delayed translations to appear as the original string for useful when we want delayed translations to appear as the original string
some reason. for some reason.
.. function:: get_language() .. function:: get_language()
Returns the currently selected language code. Returns the currently selected language code.
.. function:: get_language_bidi() .. function:: get_language_bidi()
Returns selected language's BiDi layout: Returns selected language's BiDi layout:
* ``False`` = left-to-right layout * ``False`` = left-to-right layout
* ``True`` = right-to-left layout * ``True`` = right-to-left layout
.. function:: get_date_formats() .. function:: get_date_formats()
Checks whether translation files provide a translation for some technical 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 message ID to store date and time formats. If it doesn't contain one, the
formats provided in the settings will be used. formats provided in the settings will be used.
.. function:: get_language_from_request(request) .. function:: get_language_from_request(request)
Analyzes the request to find what language the user wants the system to show. 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 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 requests a sublanguage where we have a main language, we send out the main
language. language.
.. function:: to_locale(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) .. function:: templatize(src)
Turns a Django template into something that is understood by xgettext. It does Turns a Django template into something that is understood by xgettext. It does
so by translating the Django translation tags into standard gettext function so by translating the Django translation tags into standard gettext function
invocations. invocations.
``django.utils.tzinfo`` ``django.utils.tzinfo``
======================= =======================
@ -497,8 +505,8 @@ invocations.
.. class:: FixedOffset .. class:: FixedOffset
Fixed offset in minutes east from UTC. Fixed offset in minutes east from UTC.
.. class:: LocalTimezone .. class:: LocalTimezone
Proxy timezone information from time module. Proxy timezone information from time module.

46
docs/topics/auth.txt
View File

@ -615,6 +615,8 @@ Django provides two functions in :mod:`django.contrib.auth`:
Manually checking a user's password Manually checking a user's password
----------------------------------- -----------------------------------
.. currentmodule:: django.contrib.auth.models
.. function:: check_password() .. function:: check_password()
If you'd like to manually authenticate a user by comparing a plain-text 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 How to log a user out
--------------------- ---------------------
.. currentmodule:: django.contrib.auth
.. function:: logout() .. function:: logout()
To log out a user who has been logged in via To log out a user who has been logged in via
@ -871,11 +875,13 @@ The login_required decorator
Other built-in views Other built-in views
-------------------- --------------------
.. module:: django.contrib.auth.views
In addition to the :func:`~views.login` view, the authentication system In addition to the :func:`~views.login` view, the authentication system
includes a few other useful built-in views located in includes a few other useful built-in views located in
:mod:`django.contrib.auth.views`: :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. Logs a user out.
@ -895,7 +901,7 @@ includes a few other useful built-in views located in
* ``title``: The string "Logged out", localized. * ``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. 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 * ``login_url``: The URL of the login page to redirect to. This will
default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied. 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. 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. * ``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. 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 default to :file:`registration/password_change_done.html` if not
supplied. 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 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 that can be used to reset the password, and sending that link to the
user's registered e-mail address. user's registered e-mail address.
.. versionchanged:: 1.3
The ``from_email`` argument was added.
**Optional arguments:** **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 * ``post_reset_redirect``: The URL to redirect to after a successful
password change. password change.
.. versionchanged:: 1.3
* ``from_email``: A valid e-mail address. By default Django uses * ``from_email``: A valid e-mail address. By default Django uses
the :setting:`DEFAULT_FROM_EMAIL`. 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. * ``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. 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 default to :file:`registration/password_reset_done.html` if not
supplied. 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 Redirects to the login page, and then back to another URL after a
successful login. 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 URL to redirect to after log out. Overrides ``next`` if the given
``GET`` parameter is passed. ``GET`` parameter is passed.
.. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect]) .. 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. 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 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 To limit access based on certain permissions or some other test, you'd do
essentially the same thing as described in the previous section. 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.") 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:: 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 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 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 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`` As in the :func:`~decorators.login_required` decorator, ``login_url``
defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`. defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
.. currentmodule:: django.contrib.auth
Limiting access to generic views Limiting access to generic views
-------------------------------- --------------------------------
@ -1249,7 +1259,9 @@ closing tasks.)
API reference API reference
------------- -------------
.. class:: models.Permission .. currentmodule:: django.contrib.auth.models
.. class:: Permission
Just like users, permissions are implemented in a Django model that lives Just like users, permissions are implemented in a Django model that lives
in `django/contrib/auth/models.py`_. in `django/contrib/auth/models.py`_.
@ -1262,16 +1274,16 @@ Fields
:class:`~django.contrib.auth.models.Permission` objects have the following :class:`~django.contrib.auth.models.Permission` objects have the following
fields: fields:
.. attribute:: models.Permission.name .. attribute:: Permission.name
Required. 50 characters or fewer. Example: ``'Can vote'``. 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 Required. A reference to the ``django_content_type`` database table, which
contains a record for each installed Django model. contains a record for each installed Django model.
.. attribute:: models.Permission.codename .. attribute:: Permission.codename
Required. 100 characters or fewer. Example: ``'can_vote'``. Required. 100 characters or fewer. Example: ``'can_vote'``.
@ -1281,6 +1293,8 @@ Methods
:class:`~django.contrib.auth.models.Permission` objects have the standard :class:`~django.contrib.auth.models.Permission` objects have the standard
data-access methods like any other :doc:`Django model </ref/models/instances>`. data-access methods like any other :doc:`Django model </ref/models/instances>`.
.. currentmodule:: django.contrib.auth
Authentication data in templates Authentication data in templates
================================ ================================

2
docs/topics/http/decorators.txt
View File

@ -45,7 +45,7 @@ These decorators can be used to generate ``ETag`` and ``Last-Modified``
headers; see headers; see
:doc:`conditional view processing </topics/conditional-view-processing>`. :doc:`conditional view processing </topics/conditional-view-processing>`.
.. currentmodule:: django.views.decorators.http .. currentmodule:: django.views.decorators.gzip
GZip compression GZip compression
================ ================

56
docs/topics/http/file-uploads.txt
View File

@ -2,7 +2,7 @@
File Uploads File Uploads
============ ============
.. currentmodule:: django.core.files .. currentmodule:: django.core.files.uploadedfile
When Django handles a file upload, the file data ends up placed in When Django handles a file upload, the file data ends up placed in
:attr:`request.FILES <django.http.HttpRequest.FILES>` (for more on the :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 Handling uploaded files
----------------------- -----------------------
The final piece of the puzzle is handling the actual file data from .. class:: UploadedFile
:attr:`request.FILES <django.http.HttpRequest.FILES>`. Each entry in this
dictionary is an ``UploadedFile`` object -- a simple wrapper around an uploaded The final piece of the puzzle is handling the actual file data from
file. You'll usually use one of these methods to access the uploaded content: :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 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 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()`` try to read it into memory. You'll probably want to use ``chunks()``
instead; see below. instead; see below.
``UploadedFile.multiple_chunks()`` .. method:: multiple_chunks()
Returns ``True`` if the uploaded file is big enough to require Returns ``True`` if the uploaded file is big enough to require
reading in multiple chunks. By default this will be any file reading in multiple chunks. By default this will be any file
larger than 2.5 megabytes, but that's configurable; see below. 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 A generator returning chunks of the file. If ``multiple_chunks()`` is
``True``, you should use this method in a loop instead of ``read()``. ``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; In practice, it's often easiest simply to use ``chunks()`` all the time;
see the example below. see the example below.
``UploadedFile.name`` .. attribute:: name
The name of the uploaded file (e.g. ``my_file.txt``). The name of the uploaded file (e.g. ``my_file.txt``).
``UploadedFile.size`` .. attribute:: size
The size, in bytes, of the uploaded file. The size, in bytes, of the uploaded file.
There are a few other methods and attributes available on ``UploadedFile`` 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 ``UploadedFile`` objects
======================== ========================
.. class:: UploadedFile
In addition to those inherited from :class:`File`, all ``UploadedFile`` objects In addition to those inherited from :class:`File`, all ``UploadedFile`` objects
define the following methods/attributes: 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`` The content-type header uploaded with the file (e.g. ``text/plain`` or
For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied ``application/pdf``). Like any data supplied by the user, you shouldn't
by the browser. Again, "trust but verify" is the best policy here. 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.temporary_file_path()`` .. attribute:: UploadedFile.charset
Only files uploaded onto disk will have this method; it returns the full
path to the temporary uploaded file. 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()
Only files uploaded onto disk will have this method; it returns the full
path to the temporary uploaded file.
.. note:: .. note::

2
docs/topics/http/urls.txt
View File

@ -765,6 +765,8 @@ following would happen:
Utility methods Utility methods
=============== ===============
.. module:: django.core.urlresolvers
reverse() reverse()
--------- ---------