Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updated docs to describe a simplified cache backend API.

  • Loading branch information...
commit 8e274f747a1f1c0c0e6c37873e29067f7fa022e8 1 parent ee7eb0f
Aymeric Augustin authored November 23, 2013
8  django/core/cache/__init__.py
@@ -6,11 +6,9 @@
6 6
 may be pickled -- identified by string keys.  For the complete API, see
7 7
 the abstract BaseCache class in django.core.cache.backends.base.
8 8
 
9  
-Client code should not access a cache backend directly; instead it should
10  
-either use the "cache" variable made available here, or it should use the
11  
-get_cache() function made available here. get_cache() takes a CACHES alias or a
12  
-backend path and config parameters, and returns an instance of a backend cache
13  
-class.
  9
+Client code should use the `cache` variable defined here to access the default
  10
+cache backend and look up non-default cache backends in the `caches` dict-like
  11
+object.
14 12
 
15 13
 See docs/topics/cache.txt for information on the public API.
16 14
 """
6  docs/internals/deprecation.txt
@@ -114,7 +114,7 @@ these changes.
114 114
   no longer appears to be actively maintained & does not work on Python 3.
115 115
   You are advised to install `Pillow`_, which should be used instead.
116 116
 
117  
-.. _`Pillow`: https://pypi.python.org/pypi/Pillow
  117
+  .. _`Pillow`: https://pypi.python.org/pypi/Pillow
118 118
 
119 119
 * The following private APIs will be removed:
120 120
 
@@ -215,8 +215,8 @@ these changes.
215 215
 
216 216
 * The internal ``django.utils.functional.memoize`` will be removed.
217 217
 
218  
-* ``get_cache`` from django.core.cache will be removed.  Instead, use
219  
-  ``create_cache`` or  ``caches``, depending on your need.
  218
+* ``django.core.cache.get_cache`` will be removed. Add suitable entries
  219
+  to :setting:`CACHES` and use :data:`django.core.cache.caches` instead.
220 220
 
221 221
 2.0
222 222
 ---
26  docs/releases/1.7.txt
@@ -272,22 +272,14 @@ Minor features
272 272
 Cache
273 273
 ^^^^^
274 274
 
275  
-* Access to caches configured in ``settings.CACHES`` is now available via
276  
-  ``django.core.cache.caches``.  This will now return a different instance per
277  
-  thread.
  275
+* Access to caches configured in :setting:`CACHES` is now available via
  276
+  :data:`django.core.cache.caches`. This dict-like object provides a different
  277
+  instance per thread. It supersedes :func:`django.core.cache.get_cache` which
  278
+  is now deprecated.
278 279
 
279  
-* A new function ``django.core.cache.create_cache`` has been added to make it
280  
-  clearer what's happening.  ``django.core.cache.get_cache`` will call this
281  
-  if it's passed anything other than just a cache config alias.
282  
-
283  
-* ``django.core.cache.get_cache`` has been deprecated.  Use
284  
-  ``django.core.cache.caches`` to access caches configurd in
285  
-  ``settings.CACHES``, or ``django.core.cache.create_cache`` to create ad-hoc
286  
-  instances.
287  
-
288  
-* All thread safety in cache backends has been removed, as
289  
-  ``django.core.cache.caches`` now yields differend backend instances per
290  
-   thread.
  280
+* If you instanciate cache backends directly, be aware that they aren't
  281
+  thread-safe any more, as :data:`django.core.cache.caches` now yields
  282
+  differend instances per thread.
291 283
 
292 284
 Email
293 285
 ^^^^^
@@ -666,8 +658,8 @@ Features deprecated in 1.7
666 658
 ``django.core.cache.get_cache``
667 659
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
668 660
 
669  
-``django.core.cache.get_cache`` has been supplanted by
670  
-``django.core.cache.caches`` and ``django.core.cache.create_cache``.
  661
+:func:`django.core.cache.get_cache` has been supplanted by
  662
+:data:`django.core.cache.caches`.
671 663
 
672 664
 ``django.utils.dictconfig``/``django.utils.importlib``
673 665
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77  docs/topics/cache.txt
@@ -703,67 +703,50 @@ pickling.)
703 703
 Accessing the cache
704 704
 -------------------
705 705
 
706  
-.. versionadded:: 1.7
707  
-
708  
-You can access the caches configured in ``settings.CACHES`` through the
709  
-dict-like ``django.core.cache.caches`` object. Repeated requests for the same
710  
-alias will return the same object.
711  
-
712  
-    >>> from django.core.cache import caches
713  
-    >>> cache1 = caches['myalias']
714  
-    >>> cache2 = caches['myalias']
715  
-    >>> cache1 is cache2
716  
-    True
  706
+.. data:: django.core.cache.caches
717 707
 
718  
-If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
  708
+    .. versionadded:: 1.7
719 709
 
720  
-The ``caches`` dict is thread aware, so a different instance of each alias will
721  
-be returned for each thread.
  710
+    You can access the caches configured in the :setting:`CACHES` setting
  711
+    through a dict-like object: ``django.core.cache.caches``. Repeated
  712
+    requests for the same alias in the same thread will return the same
  713
+    object.
722 714
 
723  
-The cache module, ``django.core.cache``, has a ``cache`` object that's
724  
-automatically created from the ``'default'`` entry in the :setting:`CACHES`
725  
-setting::
  715
+        >>> from django.core.cache import caches
  716
+        >>> cache1 = caches['myalias']
  717
+        >>> cache2 = caches['myalias']
  718
+        >>> cache1 is cache2
  719
+        True
726 720
 
727  
-    >>> from django.core.cache import cache
  721
+    If the named key does not exist, ``InvalidCacheBackendError`` will be
  722
+    raised.
728 723
 
729  
-This is a proxy object to caches['default']. It is provided for backward
730  
-compatiblity.
  724
+    To provide thread-safety, a different instance of the cache backend will
  725
+    be returned for each thread.
731 726
 
732  
-.. function:: django.core.cache.create_cache(backend, **kwargs)
  727
+.. data:: django.core.cache.cache
733 728
 
734  
-You can create caches from ad-hoc configurations using ``create_cache``.
  729
+    As a shortcut, the default cache is available as
  730
+    ``django.core.cache.cache``::
735 731
 
736  
-    >>> from django.core.cache import create_cache
737  
-    # Create an instance of a specific backend
738  
-    >>> cache = create_cache(
739  
-        'django.core.cache.backends.memcached.MemcachedCache',
740  
-        LOCATION='/tmp/memcached.sock'
741  
-    )
742  
-    # Create a separate copy of the 'default' cache:
743  
-    >>> new_default = create_cache('default')
744  
-    # Create a cache with the same config as 'default', but a different timeout
745  
-    >>> cache2 = create_cache('default', TIMEOUT=1)
  732
+        >>> from django.core.cache import cache
746 733
 
747  
-This is guaranteed to always create a new instance.
  734
+    This object is equivalent to ``caches['default']``.
748 735
 
749 736
 .. function:: django.core.cache.get_cache(backend, **kwargs)
750 737
 
751  
-.. deprecated:: 1.7
752  
-    This function has been deprecated in favour of ``caches`` and
753  
-    ``create_cache``.
754  
-
755  
-Before Django 1.7 this was the only way to get a cache instance.  Now it acts
756  
-as a wrapper to ``create_cache``, except in the case where it is passed only a
757  
-configured alias, where it will return the cache from ``caches``::
  738
+    .. deprecated:: 1.7
  739
+        This function has been deprecated in favour of
  740
+        :data:`~django.core.cache.caches`.
758 741
 
759  
-    >>> from django.core.cache import get_cache
760  
-    # Passes call to create_cache
761  
-    >>> cache = get_cache('django.core.cache.backends.memcached.MemcachedCache', LOCATION='127.0.0.2')
762  
-    # Creates a new cache based on the config in settings.CACHES['default']
763  
-    >>> cache = get_cache('default', TIMEOUT=300)
764  
-    # Returns instance from caches object
765  
-    >>> cache = get_cache('default')
  742
+    Before Django 1.7 this function was the canonical way to obtain a cache
  743
+    instance. It could also be used to create a new cache instance with a
  744
+    different configuration.
766 745
 
  746
+        >>> from django.core.cache import get_cache
  747
+        >>> get_cache('default')
  748
+        >>> get_cache('django.core.cache.backends.memcached.MemcachedCache', LOCATION='127.0.0.2')
  749
+        >>> get_cache('default', TIMEOUT=300)
767 750
 
768 751
 Basic usage
769 752
 -----------

0 notes on commit 8e274f7

Please sign in to comment.
Something went wrong with that request. Please try again.