magic-removal: Refactored never_cache decorator to provide a utility

function that can be used inside views, and added docs.


git-svn-id: http://code.djangoproject.com/svn/django/branches/magic-removal@2602 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/utils/cache.py

@@ -84,6 +84,13 @@ def patch_response_headers(response, cache_timeout=None):
         cache_timeout = 0 # Can't have max-age negative
     patch_cache_control(response, max_age=cache_timeout)
 
+def add_never_cache_headers(response):
+    """
+    Add headers to a response to indicate that 
+    a page should never be cached.
+    """
+    patch_response_headers(response, cache_timeout=-1)
+
 def patch_vary_headers(response, newheaders):
     """
     Adds (or updates) the "Vary" header in the given HttpResponse object.

django/views/decorators/cache.py

@@ -13,7 +13,7 @@ account on caching -- just like the middleware does.
 import re
 
 from django.utils.decorators import decorator_from_middleware
-from django.utils.cache import patch_cache_control, patch_response_headers
+from django.utils.cache import patch_cache_control, add_never_cache_headers
 from django.middleware.cache import CacheMiddleware
 
 cache_page = decorator_from_middleware(CacheMiddleware)
@@ -31,7 +31,6 @@ def cache_control(**kwargs):
 
     return _cache_controller
 
-
 def never_cache(view_func):
     """
     Decorator that adds headers to a response so that it will
@@ -39,6 +38,6 @@ def never_cache(view_func):
     """
     def _wrapped_view_func(request, *args, **kwargs):
         response = view_func(request, *args, **kwargs)
-        patch_response_headers(response, cache_timeout=-1)
+        add_never_cache_headers(response)
         return response
     return _wrapped_view_func

docs/cache.txt

@@ -332,6 +332,18 @@ 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.)
 
+If you want to use headers to disable caching altogether, two utility functions
+are provided.  `django.utils.cache.add_never_cache_headers`` is a
+function that takes a single HttpResponse object as its argument and adds
+headers to ensure the response won't be cached by browsers or other caches.
+``django.views.decorators.never_cache`` is a view decorator that does the same
+thing but can be applied to a view function for convenience.  Example::
+
+    from django.views.decorators.cache import never_cache
+    @never_cache
+    def myview(request):
+        ...
+
 .. _`Cache-Control spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
 
 Other optimizations