Changeset 224

Timestamp:

07/19/05 15:49:07 (3 years ago)

Author:

adrian

Message:

Changed docs/cache to add docs for site-wide caching, via the cache middleware

Files:

• django/trunk/docs/cache.txt (modified) (4 diffs)

django/trunk/docs/cache.txt

@@ -5 +5 @@
-So, you got slashdotted.  Now what?
-
-
-
-
+
+
+
+
-
-Setting up the cache
@@ -13 +14 @@
-
-The cache framework is split into a set of "backends" that provide different
- There's a simple single-process memory cache 
-
-backend (by 
+There's a simple single-process memory cache (mostly
+
+
-
-Before using the cache, you'll need to tell Django which cache backend you'd
-; d
+. D
-
-; examples are
+. Examples:
-
-    ==============================  ===========================================
-    CACHE_BACKEND                   Explanation
-    ==============================  ===========================================
- 
+
-                                    on localhost port 11211.
-
- 
+
+
-                                    the same database/username as the rest of
-                                    the CMS, so only a table name is needed.)
-
+
-    simple:///                      A simple single-process memory cache; you
-                                    probably don't want to use this except for
- 
+
-                                    NOT threadsafe!
-    ==============================  ===========================================
-
-; these a
+ -- they'
-arguments are:
-
-         
- Defaults
-to 5 
-
-     
+
+Defaults to 5
+
+
+
-        For the simple and database backends, the maximum number of entries
-        allowed in the cache before it is cleaned.  Defaults to 300.
-
- 
- 
+
+
+
-        The actual percentage is 1/cull_percentage, so set cull_percentage=3 to
-        cull 1/3 of the entries when max_entries is reached.
-
+
-        A value of 0 for cull_percentage means that the entire cache will be
- 
+
-        at the expense of more cache misses.
-
+
-For example::
-
-    DB_CACHE = "memcached://127.0.0.1:11211/?timeout=60"
-    DB_CACHE = "db://tablename/?timeout=120&max_entries=500&cull_percentage=4"
-
- 
+
+
-arguments.
+
+The per-site cache
+==================
+
+Once the cache is set up, the simplest way to use the cache is to simply
+cache your entire site. Just add ``django.middleware.cache.CacheMiddleware``
+to your ``MIDDLEWARE_CLASSES`` setting, as in this example::
+
+    MIDDLEWARE_CLASSES = (
+        "django.middleware.common.CommonMiddleware",
+        "django.middleware.cache.CacheMiddleware",
+    )
+
+Then, add the following three required settings::
+
+* ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be
+  cached.
+* ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple
+  sites using the same Django installation, set this to the name of the site,
+  or some other string that is unique to this Django instance, to prevent key
+  collisions. Use an empty string if you don't care.
+* ``CACHE_MIDDLEWARE_GZIP`` -- Either ``True`` or ``False``. If this is
+  enabled, Django will gzip all content for users whose browsers support gzip
+  encoding. Using gzip adds a level of overhead to page requests, but the
+  overhead generally is cancelled out by the fact that gzipped pages are stored
+  in the cache. That means subsequent requests won't have the overhead of
+  zipping, and the cache will hold more pages because each one is smaller.
+
+Pages with GET or POST parameters won't be cached.
+
+The cache middleware also makes a few more optimizations:
+
+* Sets and deals with ``ETag`` headers.
+* Sets the ``Content-Length`` header.
+* Sets the ``Last-Modified`` header to the current date/time when a fresh
+  (uncached) version of the page is requested.
+
+It doesn't matter where in the middleware stack you put the cache middleware.
-
-The per-page cache
-==================
-
-
-
-
-for you.  Using it couldn't be easier
+
+
+
+to use
-
-    from django.views.decorators.cache import cache_page
-
+
-    def slashdot_this(request):
-        ...
-
-:
+
+
-
-Or, using Python 2.4's decorator syntax::
@@ -87 +126 @@
-        ...
-
- (t
-).
+. (T
+.)
-
-The low-level cache API
@@ -94 +133 @@
-
-There are times, however, that caching an entire rendered page doesn't gain
- We often find that we only need to cache a list of object IDs
-
-
-
+The Django developers have found it's only necessary to cache a
+
+
+of 
-
-almost shockingly 
+
-
-    # the cache module exports a cache object that's automatically
-    # created from the CACHE_BACKEND setting
-    >>> from django.core.cache import cache
-
+
-    # The basic interface is set(key, value, timeout_seconds) and get(key)
-    >>> cache.set('my_key', 'hello, world!', 30)
-    >>> cache.get('my_key')
-    'hello, world!'
-
-w
+
+W
-    >>> cache.get('my_key')
-    None
-
-
+
+()
-    >>> cache.get('my_key', 'has_expired')
-    'has_expired'
-
-there's also a get_many interface that only hits the cache once
-also, note that the timeout argument is optional and defaults
-to what 
+
+There's also a get_many() interface that only hits the cache once.
+Also, note that the timeout argument is optional and defaults to what
+
-    >>> cache.set('a', 1)
-    >>> cache.set('b', 2)
-    >>> cache.set('c', 3)
+
+    # get_many() returns a dictionary with all the keys you asked for that
+    # actually exist in the cache (and haven't expired).
-    >>> cache.get_many(['a', 'b', 'c'])
-    {'a': 1, 'b': 2, 'c': 3}
-
-
-
-
+
+
-    >>> cache.delete('a')
-
- There's
+
+There are
-use the cache for; you can store any object in the cache that can be pickled
-safely, although keys must be strings.
-
-.. _memcached: http://www.danga.com/memcached/
-