From 47639b641060bc0520983314e68f1dbbbe57c1cb Mon Sep 17 00:00:00 2001 From: Brian Rosner Date: Sat, 8 May 2010 21:38:27 +0000 Subject: [PATCH] Fixed #3469 -- added django.utils documentation for stable bits Thanks to Rupe and Ramiro Morales for their initial work on this patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@13140 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- django/utils/feedgenerator.py | 6 +- django/utils/translation/trans_real.py | 5 +- docs/misc/api-stability.txt | 3 +- docs/ref/index.txt | 1 + docs/ref/utils.txt | 506 +++++++++++++++++++++++++ 5 files changed, 517 insertions(+), 4 deletions(-) create mode 100644 docs/ref/utils.txt diff --git a/django/utils/feedgenerator.py b/django/utils/feedgenerator.py index 856c164d81..4175317250 100644 --- a/django/utils/feedgenerator.py +++ b/django/utils/feedgenerator.py @@ -10,7 +10,11 @@ Sample usage: ... description=u"A group weblog by the sharpest minds in online media/journalism/publishing.", ... language=u"en", ... ) ->>> feed.add_item(title="Hello", link=u"http://www.holovaty.com/test/", description="Testing.") +>>> feed.add_item( +... title="Hello", +... link=u"http://www.holovaty.com/test/", +... description="Testing." +... ) >>> fp = open('test.rss', 'w') >>> feed.write(fp, 'utf-8') >>> fp.close() diff --git a/django/utils/translation/trans_real.py b/django/utils/translation/trans_real.py index 641318ba01..b528f8e586 100644 --- a/django/utils/translation/trans_real.py +++ b/django/utils/translation/trans_real.py @@ -224,8 +224,9 @@ def get_language(): def get_language_bidi(): """ 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 """ from django.conf import settings diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt index 52fd430011..a648c873cc 100644 --- a/docs/misc/api-stability.txt +++ b/docs/misc/api-stability.txt @@ -96,7 +96,8 @@ of 1.0. This includes these APIs: ``django.utils`` ---------------- -Most of the modules in ``django.utils`` are designed for internal use. Only the following parts of ``django.utils`` can be considered stable: +Most of the modules in ``django.utils`` are designed for internal use. Only +the following parts of :ref:`django.utils ` can be considered stable: - ``django.utils.cache`` - ``django.utils.datastructures.SortedDict`` -- only this single class; the diff --git a/docs/ref/index.txt b/docs/ref/index.txt index d47fd9b33a..e6fa17787a 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -21,4 +21,5 @@ API Reference signals templates/index unicode + utils validators diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt new file mode 100644 index 0000000000..e64b3868b9 --- /dev/null +++ b/docs/ref/utils.txt @@ -0,0 +1,506 @@ +.. _ref-utils: + +============ +Django Utils +============ + +.. module:: django.utils + :synopsis: Django's built-in utilities. + +This document covers all stable modules in ``django.utils``. Most of the +modules in ``django.utils`` are designed for internal use and only the +following parts can be considered stable and thus backwards compatible as per +the :ref:`internal release deprecation policy `. + +``django.utils.cache`` +====================== + +.. module:: django.utils.cache + :synopsis: Helper functions for controlling caching. + +This module contains helper functions for controlling caching. It does so by +managing the ``Vary`` header of responses. It includes functions to patch the +header of response objects directly and decorators that change functions to do +that header-patching themselves. + +For information on the ``Vary`` header, see `RFC 2616 section 14.44`_. + +.. _RFC 2616 section 14.44: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44 + +Essentially, the ``Vary`` HTTP header defines which headers a cache should take +into account when building its cache key. Requests with the same path but +different header content for headers named in ``Vary`` need to get different +cache keys to prevent delivery of wrong content. + +For example, :ref:`internationalization ` middleware would need +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: + + * 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). + +.. function:: patch_response_headers(response, cache_timeout=None) + +Adds some useful headers to the given ``HttpResponse`` object: + + * ``ETag`` + * ``Last-Modified`` + * ``Expires`` + * ``Cache-Control`` + +Each header is only added if it isn't already set. + +``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. + +.. 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. + +.. 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. + +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. + +The list of headers to use for cache key generation is stored in the same cache +as the pages themselves. If the cache ages some data out of the cache, this +just means that we have to build the response once to get at the Vary header +and so at the list of headers to use for the cache key. + +SortedDict +========== + +.. module:: django.utils.datastructures + :synopsis: A dictionary that keeps its keys in the order in which they're inserted. + +.. class:: django.utils.datastructures.SortedDict + +Methods +------- + +Extra methods that ``SortedDict`` adds to the standard Python ``dict`` class. + +.. method:: insert(index, key, value) + +Inserts the key, value pair before the item with the given index. + +.. method:: value_for_index(index) + +Returns the value of the item at the given zero-based index. + +Creating new SortedDict +----------------------- + +Creating a new ``SortedDict`` must be done in a way where ordering is +guaranteed. For example:: + + SortedDict({'b': 1, 'a': 2, 'c': 3}) + +will not work. Passing in a basic Python ``dict`` could produce unreliable +results. Instead do:: + + SortedDict([('b', 1), ('a', 2), ('c', 3)]) + +``django.utils.encoding`` +========================= + +.. module:: django.utils.encoding + :synopsis: A series of helper classes and function to manage character encoding. + +.. class:: StrAndUnicode + +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. + +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. + +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. + +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``. + +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. + +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 + +Returns an ASCII string containing the encoded result. + +``django.utils.feedgenerator`` +============================== + +.. module:: django.utils.feedgenerator + :synopsis: Syndication feed generation library -- used for generating RSS, etc. + +Sample usage:: + + >>> from django.utils import feedgenerator + >>> feed = feedgenerator.Rss201rev2Feed( + ... title=u"Poynter E-Media Tidbits", + ... link=u"http://www.poynter.org/column.asp?id=31", + ... description=u"A group weblog by the sharpest minds in online media/journalism/publishing.", + ... language=u"en", + ... ) + >>> feed.add_item( + ... title="Hello", + ... link=u"http://www.holovaty.com/test/", + ... description="Testing." + ... ) + >>> fp = open('test.rss', 'w') + >>> feed.write(fp, 'utf-8') + >>> fp.close() + +For simplifying the selection of a generator use ``feedgenerator.DefaultFeed`` +which is currently ``Rss201rev2Feed`` + +For definitions of the different versions of RSS, see: +http://diveintomark.org/archives/2004/02/04/incompatible-rss + +.. function:: get_tag_uri(url, date) + +Creates a TagURI. + +See http://diveintomark.org/archives/2004/05/28/howto-atom-id + +SyndicationFeed +--------------- + +.. class:: SyndicationFeed + +Base class for all syndication feeds. Subclasses should provide write(). + +Methods +~~~~~~~ + +.. 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. + +.. method:: num_items() + +.. method:: root_attributes() + +Return extra attributes to place on the root (i.e. feed/channel) element. +Called from write(). + +.. method:: add_root_elements(handler) + +Add elements in the root (i.e. feed/channel) element. Called from write(). + +.. method:: item_attributes(item) + +Return extra attributes to place on each item (i.e. item/entry) element. + +.. method:: add_item_elements(handler, item) + +Add elements on each item (i.e. item/entry) element. + +.. method:: write(outfile, encoding) + +Outputs the feed in the given encoding to ``outfile``, which is a file-like +object. Subclasses should override this. + +.. method:: writeString(encoding) + +Returns the feed in the given encoding as a string. + +.. method:: latest_post_date() + +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 + +RssFeed +------- + +.. class:: RssFeed(SyndicationFeed) + +Rss201rev2Feed +-------------- + +.. class:: Rss201rev2Feed(RssFeed) + +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 + +``django.utils.http`` +===================== + +.. module:: django.utils.http + :synopsis: HTTP helper functions. (URL encoding, cookie handling, ...) + +.. 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. + +.. 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. + +.. 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. + +.. function:: cookie_date(epoch_seconds=None) + +Formats the time to ensure compatibility with Netscape's cookie standard. + +Accepts a floating point number expressed in seconds since the epoch, in UTC - +such as that outputted by ``time.time()``. If set to ``None``, defaults to the current +time. + +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. + +.. _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. + +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 + +.. function:: int_to_base36(i) + +Converts an integer to a base36 string + +``django.utils.safestring`` +=========================== + +.. module:: django.utils.safestring + :synopsis: Functions and classes for working with strings that can be displayed safely without further escaping in HTML. + +Functions and classes for working with "safe strings": strings that can be +displayed safely without further escaping in HTML. Marking something as a "safe +string" means that the producer of the string has already turned characters +that should not be interpreted by the HTML engine (e.g. '<') into the +appropriate entities. + +.. class:: SafeString + +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. + +.. 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. + +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. + +Can be called multiple times on a single string (the resulting escaping is only +applied once). + +``django.utils.translation`` +============================ + +.. module:: django.utils.translation + :synopsis: Internationalization support. + +For a complete discussion on the usage of the following see the +:ref:`Internationalization documentation `. + +.. function:: gettext(message) + +Translates ``message`` and returns it in a UTF-8 bytestring + +.. function:: ugettext(message) + +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. + +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. + +.. function:: ngettext(singular, plural, number) + +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 + +.. function:: ngettext_lazy(singular, plural, number) +.. function:: ungettext_lazy(singular, plural, number) + +Same as the non-lazy versions above, but using lazy execution. + +See :ref:`lazy translations documentation `. + +.. function:: string_concat(*strings) + +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. + +.. function:: deactivate() + +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. + +.. function:: get_language() + +Returns the currently selected language code. + +.. function:: get_language_bidi() + +Returns selected language's BiDi layout: + + * ``False`` = left-to-right layout + * ``True`` = right-to-left layout + +.. function:: get_date_formats() + +Checks whether translation files provide a translation for some technical +message ID to store date and time formats. If it doesn't contain one, the +formats provided in the settings will be used. + +.. 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. + +.. function:: to_locale(language) + +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. + +``django.utils.tzinfo`` +======================= + +.. module:: django.utils.tzinfo + :synopsis: Implementation of ``tzinfo`` classes for use with ``datetime.datetime``. + +.. class:: FixedOffset + +Fixed offset in minutes east from UTC. + +.. class:: LocalTimezone + +Proxy timezone information from time module.