diff --git a/django/core/cache/__init__.py b/django/core/cache/__init__.py index 8e60c42633..ec32a44d6c 100644 --- a/django/core/cache/__init__.py +++ b/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. """ diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 7651d6748a..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,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 --- diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 3381c39e12..8272e246c6 100644 --- a/docs/releases/1.7.txt +++ b/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`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 86b0f28fa8..409bd42827 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -703,67 +703,50 @@ 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 - >>> from django.core.cache import caches - >>> cache1 = caches['myalias'] - >>> cache2 = caches['myalias'] - >>> cache1 is cache2 - True + 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. -If the named key does not exist, ``InvalidCacheBackendError`` will be raised. + >>> from django.core.cache import caches + >>> cache1 = caches['myalias'] + >>> cache2 = caches['myalias'] + >>> cache1 is cache2 + True -The ``caches`` dict is thread aware, so a different instance of each alias will -be returned for each thread. + If the named key does not exist, ``InvalidCacheBackendError`` will be + raised. -The cache module, ``django.core.cache``, has a ``cache`` object that's -automatically created from the ``'default'`` entry in the :setting:`CACHES` -setting:: + To provide thread-safety, a different instance of the cache backend will + be returned for each thread. - >>> from django.core.cache import cache +.. data:: django.core.cache.cache -This is a proxy object to caches['default']. It is provided for backward -compatiblity. + As a shortcut, the default cache is available as + ``django.core.cache.cache``:: -.. function:: django.core.cache.create_cache(backend, **kwargs) + >>> from django.core.cache import cache -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``:: - - >>> 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 -----------