[1.3.X] Fixed #15499 -- Ensure that cache control headers don't try to set public and private as a result of multiple calls to patch_cache_control with different arguments. Thanks to AndiDog for the report and patch.

Backport of r16657 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.3.X@16673 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 81d6baa50d..8ef4ea2f30 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -1062,6 +1062,28 @@ Django, use the ``cache_control`` view decorator. Example::
 This decorator takes care of sending out the appropriate HTTP header behind the
 scenes.
 
+Note that the cache control settings "private" and "public" are mutually
+exclusive. The decorator ensures that the "public" directive is removed if
+"private" should be set (and vice versa). An example use of the two directives
+would be a blog site that offers both private and public entries. Public
+entries may be cached on any shared cache. The following code uses
+``patch_cache_control``, the manual way to modify the cache control header
+(it is internally called by the ``cache_control`` decorator)::
+
+    from django.views.decorators.cache import patch_cache_control
+    from django.views.decorators.vary import vary_on_cookie
+
+    @vary_on_cookie
+    def list_blog_entries_view(request):
+        if request.user.is_anonymous():
+            response = render_only_public_entries()
+            patch_cache_control(response, public=True)
+        else:
+            response = render_private_and_public_entries(request.user)
+            patch_cache_control(response, private=True)
+
+        return response
+
 There are a few other ways to control cache parameters. For example, HTTP
 allows applications to do the following: