/bangkokhotel/lib/python2.5/site-packages/django/utils/cache.py

https://bitbucket.org/luisrodriguez/bangkokhotel · Python · 252 lines · 164 code · 21 blank · 67 comment · 46 complexity · d4c8f2681ffdebdc93f1b8428a00379e MD5 · raw file

  1. """
  2. This module contains helper functions for controlling caching. It does so by
  3. managing the "Vary" header of responses. It includes functions to patch the
  4. header of response objects directly and decorators that change functions to do
  5. that header-patching themselves.
  6. For information on the Vary header, see:
  7. http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
  8. Essentially, the "Vary" HTTP header defines which headers a cache should take
  9. into account when building its cache key. Requests with the same path but
  10. different header content for headers named in "Vary" need to get different
  11. cache keys to prevent delivery of wrong content.
  12. An example: i18n middleware would need to distinguish caches by the
  13. "Accept-language" header.
  14. """
  15. import hashlib
  16. import re
  17. import time
  18. from django.conf import settings
  19. from django.core.cache import get_cache
  20. from django.utils.encoding import smart_str, iri_to_uri, force_unicode
  21. from django.utils.http import http_date
  22. from django.utils.timezone import get_current_timezone_name
  23. from django.utils.translation import get_language
  24. cc_delim_re = re.compile(r'\s*,\s*')
  25. def patch_cache_control(response, **kwargs):
  26. """
  27. This function patches the Cache-Control header by adding all
  28. keyword arguments to it. The transformation is as follows:
  29. * All keyword parameter names are turned to lowercase, and underscores
  30. are converted to hyphens.
  31. * If the value of a parameter is True (exactly True, not just a
  32. true value), only the parameter name is added to the header.
  33. * All other parameters are added with their value, after applying
  34. str() to it.
  35. """
  36. def dictitem(s):
  37. t = s.split('=', 1)
  38. if len(t) > 1:
  39. return (t[0].lower(), t[1])
  40. else:
  41. return (t[0].lower(), True)
  42. def dictvalue(t):
  43. if t[1] is True:
  44. return t[0]
  45. else:
  46. return t[0] + '=' + smart_str(t[1])
  47. if response.has_header('Cache-Control'):
  48. cc = cc_delim_re.split(response['Cache-Control'])
  49. cc = dict([dictitem(el) for el in cc])
  50. else:
  51. cc = {}
  52. # If there's already a max-age header but we're being asked to set a new
  53. # max-age, use the minimum of the two ages. In practice this happens when
  54. # a decorator and a piece of middleware both operate on a given view.
  55. if 'max-age' in cc and 'max_age' in kwargs:
  56. kwargs['max_age'] = min(cc['max-age'], kwargs['max_age'])
  57. # Allow overriding private caching and vice versa
  58. if 'private' in cc and 'public' in kwargs:
  59. del cc['private']
  60. elif 'public' in cc and 'private' in kwargs:
  61. del cc['public']
  62. for (k, v) in kwargs.items():
  63. cc[k.replace('_', '-')] = v
  64. cc = ', '.join([dictvalue(el) for el in cc.items()])
  65. response['Cache-Control'] = cc
  66. def get_max_age(response):
  67. """
  68. Returns the max-age from the response Cache-Control header as an integer
  69. (or ``None`` if it wasn't found or wasn't an integer.
  70. """
  71. if not response.has_header('Cache-Control'):
  72. return
  73. cc = dict([_to_tuple(el) for el in
  74. cc_delim_re.split(response['Cache-Control'])])
  75. if 'max-age' in cc:
  76. try:
  77. return int(cc['max-age'])
  78. except (ValueError, TypeError):
  79. pass
  80. def _set_response_etag(response):
  81. response['ETag'] = '"%s"' % hashlib.md5(response.content).hexdigest()
  82. return response
  83. def patch_response_headers(response, cache_timeout=None):
  84. """
  85. Adds some useful headers to the given HttpResponse object:
  86. ETag, Last-Modified, Expires and Cache-Control
  87. Each header is only added if it isn't already set.
  88. cache_timeout is in seconds. The CACHE_MIDDLEWARE_SECONDS setting is used
  89. by default.
  90. """
  91. if cache_timeout is None:
  92. cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
  93. if cache_timeout < 0:
  94. cache_timeout = 0 # Can't have max-age negative
  95. if settings.USE_ETAGS and not response.has_header('ETag'):
  96. if hasattr(response, 'render') and callable(response.render):
  97. response.add_post_render_callback(_set_response_etag)
  98. else:
  99. response = _set_response_etag(response)
  100. if not response.has_header('Last-Modified'):
  101. response['Last-Modified'] = http_date()
  102. if not response.has_header('Expires'):
  103. response['Expires'] = http_date(time.time() + cache_timeout)
  104. patch_cache_control(response, max_age=cache_timeout)
  105. def add_never_cache_headers(response):
  106. """
  107. Adds headers to a response to indicate that a page should never be cached.
  108. """
  109. patch_response_headers(response, cache_timeout=-1)
  110. def patch_vary_headers(response, newheaders):
  111. """
  112. Adds (or updates) the "Vary" header in the given HttpResponse object.
  113. newheaders is a list of header names that should be in "Vary". Existing
  114. headers in "Vary" aren't removed.
  115. """
  116. # Note that we need to keep the original order intact, because cache
  117. # implementations may rely on the order of the Vary contents in, say,
  118. # computing an MD5 hash.
  119. if response.has_header('Vary'):
  120. vary_headers = cc_delim_re.split(response['Vary'])
  121. else:
  122. vary_headers = []
  123. # Use .lower() here so we treat headers as case-insensitive.
  124. existing_headers = set([header.lower() for header in vary_headers])
  125. additional_headers = [newheader for newheader in newheaders
  126. if newheader.lower() not in existing_headers]
  127. response['Vary'] = ', '.join(vary_headers + additional_headers)
  128. def has_vary_header(response, header_query):
  129. """
  130. Checks to see if the response has a given header name in its Vary header.
  131. """
  132. if not response.has_header('Vary'):
  133. return False
  134. vary_headers = cc_delim_re.split(response['Vary'])
  135. existing_headers = set([header.lower() for header in vary_headers])
  136. return header_query.lower() in existing_headers
  137. def _i18n_cache_key_suffix(request, cache_key):
  138. """If necessary, adds the current locale or time zone to the cache key."""
  139. if settings.USE_I18N or settings.USE_L10N:
  140. # first check if LocaleMiddleware or another middleware added
  141. # LANGUAGE_CODE to request, then fall back to the active language
  142. # which in turn can also fall back to settings.LANGUAGE_CODE
  143. cache_key += '.%s' % getattr(request, 'LANGUAGE_CODE', get_language())
  144. if settings.USE_TZ:
  145. # The datetime module doesn't restrict the output of tzname().
  146. # Windows is known to use non-standard, locale-dependant names.
  147. # User-defined tzinfo classes may return absolutely anything.
  148. # Hence this paranoid conversion to create a valid cache key.
  149. tz_name = force_unicode(get_current_timezone_name(), errors='ignore')
  150. cache_key += '.%s' % tz_name.encode('ascii', 'ignore').replace(' ', '_')
  151. return cache_key
  152. def _generate_cache_key(request, method, headerlist, key_prefix):
  153. """Returns a cache key from the headers given in the header list."""
  154. ctx = hashlib.md5()
  155. for header in headerlist:
  156. value = request.META.get(header, None)
  157. if value is not None:
  158. ctx.update(value)
  159. path = hashlib.md5(iri_to_uri(request.get_full_path()))
  160. cache_key = 'views.decorators.cache.cache_page.%s.%s.%s.%s' % (
  161. key_prefix, method, path.hexdigest(), ctx.hexdigest())
  162. return _i18n_cache_key_suffix(request, cache_key)
  163. def _generate_cache_header_key(key_prefix, request):
  164. """Returns a cache key for the header cache."""
  165. path = hashlib.md5(iri_to_uri(request.get_full_path()))
  166. cache_key = 'views.decorators.cache.cache_header.%s.%s' % (
  167. key_prefix, path.hexdigest())
  168. return _i18n_cache_key_suffix(request, cache_key)
  169. def get_cache_key(request, key_prefix=None, method='GET', cache=None):
  170. """
  171. Returns a cache key based on the request path and query. It can be used
  172. in the request phase because it pulls the list of headers to take into
  173. account from the global path registry and uses those to build a cache key
  174. to check against.
  175. If there is no headerlist stored, the page needs to be rebuilt, so this
  176. function returns None.
  177. """
  178. if key_prefix is None:
  179. key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
  180. cache_key = _generate_cache_header_key(key_prefix, request)
  181. if cache is None:
  182. cache = get_cache(settings.CACHE_MIDDLEWARE_ALIAS)
  183. headerlist = cache.get(cache_key, None)
  184. if headerlist is not None:
  185. return _generate_cache_key(request, method, headerlist, key_prefix)
  186. else:
  187. return None
  188. def learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None):
  189. """
  190. Learns what headers to take into account for some request path from the
  191. response object. It stores those headers in a global path registry so that
  192. later access to that path will know what headers to take into account
  193. without building the response object itself. The headers are named in the
  194. Vary header of the response, but we want to prevent response generation.
  195. The list of headers to use for cache key generation is stored in the same
  196. cache as the pages themselves. If the cache ages some data out of the
  197. cache, this just means that we have to build the response once to get at
  198. the Vary header and so at the list of headers to use for the cache key.
  199. """
  200. if key_prefix is None:
  201. key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
  202. if cache_timeout is None:
  203. cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
  204. cache_key = _generate_cache_header_key(key_prefix, request)
  205. if cache is None:
  206. cache = get_cache(settings.CACHE_MIDDLEWARE_ALIAS)
  207. if response.has_header('Vary'):
  208. headerlist = ['HTTP_'+header.upper().replace('-', '_')
  209. for header in cc_delim_re.split(response['Vary'])]
  210. cache.set(cache_key, headerlist, cache_timeout)
  211. return _generate_cache_key(request, request.method, headerlist, key_prefix)
  212. else:
  213. # if there is no Vary header, we still need a cache key
  214. # for the request.get_full_path()
  215. cache.set(cache_key, [], cache_timeout)
  216. return _generate_cache_key(request, request.method, [], key_prefix)
  217. def _to_tuple(s):
  218. t = s.split('=',1)
  219. if len(t) == 2:
  220. return t[0].lower(), t[1]
  221. return t[0].lower(), True