diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index f63d55bab0..42c0a34055 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -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. diff --git a/docs/ref/contrib/formtools/form-preview.txt b/docs/ref/contrib/formtools/form-preview.txt index a2cbea704a..c5d8b9a8d8 100644 --- a/docs/ref/contrib/formtools/form-preview.txt +++ b/docs/ref/contrib/formtools/form-preview.txt @@ -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. diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 0501b9b0d0..dbdf109134 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -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 diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 973ddff7d9..cacc5e7ec3 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1749,6 +1749,8 @@ SQL equivalents:: Aggregation functions --------------------- +.. currentmodule:: django.db.models + Django provides the following aggregation functions in the ``django.db.models`` module. For details on how to use these aggregate functions, see @@ -1759,100 +1761,100 @@ Avg .. class:: Avg(field) -Returns the mean value of the given field. + Returns the mean value of the given field. - * Default alias: ``__avg`` - * Return type: float + * Default alias: ``__avg`` + * Return type: float Count ~~~~~ .. class:: Count(field, distinct=False) -Returns the number of objects that are related through the provided field. + Returns the number of objects that are related through the provided field. - * Default alias: ``__count`` - * Return type: integer + * Default alias: ``__count`` + * Return type: integer -Has one optional argument: + Has one optional argument: -.. attribute:: distinct + .. attribute:: distinct - If distinct=True, the count will only include unique instances. This has - the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``. + If distinct=True, the count will only include unique instances. This has + the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``. Max ~~~ .. class:: Max(field) -Returns the maximum value of the given field. + Returns the maximum value of the given field. - * Default alias: ``__max`` - * Return type: same as input field + * Default alias: ``__max`` + * Return type: same as input field Min ~~~ .. class:: Min(field) -Returns the minimum value of the given field. + Returns the minimum value of the given field. - * Default alias: ``__min`` - * Return type: same as input field + * Default alias: ``__min`` + * Return type: same as input field StdDev ~~~~~~ .. class:: StdDev(field, sample=False) -Returns the standard deviation of the data in the provided field. + Returns the standard deviation of the data in the provided field. - * Default alias: ``__stddev`` - * Return type: float + * Default alias: ``__stddev`` + * Return type: float -Has one optional argument: + Has one optional argument: -.. attribute:: sample + .. attribute:: sample - By default, ``StdDev`` returns the population standard deviation. However, - if ``sample=True``, the return value will be the sample standard deviation. + By default, ``StdDev`` returns the population standard deviation. However, + if ``sample=True``, the return value will be the sample standard deviation. -.. admonition:: SQLite + .. admonition:: SQLite - SQLite doesn't provide ``StdDev`` out of the box. An implementation is - available as an extension module for SQLite. Consult the SQlite - documentation for instructions on obtaining and installing this extension. + SQLite doesn't provide ``StdDev`` out of the box. An implementation is + available as an extension module for SQLite. Consult the SQlite + documentation for instructions on obtaining and installing this extension. Sum ~~~ .. class:: Sum(field) -Computes the sum of all values of the given field. + Computes the sum of all values of the given field. - * Default alias: ``__sum`` - * Return type: same as input field + * Default alias: ``__sum`` + * Return type: same as input field Variance ~~~~~~~~ .. class:: Variance(field, sample=False) -Returns the variance of the data in the provided field. + Returns the variance of the data in the provided field. - * Default alias: ``__variance`` - * Return type: float + * Default alias: ``__variance`` + * Return type: float -Has one optional argument: + Has one optional argument: -.. attribute:: sample + .. attribute:: sample - By default, ``Variance`` returns the population variance. However, - if ``sample=True``, the return value will be the sample variance. + By default, ``Variance`` returns the population variance. However, + if ``sample=True``, the return value will be the sample variance. -.. admonition:: SQLite + .. admonition:: SQLite - SQLite doesn't provide ``Variance`` out of the box. An implementation is - available as an extension module for SQLite. Consult the SQlite - documentation for instructions on obtaining and installing this extension. + SQLite doesn't provide ``Variance`` out of the box. An implementation is + available as an extension module for SQLite. Consult the SQlite + documentation for instructions on obtaining and installing this extension. diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index e4ce7c4f86..8a388fd70c 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -35,66 +35,68 @@ to distinguish caches by the ``Accept-language`` header. .. function:: patch_cache_control(response, **kwargs) -This function patches the ``Cache-Control`` header by adding all keyword -arguments to it. The transformation is as follows: + This function patches the ``Cache-Control`` header by adding all keyword + arguments to it. The transformation is as follows: - * All keyword parameter names are turned to lowercase, and underscores - are converted to hyphens. - * If the value of a parameter is ``True`` (exactly ``True``, not just a - true value), only the parameter name is added to the header. - * All other parameters are added with their value, after applying - ``str()`` to it. + * All keyword parameter names are turned to lowercase, and underscores + are converted to hyphens. + * If the value of a parameter is ``True`` (exactly ``True``, not just a + true value), only the parameter name is added to the header. + * All other parameters are added with their value, after applying + ``str()`` to it. .. function:: get_max_age(response) -Returns the max-age from the response Cache-Control header as an integer (or -``None`` if it wasn't found or wasn't an integer). + Returns the max-age from the response Cache-Control header as an integer + (or ``None`` if it wasn't found or wasn't an integer). .. function:: patch_response_headers(response, cache_timeout=None) -Adds some useful headers to the given ``HttpResponse`` object: + Adds some useful headers to the given ``HttpResponse`` object: - * ``ETag`` - * ``Last-Modified`` - * ``Expires`` - * ``Cache-Control`` + * ``ETag`` + * ``Last-Modified`` + * ``Expires`` + * ``Cache-Control`` -Each header is only added if it isn't already set. + Each header is only added if it isn't already set. -``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting is -used by default. + ``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting + is used by default. .. function:: add_never_cache_headers(response) -Adds headers to a response to indicate that a page should never be cached. + Adds headers to a response to indicate that a page should never be cached. .. function:: patch_vary_headers(response, newheaders) -Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object. -``newheaders`` is a list of header names that should be in ``Vary``. Existing -headers in ``Vary`` aren't removed. + Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object. + ``newheaders`` is a list of header names that should be in ``Vary``. + Existing headers in ``Vary`` aren't removed. .. function:: get_cache_key(request, key_prefix=None) -Returns a cache key based on the request path. It can be used in the request -phase because it pulls the list of headers to take into account from the -global path registry and uses those to build a cache key to check against. + Returns a cache key based on the request path. It can be used in the + request phase because it pulls the list of headers to take into account + from the global path registry and uses those to build a cache key to + check against. -If there is no headerlist stored, the page needs to be rebuilt, so this -function returns ``None``. + If there is no headerlist stored, the page needs to be rebuilt, so this + function returns ``None``. .. function:: learn_cache_key(request, response, cache_timeout=None, key_prefix=None) -Learns what headers to take into account for some request path from the -response object. It stores those headers in a global path registry so that -later access to that path will know what headers to take into account without -building the response object itself. The headers are named in the ``Vary`` -header of the response, but we want to prevent response generation. + Learns what headers to take into account for some request path from the + response object. It stores those headers in a global path registry so that + later access to that path will know what headers to take into account + without building the response object itself. The headers are named in + the ``Vary`` header of the response, but we want to prevent response + generation. -The list of headers to use for cache key generation is stored in the same cache -as the pages themselves. If the cache ages some data out of the cache, this -just means that we have to build the response once to get at the Vary header -and so at the list of headers to use for the cache key. + The list of headers to use for cache key generation is stored in the same + cache as the pages themselves. If the cache ages some data out of the + cache, this just means that we have to build the response once to get at + the Vary header and so at the list of headers to use for the cache key. SortedDict ========== @@ -102,23 +104,23 @@ SortedDict .. module:: django.utils.datastructures :synopsis: A dictionary that keeps its keys in the order in which they're inserted. -.. class:: django.utils.datastructures.SortedDict +.. class:: SortedDict -Methods -------- + 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 `. + See :ref:`lazy translations documentation `. .. 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 `. + See :ref:`lazy translations documentation `. .. function:: string_concat(*strings) -Lazy variant of string concatenation, needed for translations that are -constructed from multiple parts. + Lazy variant of string concatenation, needed for translations that are + constructed from multiple parts. .. function:: activate(language) -Fetches the translation object for a given tuple of application name and -language and installs it as the current translation object for the current -thread. + Fetches the translation object for a given tuple of application name and + language and installs it as the current translation object for the current + thread. .. function:: deactivate() -De-installs the currently active translation object so that further _ calls will -resolve against the default translation object, again. + De-installs the currently active translation object so that further _ calls + will resolve against the default translation object, again. .. function:: deactivate_all() -Makes the active translation object a NullTranslations() instance. This is -useful when we want delayed translations to appear as the original string for -some reason. + Makes the active translation object a NullTranslations() instance. This is + useful when we want delayed translations to appear as the original string + for some reason. .. function:: get_language() -Returns the currently selected language code. + Returns the currently selected language code. .. function:: get_language_bidi() -Returns selected language's BiDi layout: + Returns selected language's BiDi layout: - * ``False`` = left-to-right layout - * ``True`` = right-to-left layout + * ``False`` = left-to-right layout + * ``True`` = right-to-left layout .. function:: get_date_formats() -Checks whether translation files provide a translation for some technical -message ID to store date and time formats. If it doesn't contain one, the -formats provided in the settings will be used. + Checks whether translation files provide a translation for some technical + message ID to store date and time formats. If it doesn't contain one, the + formats provided in the settings will be used. .. function:: get_language_from_request(request) -Analyzes the request to find what language the user wants the system to show. -Only languages listed in settings.LANGUAGES are taken into account. If the user -requests a sublanguage where we have a main language, we send out the main -language. + Analyzes the request to find what language the user wants the system to show. + Only languages listed in settings.LANGUAGES are taken into account. If the user + requests a sublanguage where we have a main language, we send out the main + language. .. function:: to_locale(language) -Turns a language name (en-us) into a locale name (en_US). + Turns a language name (en-us) into a locale name (en_US). .. function:: templatize(src) -Turns a Django template into something that is understood by xgettext. It does -so by translating the Django translation tags into standard gettext function -invocations. + Turns a Django template into something that is understood by xgettext. It does + so by translating the Django translation tags into standard gettext function + invocations. ``django.utils.tzinfo`` ======================= @@ -497,8 +505,8 @@ invocations. .. class:: FixedOffset -Fixed offset in minutes east from UTC. + Fixed offset in minutes east from UTC. .. class:: LocalTimezone -Proxy timezone information from time module. + Proxy timezone information from time module. diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index bc27ea5323..6c758d984e 100644 --- a/docs/topics/auth.txt +++ b/docs/topics/auth.txt @@ -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 ` if not supplied. -.. function:: views.password_change(request[, template_name, post_change_redirect, password_change_form]) +.. function:: password_change(request[, template_name, post_change_redirect, password_change_form]) Allows a user to change their password. @@ -928,7 +934,7 @@ includes a few other useful built-in views located in * ``form``: The password change form. -.. function:: views.password_change_done(request[, template_name]) +.. function:: password_change_done(request[, template_name]) The page shown after a user has changed their password. @@ -938,11 +944,14 @@ includes a few other useful built-in views located in default to :file:`registration/password_change_done.html` if not supplied. -.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email]) +.. function:: password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email]) Allows a user to reset their password by generating a one-time use link that can be used to reset the password, and sending that link to the user's registered e-mail address. + + .. versionchanged:: 1.3 + The ``from_email`` argument was added. **Optional arguments:** @@ -964,8 +973,6 @@ includes a few other useful built-in views located in * ``post_reset_redirect``: The URL to redirect to after a successful password change. - .. versionchanged:: 1.3 - * ``from_email``: A valid e-mail address. By default Django uses the :setting:`DEFAULT_FROM_EMAIL`. @@ -973,7 +980,7 @@ includes a few other useful built-in views located in * ``form``: The form for resetting the user's password. -.. function:: views.password_reset_done(request[, template_name]) +.. function:: password_reset_done(request[, template_name]) The page shown after a user has reset their password. @@ -983,7 +990,7 @@ includes a few other useful built-in views located in default to :file:`registration/password_reset_done.html` if not supplied. -.. function:: views.redirect_to_login(next[, login_url, redirect_field_name]) +.. function:: redirect_to_login(next[, login_url, redirect_field_name]) Redirects to the login page, and then back to another URL after a successful login. @@ -1001,6 +1008,7 @@ includes a few other useful built-in views located in URL to redirect to after log out. Overrides ``next`` if the given ``GET`` parameter is passed. + .. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect]) Presents a form for entering a new password. @@ -1073,7 +1081,7 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`: Limiting access to logged-in users that pass a test --------------------------------------------------- -.. currentmodule:: django.contrib.auth +.. currentmodule:: django.contrib.auth.decorators To limit access based on certain permissions or some other test, you'd do essentially the same thing as described in the previous section. @@ -1088,7 +1096,7 @@ checks to make sure the user is logged in and has the permission return HttpResponse("You can't vote in this poll.") # ... -.. function:: decorators.user_passes_test() +.. function:: user_passes_test() As a shortcut, you can use the convenient ``user_passes_test`` decorator:: @@ -1126,7 +1134,7 @@ checks to make sure the user is logged in and has the permission The permission_required decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. function:: decorators.permission_required() +.. function:: permission_required() It's a relatively common task to check whether a user has a particular permission. For that reason, Django provides a shortcut for that case: the @@ -1155,6 +1163,8 @@ The permission_required decorator As in the :func:`~decorators.login_required` decorator, ``login_url`` defaults to :setting:`settings.LOGIN_URL `. +.. 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 `. +.. currentmodule:: django.contrib.auth + Authentication data in templates ================================ diff --git a/docs/topics/http/decorators.txt b/docs/topics/http/decorators.txt index 30883a45e8..fdb660d1a5 100644 --- a/docs/topics/http/decorators.txt +++ b/docs/topics/http/decorators.txt @@ -45,7 +45,7 @@ These decorators can be used to generate ``ETag`` and ``Last-Modified`` headers; see :doc:`conditional view processing `. -.. currentmodule:: django.views.decorators.http +.. currentmodule:: django.views.decorators.gzip GZip compression ================ diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt index 377dcacb8d..af4ab6423a 100644 --- a/docs/topics/http/file-uploads.txt +++ b/docs/topics/http/file-uploads.txt @@ -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 ` (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 `. 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 `. Each entry in this + dictionary is an ``UploadedFile`` object -- a simple wrapper around an uploaded + file. You'll usually use one of these methods to access the uploaded content: + + .. method:: read() - ``UploadedFile.read()`` Read the entire uploaded data from the file. Be careful with this method: if the uploaded file is huge it can overwhelm your system if you try to read it into memory. You'll probably want to use ``chunks()`` instead; see below. - ``UploadedFile.multiple_chunks()`` + .. method:: multiple_chunks() + Returns ``True`` if the uploaded file is big enough to require reading in multiple chunks. By default this will be any file larger than 2.5 megabytes, but that's configurable; see below. - ``UploadedFile.chunks()`` + .. method:: chunks() + A generator returning chunks of the file. If ``multiple_chunks()`` is ``True``, you should use this method in a loop instead of ``read()``. In practice, it's often easiest simply to use ``chunks()`` all the time; see the example below. - ``UploadedFile.name`` + .. attribute:: name + The name of the uploaded file (e.g. ``my_file.txt``). - ``UploadedFile.size`` + .. attribute:: size + The size, in bytes, of the uploaded file. There are a few other methods and attributes available on ``UploadedFile`` @@ -177,25 +184,26 @@ Three settings control Django's file upload behavior: ``UploadedFile`` objects ======================== -.. class:: UploadedFile - In addition to those inherited from :class:`File`, all ``UploadedFile`` objects define the following methods/attributes: - ``UploadedFile.content_type`` - The content-type header uploaded with the file (e.g. ``text/plain`` or - ``application/pdf``). Like any data supplied by the user, you shouldn't - trust that the uploaded file is actually this type. You'll still need to - validate that the file contains the content that the content-type header - claims -- "trust but verify." +.. attribute:: UploadedFile.content_type - ``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. + 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.temporary_file_path()`` - Only files uploaded onto disk will have this method; it returns the full - path to the temporary uploaded file. +.. 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. + +.. 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:: diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index 1ff1c66542..3b6329a4c0 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -765,6 +765,8 @@ following would happen: Utility methods =============== +.. module:: django.core.urlresolvers + reverse() ---------