--- a/app/django/middleware/cache.py Tue Oct 14 12:36:55 2008 +0000
+++ b/app/django/middleware/cache.py Tue Oct 14 16:00:59 2008 +0000
@@ -1,50 +1,117 @@
+"""
+Cache middleware. If enabled, each Django-powered page will be cached based on
+URL. The canonical way to enable cache middleware is to set
+``UpdateCacheMiddleware`` as your first piece of middleware, and
+``FetchFromCacheMiddleware`` as the last::
+
+ MIDDLEWARE_CLASSES = [
+ 'django.middleware.cache.UpdateCacheMiddleware',
+ ...
+ 'django.middleware.cache.FetchFromCacheMiddleware'
+ ]
+
+This is counter-intuitive, but correct: ``UpdateCacheMiddleware`` needs to run
+last during the response phase, which processes middleware bottom-up;
+``FetchFromCacheMiddleware`` needs to run last during the request phase, which
+processes middleware top-down.
+
+The single-class ``CacheMiddleware`` can be used for some simple sites.
+However, if any other piece of middleware needs to affect the cache key, you'll
+need to use the two-part ``UpdateCacheMiddleware`` and
+``FetchFromCacheMiddleware``. This'll most often happen when you're using
+Django's ``LocaleMiddleware``.
+
+More details about how the caching works:
+
+* Only parameter-less GET or HEAD-requests with status code 200 are cached.
+
+* The number of seconds each page is stored for is set by the "max-age" section
+ of the response's "Cache-Control" header, falling back to the
+ CACHE_MIDDLEWARE_SECONDS setting if the section was not found.
+
+* If CACHE_MIDDLEWARE_ANONYMOUS_ONLY is set to True, only anonymous requests
+ (i.e., those not made by a logged-in user) will be cached. This is a simple
+ and effective way of avoiding the caching of the Django admin (and any other
+ user-specific content).
+
+* This middleware expects that a HEAD request is answered with a response
+ exactly like the corresponding GET request.
+
+* When a hit occurs, a shallow copy of the original response object is returned
+ from process_request.
+
+* Pages will be cached based on the contents of the request headers listed in
+ the response's "Vary" header.
+
+* This middleware also sets ETag, Last-Modified, Expires and Cache-Control
+ headers on the response object.
+
+"""
+
from django.conf import settings
from django.core.cache import cache
from django.utils.cache import get_cache_key, learn_cache_key, patch_response_headers, get_max_age
-class CacheMiddleware(object):
+class UpdateCacheMiddleware(object):
"""
- Cache middleware. If this is enabled, each Django-powered page will be
- cached (based on URLs).
-
- Only parameter-less GET or HEAD-requests with status code 200 are cached.
+ Response-phase cache middleware that updates the cache if the response is
+ cacheable.
- The number of seconds each page is stored for is set by the
- "max-age" section of the response's "Cache-Control" header, falling back to
- the CACHE_MIDDLEWARE_SECONDS setting if the section was not found.
-
- If CACHE_MIDDLEWARE_ANONYMOUS_ONLY is set to True, only anonymous requests
- (i.e., those not made by a logged-in user) will be cached. This is a
- simple and effective way of avoiding the caching of the Django admin (and
- any other user-specific content).
-
- This middleware expects that a HEAD request is answered with a response
- exactly like the corresponding GET request.
+ Must be used as part of the two-part update/fetch cache middleware.
+ UpdateCacheMiddleware must be the first piece of middleware in
+ MIDDLEWARE_CLASSES so that it'll get called last during the response phase.
+ """
+ def __init__(self):
+ self.cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
+ self.key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
+ self.cache_anonymous_only = getattr(settings, 'CACHE_MIDDLEWARE_ANONYMOUS_ONLY', False)
- When a hit occurs, a shallow copy of the original response object is
- returned from process_request.
+ def process_response(self, request, response):
+ """Sets the cache, if needed."""
+ if not hasattr(request, '_cache_update_cache') or not request._cache_update_cache:
+ # We don't need to update the cache, just return.
+ return response
+ if request.method != 'GET':
+ # This is a stronger requirement than above. It is needed
+ # because of interactions between this middleware and the
+ # HTTPMiddleware, which throws the body of a HEAD-request
+ # away before this middleware gets a chance to cache it.
+ return response
+ if not response.status_code == 200:
+ return response
+ # Try to get the timeout from the "max-age" section of the "Cache-
+ # Control" header before reverting to using the default cache_timeout
+ # length.
+ timeout = get_max_age(response)
+ if timeout == None:
+ timeout = self.cache_timeout
+ elif timeout == 0:
+ # max-age was set to 0, don't bother caching.
+ return response
+ patch_response_headers(response, timeout)
+ if timeout:
+ cache_key = learn_cache_key(request, response, timeout, self.key_prefix)
+ cache.set(cache_key, response, timeout)
+ return response
- Pages will be cached based on the contents of the request headers
- listed in the response's "Vary" header. This means that pages shouldn't
- change their "Vary" header.
-
- This middleware also sets ETag, Last-Modified, Expires and Cache-Control
- headers on the response object.
+class FetchFromCacheMiddleware(object):
"""
- def __init__(self, cache_timeout=None, key_prefix=None, cache_anonymous_only=None):
- self.cache_timeout = cache_timeout
- if cache_timeout is None:
- self.cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
- self.key_prefix = key_prefix
- if key_prefix is None:
- self.key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
- if cache_anonymous_only is None:
- self.cache_anonymous_only = getattr(settings, 'CACHE_MIDDLEWARE_ANONYMOUS_ONLY', False)
- else:
- self.cache_anonymous_only = cache_anonymous_only
+ Request-phase cache middleware that fetches a page from the cache.
+
+ Must be used as part of the two-part update/fetch cache middleware.
+ FetchFromCacheMiddleware must be the last piece of middleware in
+ MIDDLEWARE_CLASSES so that it'll get called last during the request phase.
+ """
+ def __init__(self):
+ self.cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
+ self.key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
+ self.cache_anonymous_only = getattr(settings, 'CACHE_MIDDLEWARE_ANONYMOUS_ONLY', False)
def process_request(self, request):
- "Checks whether the page is already cached and returns the cached version if available."
+ """
+ Checks whether the page is already cached and returns the cached
+ version if available.
+ """
if self.cache_anonymous_only:
assert hasattr(request, 'user'), "The Django cache middleware with CACHE_MIDDLEWARE_ANONYMOUS_ONLY=True requires authentication middleware to be installed. Edit your MIDDLEWARE_CLASSES setting to insert 'django.contrib.auth.middleware.AuthenticationMiddleware' before the CacheMiddleware."
@@ -69,29 +136,21 @@
request._cache_update_cache = False
return response
- def process_response(self, request, response):
- "Sets the cache, if needed."
- if not hasattr(request, '_cache_update_cache') or not request._cache_update_cache:
- # We don't need to update the cache, just return.
- return response
- if request.method != 'GET':
- # This is a stronger requirement than above. It is needed
- # because of interactions between this middleware and the
- # HTTPMiddleware, which throws the body of a HEAD-request
- # away before this middleware gets a chance to cache it.
- return response
- if not response.status_code == 200:
- return response
- # Try to get the timeout from the "max-age" section of the "Cache-
- # Control" header before reverting to using the default cache_timeout
- # length.
- timeout = get_max_age(response)
- if timeout == None:
- timeout = self.cache_timeout
- elif timeout == 0:
- # max-age was set to 0, don't bother caching.
- return response
- patch_response_headers(response, timeout)
- cache_key = learn_cache_key(request, response, timeout, self.key_prefix)
- cache.set(cache_key, response, timeout)
- return response
+class CacheMiddleware(UpdateCacheMiddleware, FetchFromCacheMiddleware):
+ """
+ Cache middleware that provides basic behavior for many simple sites.
+
+ Also used as the hook point for the cache decorator, which is generated
+ using the decorator-from-middleware utility.
+ """
+ def __init__(self, cache_timeout=None, key_prefix=None, cache_anonymous_only=None):
+ self.cache_timeout = cache_timeout
+ if cache_timeout is None:
+ self.cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
+ self.key_prefix = key_prefix
+ if key_prefix is None:
+ self.key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
+ if cache_anonymous_only is None:
+ self.cache_anonymous_only = getattr(settings, 'CACHE_MIDDLEWARE_ANONYMOUS_ONLY', False)
+ else:
+ self.cache_anonymous_only = cache_anonymous_only