Fixed #21012 -- Thread-local caches, like databases.

docs/topics/cache.txt

@@ -703,7 +703,22 @@ pickling.)
 Accessing the cache
 -------------------
 
-.. function:: django.core.cache.get_cache(backend, **kwargs)
+.. versionadded:: 1.7
+
+You can access the caches configured in ``settings.CACHES`` through the
+dict-like ``django.core.cache.caches`` object. Repeated requests for the same
+alias will return the same object.
+
+    >>> from django.core.cache import caches
+    >>> cache1 = caches['myalias']
+    >>> cache2 = caches['myalias']
+    >>> cache1 is cache2
+    True
+
+If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
+
+The ``caches`` dict is thread aware, so a different instance of each alias will
+be returned for each thread.
 
 The cache module, ``django.core.cache``, has a ``cache`` object that's
 automatically created from the ``'default'`` entry in the :setting:`CACHES`
@@ -711,13 +726,43 @@ setting::
 
     >>> from django.core.cache import cache
 
-If you have multiple caches defined in :setting:`CACHES`, then you can use
-:func:`django.core.cache.get_cache` to retrieve a cache object for any key::
+This is a proxy object to caches['default']. It is provided for backward
+compatiblity.
+
+.. function:: django.core.cache.create_cache(backend, **kwargs)
+
+You can create caches from ad-hoc configurations using ``create_cache``.
+
+    >>> from django.core.cache import create_cache
+    # Create an instance of a specific backend
+    >>> cache = create_cache(
+        'django.core.cache.backends.memcached.MemcachedCache',
+        LOCATION='/tmp/memcached.sock'
+    )
+    # Create a separate copy of the 'default' cache:
+    >>> new_default = create_cache('default')
+    # Create a cache with the same config as 'default', but a different timeout
+    >>> cache2 = create_cache('default', TIMEOUT=1)
+
+This is guaranteed to always create a new instance.
+
+.. function:: django.core.cache.get_cache(backend, **kwargs)
+
+.. deprecated:: 1.7
+    This function has been deprecated in favour of ``caches`` and
+    ``create_cache``.
+
+Before Django 1.7 this was the only way to get a cache instance.  Now it acts
+as a wrapper to ``create_cache``, except in the case where it is passed only a
+configured alias, where it will return the cache from ``caches``::
 
     >>> from django.core.cache import get_cache
-    >>> cache = get_cache('alternate')
-
-If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
+    # Passes call to create_cache
+    >>> cache = get_cache('django.core.cache.backends.memcached.MemcachedCache', LOCATION='127.0.0.2')
+    # Creates a new cache based on the config in settings.CACHES['default']
+    >>> cache = get_cache('default', TIMEOUT=300)
+    # Returns instance from caches object
+    >>> cache = get_cache('default')
 
 
 Basic usage