Updated docs to describe a simplified cache backend API.

django/core/cache/__init__.py

@@ -6,11 +6,9 @@ In a nutshell, a cache is a set of values -- which can be any object that
 may be pickled -- identified by string keys.  For the complete API, see
 the abstract BaseCache class in django.core.cache.backends.base.
 
-Client code should not access a cache backend directly; instead it should
-either use the "cache" variable made available here, or it should use the
-get_cache() function made available here. get_cache() takes a CACHES alias or a
-backend path and config parameters, and returns an instance of a backend cache
-class.
+Client code should use the `cache` variable defined here to access the default
+cache backend and look up non-default cache backends in the `caches` dict-like
+object.
 
 See docs/topics/cache.txt for information on the public API.
 """

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,8 +215,8 @@ these changes.
 
 * The internal ``django.utils.functional.memoize`` will be removed.
 
-* ``get_cache`` from django.core.cache will be removed.  Instead, use
-  ``create_cache`` or  ``caches``, depending on your need.
+* ``django.core.cache.get_cache`` will be removed. Add suitable entries
+  to :setting:`CACHES` and use :data:`django.core.cache.caches` instead.
 
 2.0
 ---

docs/releases/1.7.txt

@@ -272,22 +272,14 @@ Minor features
 Cache
 ^^^^^
 
-* Access to caches configured in ``settings.CACHES`` is now available via
-  ``django.core.cache.caches``.  This will now return a different instance per
-  thread.
+* 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.
 
-* A new function ``django.core.cache.create_cache`` has been added to make it
-  clearer what's happening.  ``django.core.cache.get_cache`` will call this
-  if it's passed anything other than just a cache config alias.
-
-* ``django.core.cache.get_cache`` has been deprecated.  Use
-  ``django.core.cache.caches`` to access caches configurd in
-  ``settings.CACHES``, or ``django.core.cache.create_cache`` to create ad-hoc
-  instances.
-
-* All thread safety in cache backends has been removed, as
-  ``django.core.cache.caches`` now yields differend backend instances per
-   thread.
+* 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
 ^^^^^
@@ -666,8 +658,8 @@ Features deprecated in 1.7
 ``django.core.cache.get_cache``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``django.core.cache.get_cache`` has been supplanted by
-``django.core.cache.caches`` and ``django.core.cache.create_cache``.
+:func:`django.core.cache.get_cache` has been supplanted by
+:data:`django.core.cache.caches`.
 
 ``django.utils.dictconfig``/``django.utils.importlib``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/topics/cache.txt

@@ -703,11 +703,14 @@ pickling.)
 Accessing the cache
 -------------------
 
-.. versionadded:: 1.7
+.. data:: django.core.cache.caches
 
-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.
+    .. versionadded:: 1.7
+
+    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']
@@ -715,55 +718,35 @@ alias will return the same object.
         >>> cache1 is cache2
         True
 
-If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
+    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.
+    To provide thread-safety, a different instance of the cache backend 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`
-setting::
+.. 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 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.
+    This object is equivalent to ``caches['default']``.
 
 .. function:: django.core.cache.get_cache(backend, **kwargs)
 
-.. deprecated:: 1.7
-    This function has been deprecated in favour of ``caches`` and
-    ``create_cache``.
+    .. deprecated:: 1.7
+        This function has been deprecated in favour of
+        :data:`~django.core.cache.caches`.
 
-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``::
+    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
-    # 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')
-
+        >>> get_cache('default')
+        >>> get_cache('django.core.cache.backends.memcached.MemcachedCache', LOCATION='127.0.0.2')
+        >>> get_cache('default', TIMEOUT=300)
 
 Basic usage
 -----------