Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Updated docs to describe a simplified cache backend API.

  • Loading branch information...
commit 8e274f747a1f1c0c0e6c37873e29067f7fa022e8 1 parent ee7eb0f
@aaugustin aaugustin authored
View
8 django/core/cache/__init__.py
@@ -6,11 +6,9 @@
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.
"""
View
6 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
---
View
26 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``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
View
77 docs/topics/cache.txt
@@ -703,67 +703,50 @@ pickling.)
Accessing the cache
-------------------
-.. 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
+.. data:: django.core.cache.caches
-If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
+ .. versionadded:: 1.7
-The ``caches`` dict is thread aware, so a different instance of each alias will
-be returned for each thread.
+ 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.
-The cache module, ``django.core.cache``, has a ``cache`` object that's
-automatically created from the ``'default'`` entry in the :setting:`CACHES`
-setting::
+ >>> from django.core.cache import caches
+ >>> cache1 = caches['myalias']
+ >>> cache2 = caches['myalias']
+ >>> cache1 is cache2
+ True
- >>> from django.core.cache import cache
+ If the named key does not exist, ``InvalidCacheBackendError`` will be
+ raised.
-This is a proxy object to caches['default']. It is provided for backward
-compatiblity.
+ To provide thread-safety, a different instance of the cache backend will
+ be returned for each thread.
-.. function:: django.core.cache.create_cache(backend, **kwargs)
+.. data:: django.core.cache.cache
-You can create caches from ad-hoc configurations using ``create_cache``.
+ As a shortcut, the default cache is available as
+ ``django.core.cache.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)
+ >>> from django.core.cache import cache
-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``.
-
-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``::
+ .. deprecated:: 1.7
+ This function has been deprecated in favour of
+ :data:`~django.core.cache.caches`.
- >>> 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')
+ 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
-----------

0 comments on commit 8e274f7

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