← Back to branch summary

~ubuntu-branches/ubuntu/saucy/python-django/saucy-updates

« back to all changes in this revision

Viewing changes to docs/topics/cache.txt

  • Committer: Package Import Robot
  • Author(s): Luke Faraone, Jakub Wilk, Luke Faraone
  • Date: 2013-05-09 15:10:47 UTC
  • mfrom: (1.1.21) (4.4.27 sid)
  • Revision ID: package-import@ubuntu.com-20130509151047-aqv8d71oj9wvcv8c
Tags: 1.5.1-2
[ Jakub Wilk ]
* Use canonical URIs for Vcs-* fields.

[ Luke Faraone ]
* Upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/cache.txt
51
51
settings file. Here's an explanation of all available values for
52
52
:setting:`CACHES`.
53
53
 
54
 
.. versionchanged:: 1.3
55
 
    The settings used to configure caching changed in Django 1.3. In
56
 
    Django 1.2 and earlier, you used a single string-based
57
 
    :setting:`CACHE_BACKEND` setting to configure caches. This has
58
 
    been replaced with the new dictionary-based :setting:`CACHES`
59
 
    setting.
60
 
 
61
54
.. _memcached:
62
55
 
63
56
Memcached
83
76
.. _`python-memcached`: ftp://ftp.tummy.com/pub/python-memcached/
84
77
.. _`pylibmc`: http://sendapatch.se/projects/pylibmc/
85
78
 
86
 
.. versionchanged:: 1.2
87
 
    In Django 1.0 and 1.1, you could also use ``cmemcache`` as a binding.
88
 
    However, support for this library was deprecated in 1.2 due to
89
 
    a lack of maintenance on the ``cmemcache`` library itself. Support for
90
 
    ``cmemcache`` will be removed completely in Django 1.4.
91
 
 
92
 
.. versionchanged:: 1.3
93
 
    Support for ``pylibmc`` was added.
94
 
 
95
79
To use Memcached with Django:
96
80
 
97
81
* Set :setting:`BACKEND <CACHES-BACKEND>` to
153
137
            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
154
138
            'LOCATION': [
155
139
                '172.19.26.240:11211',
156
 
                '172.19.26.242:11211',
 
140
                '172.19.26.242:11212',
157
141
                '172.19.26.244:11213',
158
142
            ]
159
143
        }
302
286
 
303
287
The cache :setting:`LOCATION <CACHES-LOCATION>` is used to identify individual
304
288
memory stores. If you only have one locmem cache, you can omit the
305
 
:setting:`LOCATION <CACHES-LOCATION>`; however, if you have more that one local
 
289
:setting:`LOCATION <CACHES-LOCATION>`; however, if you have more than one local
306
290
memory cache, you will need to assign a name to at least one of them in
307
291
order to keep them separate.
308
292
 
493
477
 
494
478
.. _i18n-cache-key:
495
479
 
496
 
.. versionadded:: 1.2
497
 
 
498
480
If :setting:`USE_I18N` is set to ``True`` then the generated cache key will
499
481
include the name of the active :term:`language<language code>` -- see also
500
482
:ref:`how-django-discovers-language-preference`). This allows you to easily
603
585
 
604
586
The ``{% cache %}`` template tag caches the contents of the block for a given
605
587
amount of time. It takes at least two arguments: the cache timeout, in seconds,
606
 
and the name to give the cache fragment. For example:
 
588
and the name to give the cache fragment. The name will be taken as is, do not
 
589
use a variable. For example:
607
590
 
608
591
.. code-block:: html+django
609
592
 
680
663
can be pickled; refer to the Python documentation for more information about
681
664
pickling.)
682
665
 
 
666
Accessing the cache
 
667
-------------------
 
668
 
 
669
.. function:: django.core.cache.get_cache(backend, **kwargs)
 
670
 
683
671
The cache module, ``django.core.cache``, has a ``cache`` object that's
684
672
automatically created from the ``'default'`` entry in the :setting:`CACHES`
685
673
setting::
686
674
 
687
675
    >>> from django.core.cache import cache
688
676
 
 
677
If you have multiple caches defined in :setting:`CACHES`, then you can use
 
678
:func:`django.core.cache.get_cache` to retrieve a cache object for any key::
 
679
 
 
680
    >>> from django.core.cache import get_cache
 
681
    >>> cache = get_cache('alternate')
 
682
 
 
683
If the named key does not exist, ``InvalidCacheBackendError`` will be raised.
 
684
 
 
685
 
 
686
Basic usage
 
687
-----------
 
688
 
689
689
The basic interface is ``set(key, value, timeout)`` and ``get(key)``::
690
690
 
691
691
    >>> cache.set('my_key', 'hello, world!', 30)
693
693
    'hello, world!'
694
694
 
695
695
The ``timeout`` argument is optional and defaults to the ``timeout``
696
 
argument of the ``'default'`` backend in :setting:`CACHES` setting
 
696
argument of the appropriate backend in the :setting:`CACHES` setting
697
697
(explained above). It's the number of seconds the value should be stored
698
698
in the cache.
699
699
 
737
737
    >>> cache.get_many(['a', 'b', 'c'])
738
738
    {'a': 1, 'b': 2, 'c': 3}
739
739
 
740
 
.. versionadded:: 1.2
741
 
 
742
740
To set multiple values more efficiently, use ``set_many()`` to pass a dictionary
743
741
of key-value pairs::
744
742
 
753
751
 
754
752
    >>> cache.delete('a')
755
753
 
756
 
.. versionadded:: 1.2
757
 
 
758
754
If you want to clear a bunch of keys at once, ``delete_many()`` can take a list
759
755
of keys to be cleared::
760
756
 
761
757
    >>> cache.delete_many(['a', 'b', 'c'])
762
758
 
763
 
.. versionadded:: 1.2
764
 
 
765
759
Finally, if you want to delete all the keys in the cache, use
766
760
``cache.clear()``.  Be careful with this; ``clear()`` will remove *everything*
767
761
from the cache, not just the keys set by your application. ::
798
792
Cache key prefixing
799
793
-------------------
800
794
 
801
 
.. versionadded:: 1.3
802
 
 
803
795
If you are sharing a cache instance between servers, or between your
804
796
production and development environments, it's possible for data cached
805
797
by one server to be used by another server. If the format of cached
820
812
Cache versioning
821
813
----------------
822
814
 
823
 
.. versionadded:: 1.3
824
 
 
825
815
When you change running code that uses cached values, you may need to
826
816
purge any existing cached values. The easiest way to do this is to
827
817
flush the entire cache, but this can lead to the loss of cache values
848
838
    'hello world!'
849
839
 
850
840
The version of a specific key can be incremented and decremented using
851
 
the :func:`incr_version()` and :func:`decr_version()` methods. This
 
841
the ``incr_version()`` and ``decr_version()`` methods. This
852
842
enables specific keys to be bumped to a new version, leaving other
853
843
keys unaffected. Continuing our previous example::
854
844
 
869
859
Cache key transformation
870
860
------------------------
871
861
 
872
 
.. versionadded:: 1.3
873
 
 
874
862
As described in the previous two sections, the cache key provided by a
875
863
user is not used verbatim -- it is combined with the cache prefix and
876
864
key version to provide a final cache key. By default, the three parts
877
865
are joined using colons to produce a final string::
878
866
 
879
867
    def make_key(key, key_prefix, version):
880
 
        return ':'.join([key_prefix, str(version), smart_str(key)])
 
868
        return ':'.join([key_prefix, str(version), key])
881
869
 
882
870
If you want to combine the parts in different ways, or apply other
883
871
processing to the final key (e.g., taking a hash digest of the key
885
873
 
886
874
The :setting:`KEY_FUNCTION <CACHES-KEY_FUNCTION>` cache setting
887
875
specifies a dotted-path to a function matching the prototype of
888
 
:func:`make_key()` above. If provided, this custom key function will
 
876
``make_key()`` above. If provided, this custom key function will
889
877
be used instead of the default key combining function.
890
878
 
891
879
Cache key warnings
892
880
------------------
893
881
 
894
 
.. versionadded:: 1.3
895
 
 
896
882
Memcached, the most commonly-used production cache backend, does not allow
897
883
cache keys longer than 250 characters or containing whitespace or control
898
884
characters, and using such keys will cause an exception. To encourage
979
965
the contents of a Web page depend on a user's language preference, the page is
980
966
said to "vary on language."
981
967
 
982
 
.. versionchanged:: 1.3
983
 
    In Django 1.3 the full request path -- including the query -- is used
984
 
    to create the cache keys, instead of only the path component in Django 1.2.
985
 
 
986
968
By default, Django's cache system creates its cache keys using the requested
987
969
path and query -- e.g., ``"/stories/2005/?order_by=author"``. This means every
988
970
request to that URL will use the same cached version, regardless of user-agent