3 files changed, 60 insertions, 11 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 4080957c77..4c44c70501 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -114,7 +114,7 @@ these changes.
   no longer appears to be actively maintained & does not work on Python 3.
   You are advised to install `Pillow`_, which should be used instead.
 
-.. _`Pillow`: https://pypi.python.org/pypi/Pillow
+  .. _`Pillow`: https://pypi.python.org/pypi/Pillow
 
 * The following private APIs will be removed:
 
@@ -215,6 +215,9 @@ these changes.
 
 * The internal ``django.utils.functional.memoize`` will be removed.
 
+* ``django.core.cache.get_cache`` will be removed. Add suitable entries
+  to :setting:`CACHES` and use :data:`django.core.cache.caches` instead.
+
 2.0
 ---
 
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 749a843a5a..8272e246c6 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -269,6 +269,18 @@ Minor features
   allowing the ``published`` element to be included in the feed (which
   relies on ``pubdate``).
 
+Cache
+^^^^^
+
+* Access to caches configured in :setting:`CACHES` is now available via
+  :data:`django.core.cache.caches`. This dict-like object provides a different
+  instance per thread. It supersedes :func:`django.core.cache.get_cache` which
+  is now deprecated.
+
+* If you instanciate cache backends directly, be aware that they aren't
+  thread-safe any more, as :data:`django.core.cache.caches` now yields
+  differend instances per thread.
+
 Email
 ^^^^^
 
@@ -643,6 +655,12 @@ Miscellaneous
 Features deprecated in 1.7
 ==========================
 
+``django.core.cache.get_cache``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:func:`django.core.cache.get_cache` has been supplanted by
+:data:`django.core.cache.caches`.
+
 ``django.utils.dictconfig``/``django.utils.importlib``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index abf4946cb5..409bd42827 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -703,22 +703,50 @@ pickling.)
 Accessing the cache
 -------------------
 
-.. function:: django.core.cache.get_cache(backend, **kwargs)
+.. data:: django.core.cache.caches
 
-The cache module, ``django.core.cache``, has a ``cache`` object that's
-automatically created from the ``'default'`` entry in the :setting:`CACHES`
-setting::
+    .. versionadded:: 1.7
 
-    >>> from django.core.cache import cache
+    You can access the caches configured in the :setting:`CACHES` setting
+    through a dict-like object: ``django.core.cache.caches``. Repeated
+    requests for the same alias in the same thread 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.
+
+    To provide thread-safety, a different instance of the cache backend will
+    be returned for each thread.
 
-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::
+.. data:: django.core.cache.cache
+
+    As a shortcut, the default cache is available as
+    ``django.core.cache.cache``::
+
+        >>> from django.core.cache import cache
+
+    This object is equivalent to ``caches['default']``.
+
+.. function:: django.core.cache.get_cache(backend, **kwargs)
 
-    >>> from django.core.cache import get_cache
-    >>> cache = get_cache('alternate')
+    .. deprecated:: 1.7
+        This function has been deprecated in favour of
+        :data:`~django.core.cache.caches`.
 
-If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
+    Before Django 1.7 this function was the canonical way to obtain a cache
+    instance. It could also be used to create a new cache instance with a
+    different configuration.
 
+        >>> from django.core.cache import get_cache
+        >>> get_cache('default')
+        >>> get_cache('django.core.cache.backends.memcached.MemcachedCache', LOCATION='127.0.0.2')
+        >>> get_cache('default', TIMEOUT=300)
 
 Basic usage
 -----------