summaryrefslogtreecommitdiff
path: root/parts/django/docs/ref/utils.txt
diff options
context:
space:
mode:
authorNishanth Amuluru2011-01-08 11:20:57 +0530
committerNishanth Amuluru2011-01-08 11:20:57 +0530
commit65411d01d448ff0cd4abd14eee14cf60b5f8fc20 (patch)
treeb4c404363c4c63a61d6e2f8bd26c5b057c1fb09d /parts/django/docs/ref/utils.txt
parent2e35094d43b4cc6974172e1febf76abb50f086ec (diff)
downloadpytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.gz
pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.bz2
pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.zip
Added buildout stuff and made changes accordingly
--HG-- rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt rename : taskapp/models.py => parts/django/django/conf/app_template/models.py rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py rename : taskapp/views.py => parts/django/django/conf/app_template/views.py rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py rename : profile/forms.py => pytask/profile/forms.py rename : profile/management/__init__.py => pytask/profile/management/__init__.py rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py rename : profile/models.py => pytask/profile/models.py rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py rename : taskapp/tests.py => pytask/profile/tests.py rename : profile/urls.py => pytask/profile/urls.py rename : profile/utils.py => pytask/profile/utils.py rename : profile/views.py => pytask/profile/views.py rename : static/css/base.css => pytask/static/css/base.css rename : taskapp/tests.py => pytask/taskapp/tests.py rename : taskapp/views.py => pytask/taskapp/views.py rename : templates/base.html => pytask/templates/base.html rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html rename : templates/profile/edit.html => pytask/templates/profile/edit.html rename : templates/profile/view.html => pytask/templates/profile/view.html rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html rename : templates/registration/activate.html => pytask/templates/registration/activate.html rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html rename : templates/registration/login.html => pytask/templates/registration/login.html rename : templates/registration/logout.html => pytask/templates/registration/logout.html rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html rename : utils.py => pytask/utils.py
Diffstat (limited to 'parts/django/docs/ref/utils.txt')
-rw-r--r--parts/django/docs/ref/utils.txt504
1 files changed, 504 insertions, 0 deletions
diff --git a/parts/django/docs/ref/utils.txt b/parts/django/docs/ref/utils.txt
new file mode 100644
index 0000000..e4ce7c4
--- /dev/null
+++ b/parts/django/docs/ref/utils.txt
@@ -0,0 +1,504 @@
+============
+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 <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, :doc:`internationalization </topics/i18n/index>` 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
+:doc:`Internationalization documentation </topics/i18n/internationalization>`.
+
+.. 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 <lazy-translations>`.
+
+.. function:: gettext_noop(message)
+
+Marks strings for translation but doesn't translate them now. This can be used
+to store strings in global variables that should stay in the base language
+(because they might be used externally) and will be translated later.
+
+.. 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 <lazy-translations>`.
+
+.. 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.