Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Made several grammar fixes to cache documentation from [1020]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1030 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit cbe24263692641af8908da21d1a2d333100a468a 1 parent fb55717
@adrianholovaty adrianholovaty authored
Showing with 57 additions and 33 deletions.
  1. +7 −9 django/utils/cache.py
  2. +50 −24 docs/cache.txt
View
16 django/utils/cache.py
@@ -22,19 +22,19 @@
from django.core.cache import cache
cc_delim_re = re.compile(r'\s*,\s*')
+
def 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
- all _ will be translated to -
- - if the value of a parameter is True (exatly 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.
"""
-
def dictitem(s):
t = s.split('=',1)
if len(t) > 1:
@@ -49,9 +49,7 @@ def dictvalue(t):
return t[0] + '=' + str(t[1])
if response.has_header('Cache-Control'):
- print response['Cache-Control']
cc = cc_delim_re.split(response['Cache-Control'])
- print cc
cc = dict([dictitem(el) for el in cc])
else:
cc = {}
View
74 docs/cache.txt
@@ -272,39 +272,65 @@ and a list/tuple of header names as its second argument.
.. _`HTTP Vary headers`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
-Controlling cache: Using Vary headers
-=====================================
+Controlling cache: Using other headers
+======================================
+
+Another problem with caching is the privacy of data and the question of where
+data should be stored in a cascade of caches.
+
+A user usually faces two kinds of caches: his own browser cache (a private
+cache) and his provider's cache (a public cache). A public cache is used by
+multiple users and controlled by someone else. This poses problems with
+sensitive data: You don't want, say, your banking-account number stored in a
+public cache. So Web applications need a way to tell caches which data is
+private and which is public.
+
+The solution is to indicate a page's cache should be "private." To do this in
+Django, use the ``cache_control`` view decorator. Example::
+
+ from django.views.decorators.cache import cache_control
+ @cache_control(private=True)
+ def my_view(request):
+ ...
+
+This decorator takes care of sending out the appropriate HTTP header behind the
+scenes.
-Another problem with caching is the privacy of data, and the question where data can
-be stored in a cascade of caches. A user usually faces two kinds of caches: his own
-browser cache (a private cache) and his providers cache (a public cache). A public cache
-is used by multiple users and controlled by someone else. This poses problems with private
-(in the sense of sensitive) data - you don't want your social security number or your
-banking account numbers stored in some public cache. So web applications need a way
-to tell the caches what data is private and what is public.
+There are a few other ways to control cache parameters. For example, HTTP
+allows applications to do the following:
-Other aspects are the definition how long a page should be cached at max, or wether the
-cache should allways check for newer versions and only deliver the cache content when
-there were no changes (some caches might deliver cached content even if the server page
-changed - just because the cache copy isn't yet expired).
+ * Define the maximum time a page should be cached.
+ * Specify whether a cache should always check for newer versions, only
+ delivering the cached content when there are no changes. (Some caches
+ might deliver cached content even if the server page changed -- simply
+ because the cache copy isn't yet expired.)
-So there are a multitude of options you can control for your pages. This is where the
-Cache-Control header (more infos in `HTTP Cache-Control headers`_) comes in. The usage
-is quite simple::
+In Django, use the ``cache_control`` view decorator to specify these cache
+parameters. In this example, the ``cache_control`` decorator tells caches to
+revalidate the cache on every access and to store cached versions for, at most,
+3600 seconds::
- @cache_control(private=True, must_revalidate=True, max_age=3600)
+ from django.views.decorators.cache import cache_control
+ @cache_control(must_revalidate=True, max_age=3600)
def my_view(request):
...
-This would define the view as private, to be revalidated on every access and cache
-copies will only be stored for 3600 seconds at max.
+Any valid Cache-Control directive is valid in ``cache_control()``. For a full
+list, see the `Cache-Control spec`_. Just pass the directives as keyword
+arguments to ``cache_control()``, substituting underscores for hyphens. For
+directives that don't take an argument, set the argument to ``True``.
+
+Examples:
+
+ ``@cache_control(max_age=3600)`` turns into ``max-age=3600``.
+ ``@cache_control(public=True)`` turns into ``public``.
-The caching middleware already set's this header up with a max-age of the CACHE_MIDDLEWARE_SETTINGS
-setting. And the cache_page decorator does the same. The cache_control decorator correctly merges
-different values into one big header, though. But you should take into account that middlewares
-might overwrite some of your headers or set their own defaults if you don't give that header yourself.
+(Note that the caching middleware already sets the cache header's max-age with
+the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
+``max_age`` in a ``cache_control`` decorator, the decorator will take
+precedence, and the header values will be merged correctly.)
-.. _`HTTP Cache-Control headers`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
+.. _`Cache-Control spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
Other optimizations
===================
Please sign in to comment.
Something went wrong with that request. Please try again.