Fixed #11675 -- Added support for the PyLibMC cache library. In order to support this, and clean up some other 1.3 caching additions, this patch also includes some changes to the way caches are defined. This means you can now have multiple caches, in the same way you have multiple databases. A huge thanks to Jacob Burch for the work on the PyLibMC backend, and to Jannis for his work on the cache definition changes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15005 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 125 insertions, 25 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 3a7d987d44..e358c4264d 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -127,21 +127,63 @@ Default: Not defined
 The site-specific user profile model used by this site. See
 :ref:`auth-profiles`.
 
-.. setting:: CACHE_BACKEND
+.. setting:: CACHES
 
-CACHE_BACKEND
--------------
+CACHES
+------
 
-Default: ``'locmem://'``
+.. versionadded:: 1.3
 
-The cache backend to use. See :doc:`/topics/cache`.
+Default::
 
-.. setting:: CACHE_KEY_FUNCTION
+    {
+        'default': {
+            'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
+        }
+    }
 
-CACHE_KEY_FUNCTION
-------------------
+A dictionary containing the settings for all caches to be used with
+Django. It is a nested dictionary whose contents maps cache aliases
+to a dictionary containing the options for an individual cache.
 
-Default: ``None``
+The :setting:`CACHES` setting must configure a ``default`` cache;
+any number of additional caches may also be specified. If you
+are using a cache backend other than the local memory cache, or
+you need to define multiple caches, other options will be required.
+The following cache options are available.
+
+.. setting:: CACHES-BACKEND
+
+BACKEND
+~~~~~~~
+
+Default: ``''`` (Empty string)
+
+The cache backend to use. The built-in cache backends are:
+
+    * ``'django.core.cache.backends.db.DatabaseCache'``
+    * ``'django.core.cache.backends.dummy.DummyCache'``
+    * ``'django.core.cache.backends.filebased.FileBasedCache'``
+    * ``'django.core.cache.backends.locmem.LocMemCache'``
+    * ``'django.core.cache.backends.memcached.MemcachedCache'``
+    * ``'django.core.cache.backends.memcached.PyLibMCCache'``
+
+You can use a cache backend that doesn't ship with Django by setting
+:setting:`BACKEND <CACHE-BACKEND>` to a fully-qualified path of a cache
+backend class (i.e. ``mypackage.backends.whatever.WhateverCache``).
+Writing a whole new cache backend from scratch is left as an exercise
+to the reader; see the other backends for examples.
+
+.. note::
+    Prior to Django 1.3, you could use a URI based version of the backend
+    name to reference the built-in cache backends (e.g., you could use
+    ``'db://tablename'`` to refer to the database backend). This format has
+    been deprecated, and will be removed in Django 1.5.
+
+.. setting:: CACHES-KEY_FUNCTION
+
+KEY_FUNCTION
+~~~~~~~~~~~~
 
 A string containing a dotted path to a function that defines how to
 compose a prefix, version and key into a final cache key. The default
@@ -155,10 +197,10 @@ argument signature.
 
 See the :ref:`cache documentation <cache_key_transformation>` for more information.
 
-.. setting:: CACHE_KEY_PREFIX
+.. setting:: CACHES-KEY_PREFIX
 
-CACHE_KEY_PREFIX
-----------------
+KEY_PREFIX
+~~~~~~~~~~
 
 Default: ``''`` (Empty string)
 
@@ -167,6 +209,67 @@ all cache keys used by the Django server.
 
 See the :ref:`cache documentation <cache_key_prefixing>` for more information.
 
+.. setting:: CACHES-LOCATION
+
+LOCATION
+~~~~~~~~
+
+Default: ``''`` (Empty string)
+
+The location of the cache to use. This might be the directory for a
+file system cache, a host and port for a memcache server, or simply an
+identifying name for a local memory cache. e.g.::
+
+    CACHES = {
+        'default': {
+            'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
+            'LOCATION': '/var/tmp/django_cache',
+        }
+    }
+
+.. setting:: CACHES-OPTIONS
+
+OPTIONS
+~~~~~~~
+
+Default: None
+
+Extra parameters to pass to the cache backend. Available parameters
+vary depending on your cache backend.
+
+Some information on available parameters can be found in the
+:doc:`Cache Backends </topics/cache>` documentation. For more information,
+consult your backend module's own documentation.
+
+.. setting:: CACHES-TIMEOUT
+
+TIMEOUT
+~~~~~~~
+
+Default: 300
+
+The number of seconds before a cache entry is considered stale.
+
+.. setting:: CACHES-VERSION
+
+VERSION
+~~~~~~~
+
+Default: ``1``
+
+The default version number for cache keys generated by the Django server.
+
+See the :ref:`cache documentation <cache_versioning>` for more information.
+
+.. setting:: CACHE_MIDDLEWARE_ALIAS
+
+CACHE_MIDDLEWARE_ALIAS
+----------------------
+
+Default: ``default``
+
+The cache connection to use for the cache middleware.
+
 .. setting:: CACHE_MIDDLEWARE_ANONYMOUS_ONLY
 
 CACHE_MIDDLEWARE_ANONYMOUS_ONLY
@@ -206,18 +309,6 @@ The default number of seconds to cache a page when the caching middleware or
 
 See :doc:`/topics/cache`.
 
-.. setting:: CACHE_VERSION
-
-CACHE_VERSION
--------------
-
-Default: ``1``
-
-The default version number for cache keys generated by the Django server.
-
-See the :ref:`cache documentation <cache_versioning>` for more information.
-
-
 .. setting:: CSRF_COOKIE_DOMAIN
 
 CSRF_COOKIE_DOMAIN
@@ -293,7 +384,7 @@ SQLite. This can be configured using the following::
 For other database backends, or more complex SQLite configurations, other options
 will be required. The following inner options are available.
 
-.. setting:: ENGINE
+.. setting:: DATABASE-ENGINE
 
 ENGINE
 ~~~~~~
@@ -1896,6 +1987,15 @@ See :tfilter:`allowed date format strings <date>`. See also ``DATE_FORMAT``,
 Deprecated settings
 ===================
 
+.. setting:: CACHE_BACKEND
+
+CACHE_BACKEND
+-------------
+
+.. deprecated:: 1.3
+   This setting has been replaced by :setting:`BACKEND <CACHES-BACKEND>` in
+   :setting:`CACHES`.
+
 .. setting:: DATABASE_ENGINE
 
 DATABASE_ENGINE