PageRenderTime 177ms CodeModel.GetById 157ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/topics/cache.txt

https://code.google.com/p/mango-py/
Plain Text | 1174 lines | 890 code | 284 blank | 0 comment | 0 complexity | cb89fec0e254edea301250011073d356 MD5 | raw file
   1========================
   2Django's cache framework
   3========================
   4
   5A fundamental trade-off in dynamic Web sites is, well, they're dynamic. Each
   6time a user requests a page, the Web server makes all sorts of calculations --
   7from database queries to template rendering to business logic -- to create the
   8page that your site's visitor sees. This is a lot more expensive, from a
   9processing-overhead perspective, than your standard
  10read-a-file-off-the-filesystem server arrangement.
  11
  12For most Web applications, this overhead isn't a big deal. Most Web
  13applications aren't washingtonpost.com or slashdot.org; they're simply small-
  14to medium-sized sites with so-so traffic. But for medium- to high-traffic
  15sites, it's essential to cut as much overhead as possible.
  16
  17That's where caching comes in.
  18
  19To cache something is to save the result of an expensive calculation so that
  20you don't have to perform the calculation next time. Here's some pseudocode
  21explaining how this would work for a dynamically generated Web page::
  22
  23    given a URL, try finding that page in the cache
  24    if the page is in the cache:
  25        return the cached page
  26    else:
  27        generate the page
  28        save the generated page in the cache (for next time)
  29        return the generated page
  30
  31Django comes with a robust cache system that lets you save dynamic pages so
  32they don't have to be calculated for each request. For convenience, Django
  33offers different levels of cache granularity: You can cache the output of
  34specific views, you can cache only the pieces that are difficult to produce,
  35or you can cache your entire site.
  36
  37Django also works well with "upstream" caches, such as `Squid
  38<http://www.squid-cache.org>`_ and browser-based caches. These are the types of
  39caches that you don't directly control but to which you can provide hints (via
  40HTTP headers) about which parts of your site should be cached, and how.
  41
  42Setting up the cache
  43====================
  44
  45The cache system requires a small amount of setup. Namely, you have to tell it
  46where your cached data should live -- whether in a database, on the filesystem
  47or directly in memory. This is an important decision that affects your cache's
  48performance; yes, some cache types are faster than others.
  49
  50Your cache preference goes in the :setting:`CACHES` setting in your
  51settings file. Here's an explanation of all available values for
  52:setting:`CACHES`.
  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.. _memcached:
  62
  63Memcached
  64---------
  65
  66By far the fastest, most efficient type of cache available to Django, Memcached
  67is an entirely memory-based cache framework originally developed to handle high
  68loads at LiveJournal.com and subsequently open-sourced by Danga Interactive.
  69It's used by sites such as Facebook and Wikipedia to reduce database access and
  70dramatically increase site performance.
  71
  72Memcached is available for free at http://memcached.org/. It runs as a
  73daemon and is allotted a specified amount of RAM. All it does is provide a
  74fast interface for adding, retrieving and deleting arbitrary data in the cache.
  75All data is stored directly in memory, so there's no overhead of database or
  76filesystem usage.
  77
  78After installing Memcached itself, you'll need to install a memcached
  79binding. There are several python memcached bindings available; the
  80two most common are `python-memcached`_ and `pylibmc`_.
  81
  82.. _`python-memcached`: ftp://ftp.tummy.com/pub/python-memcached/
  83.. _`pylibmc`: http://sendapatch.se/projects/pylibmc/
  84
  85.. versionchanged:: 1.2
  86    In Django 1.0 and 1.1, you could also use ``cmemcache`` as a binding.
  87    However, support for this library was deprecated in 1.2 due to
  88    a lack of maintenance on the ``cmemcache`` library itself. Support for
  89    ``cmemcache`` will be removed completely in Django 1.4.
  90
  91.. versionchanged:: 1.3
  92    Support for ``pylibmc`` was added.
  93
  94To use Memcached with Django:
  95
  96    * Set :setting:`BACKEND <CACHES-BACKEND>` to
  97      ``django.core.cache.backends.memcached.MemcachedCache`` or
  98      ``django.core.cache.backends.memcached.PyLibMCCache`` (depending
  99      on your chosen memcached binding)
 100
 101    * Set :setting:`LOCATION <CACHES-LOCATION>` to ``ip:port`` values,
 102      where ``ip`` is the IP address of the Memcached daemon and
 103      ``port`` is the port on which Memcached is running.
 104
 105In this example, Memcached is running on localhost (127.0.0.1) port 11211, using
 106the ``python-memcached`` binding::
 107
 108    CACHES = {
 109        'default': {
 110            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
 111            'LOCATION': '127.0.0.1:11211',
 112        }
 113    }
 114
 115One excellent feature of Memcached is its ability to share cache over multiple
 116servers. This means you can run Memcached daemons on multiple machines, and the
 117program will treat the group of machines as a *single* cache, without the need
 118to duplicate cache values on each machine. To take advantage of this feature,
 119include all server addresses in :setting:`LOCATION <CACHES-LOCATION>`, either
 120separated by semicolons or as a list.
 121
 122In this example, the cache is shared over Memcached instances running on IP
 123address 172.19.26.240 and 172.19.26.242, both on port 11211::
 124
 125    CACHES = {
 126        'default': {
 127            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
 128            'LOCATION': [
 129                '172.19.26.240:11211',
 130                '172.19.26.242:11211',
 131            ]
 132        }
 133    }
 134
 135In the following example, the cache is shared over Memcached instances running
 136on the IP addresses 172.19.26.240 (port 11211), 172.19.26.242 (port 11212), and
 137172.19.26.244 (port 11213)::
 138
 139    CACHES = {
 140        'default': {
 141            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
 142            'LOCATION': [
 143                '172.19.26.240:11211',
 144                '172.19.26.242:11211',
 145                '172.19.26.244:11213',
 146            ]
 147        }
 148    }
 149
 150A final point about Memcached is that memory-based caching has one
 151disadvantage: Because the cached data is stored in memory, the data will be
 152lost if your server crashes. Clearly, memory isn't intended for permanent data
 153storage, so don't rely on memory-based caching as your only data storage.
 154Without a doubt, *none* of the Django caching backends should be used for
 155permanent storage -- they're all intended to be solutions for caching, not
 156storage -- but we point this out here because memory-based caching is
 157particularly temporary.
 158
 159Database caching
 160----------------
 161
 162To use a database table as your cache backend, first create a cache table in
 163your database by running this command::
 164
 165    python manage.py createcachetable [cache_table_name]
 166
 167...where ``[cache_table_name]`` is the name of the database table to create.
 168(This name can be whatever you want, as long as it's a valid table name that's
 169not already being used in your database.) This command creates a single table
 170in your database that is in the proper format that Django's database-cache
 171system expects.
 172
 173Once you've created that database table, set your
 174:setting:`BACKEND <CACHES-BACKEND>` setting to
 175``"django.core.cache.backends.db.DatabaseCache"``, and
 176:setting:`LOCATION <CACHES-LOCATION>` to ``tablename`` -- the name of the
 177database table. In this example, the cache table's name is ``my_cache_table``::
 178
 179    CACHES = {
 180        'default': {
 181            'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
 182            'LOCATION': 'my_cache_table',
 183        }
 184    }
 185
 186
 187The database caching backend uses the same database as specified in your
 188settings file. You can't use a different database backend for your cache table.
 189
 190Database caching works best if you've got a fast, well-indexed database server.
 191
 192Database caching and multiple databases
 193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 194
 195If you use database caching with multiple databases, you'll also need
 196to set up routing instructions for your database cache table. For the
 197purposes of routing, the database cache table appears as a model named
 198``CacheEntry``, in an application named ``django_cache``. This model
 199won't appear in the models cache, but the model details can be used
 200for routing purposes.
 201
 202For example, the following router would direct all cache read
 203operations to ``cache_slave``, and all write operations to
 204``cache_master``. The cache table will only be synchronized onto
 205``cache_master``::
 206
 207    class CacheRouter(object):
 208        """A router to control all database cache operations"""
 209
 210        def db_for_read(self, model, **hints):
 211            "All cache read operations go to the slave"
 212            if model._meta.app_label in ('django_cache',):
 213                return 'cache_slave'
 214            return None
 215
 216        def db_for_write(self, model, **hints):
 217            "All cache write operations go to master"
 218            if model._meta.app_label in ('django_cache',):
 219                return 'cache_master'
 220            return None
 221
 222        def allow_syncdb(self, db, model):
 223            "Only synchronize the cache model on master"
 224            if model._meta.app_label in ('django_cache',):
 225                return db == 'cache_master'
 226            return None
 227
 228If you don't specify routing directions for the database cache model,
 229the cache backend will use the ``default`` database.
 230
 231Of course, if you don't use the database cache backend, you don't need
 232to worry about providing routing instructions for the database cache
 233model.
 234
 235Filesystem caching
 236------------------
 237
 238To store cached items on a filesystem, use
 239``"django.core.cache.backends.filebased.FileBasedCache"`` for
 240:setting:`BACKEND <CACHES-BACKEND>`. For example, to store cached data in
 241``/var/tmp/django_cache``, use this setting::
 242
 243    CACHES = {
 244        'default': {
 245            'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
 246            'LOCATION': '/var/tmp/django_cache',
 247        }
 248    }
 249
 250
 251If you're on Windows, put the drive letter at the beginning of the path,
 252like this::
 253
 254    CACHES = {
 255        'default': {
 256            'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
 257            'LOCATION': 'c:/foo/bar',
 258        }
 259    }
 260
 261The directory path should be absolute -- that is, it should start at the root
 262of your filesystem. It doesn't matter whether you put a slash at the end of the
 263setting.
 264
 265Make sure the directory pointed-to by this setting exists and is readable and
 266writable by the system user under which your Web server runs. Continuing the
 267above example, if your server runs as the user ``apache``, make sure the
 268directory ``/var/tmp/django_cache`` exists and is readable and writable by the
 269user ``apache``.
 270
 271Each cache value will be stored as a separate file whose contents are the
 272cache data saved in a serialized ("pickled") format, using Python's ``pickle``
 273module. Each file's name is the cache key, escaped for safe filesystem use.
 274
 275Local-memory caching
 276--------------------
 277
 278If you want the speed advantages of in-memory caching but don't have the
 279capability of running Memcached, consider the local-memory cache backend. This
 280cache is multi-process and thread-safe. To use it, set
 281:setting:`BACKEND <CACHES-BACKEND>` to
 282``"django.core.cache.backends.locmem.LocMemCache"``. For example::
 283
 284    CACHES = {
 285        'default': {
 286            'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
 287            'LOCATION': 'unique-snowflake'
 288        }
 289    }
 290
 291The cache :setting:`LOCATION <CACHES-LOCATION>` is used to identify individual
 292memory stores. If you only have one locmem cache, you can omit the
 293:setting:`LOCATION <CACHES-LOCATION>`; however, if you have more that one local
 294memory cache, you will need to assign a name to at least one of them in
 295order to keep them separate.
 296
 297Note that each process will have its own private cache instance, which means no
 298cross-process caching is possible. This obviously also means the local memory
 299cache isn't particularly memory-efficient, so it's probably not a good choice
 300for production environments. It's nice for development.
 301
 302Dummy caching (for development)
 303-------------------------------
 304
 305Finally, Django comes with a "dummy" cache that doesn't actually cache -- it
 306just implements the cache interface without doing anything.
 307
 308This is useful if you have a production site that uses heavy-duty caching in
 309various places but a development/test environment where you don't want to cache
 310and don't want to have to change your code to special-case the latter. To
 311activate dummy caching, set :setting:`BACKEND <CACHES-BACKEND>` like so::
 312
 313    CACHES = {
 314        'default': {
 315            'BACKEND': 'django.core.cache.backends.dummy.DummyCache',
 316        }
 317    }
 318
 319Using a custom cache backend
 320----------------------------
 321
 322While Django includes support for a number of cache backends out-of-the-box,
 323sometimes you might want to use a customized cache backend. To use an external
 324cache backend with Django, use the Python import path as the
 325:setting:`BACKEND <CACHES-BACKEND>` of the :setting:`CACHES` setting, like so::
 326
 327    CACHES = {
 328        'default': {
 329            'BACKEND': 'path.to.backend',
 330        }
 331    }
 332
 333If you're building your own backend, you can use the standard cache backends
 334as reference implementations. You'll find the code in the
 335``django/core/cache/backends/`` directory of the Django source.
 336
 337Note: Without a really compelling reason, such as a host that doesn't support
 338them, you should stick to the cache backends included with Django. They've
 339been well-tested and are easy to use.
 340
 341Cache arguments
 342---------------
 343
 344In addition to the defining the engine and name of the each cache
 345backend, each cache backend can be given additional arguments to
 346control caching behavior. These arguments are provided as additional
 347keys in the :setting:`CACHES` setting. Valid arguments are as follows:
 348
 349    * :setting:`TIMEOUT <CACHES-TIMEOUT>`: The default timeout, in
 350      seconds, to use for the cache. This argument defaults to 300
 351      seconds (5 minutes).
 352
 353    * :setting:`OPTIONS <CACHES-OPTIONS>`: Any options that should be
 354      passed to cache backend. The list options understood by each
 355      backend vary with each backend.
 356
 357      Cache backends that implement their own culling strategy (i.e.,
 358      the ``locmem``, ``filesystem`` and ``database`` backends) will
 359      honor the following options:
 360
 361        * ``MAX_ENTRIES``: the maximum number of entries allowed in
 362          the cache before old values are deleted. This argument
 363          defaults to ``300``.
 364
 365        * ``CULL_FREQUENCY``: The fraction of entries that are culled
 366          when ``MAX_ENTRIES`` is reached. The actual ratio is
 367          ``1/CULL_FREQUENCY``, so set ``CULL_FREQUENCY``: to ``2`` to
 368          cull half of the entries when ``MAX_ENTRIES`` is reached.
 369
 370          A value of ``0`` for ``CULL_FREQUENCY`` means that the
 371          entire cache will be dumped when ``MAX_ENTRIES`` is reached.
 372          This makes culling *much* faster at the expense of more
 373          cache misses.
 374
 375      Cache backends backed by a third-party library will pass their
 376      options directly to the underlying cache library. As a result,
 377      the list of valid options depends on the library in use.
 378
 379    * :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`: A string that will be
 380      automatically included (prepended by default) to all cache keys
 381      used by the Django server.
 382
 383      See the :ref:`cache documentation <cache_key_prefixing>` for
 384      more information.
 385
 386    * :setting:`VERSION <CACHES-VERSION>`: The default version number
 387      for cache keys generated by the Django server.
 388
 389      See the :ref:`cache documentation <cache_versioning>` for more
 390      information.
 391
 392    * :setting:`KEY_FUNCTION <CACHES-KEY_FUNCTION>`
 393      A string containing a dotted path to a function that defines how
 394      to compose a prefix, version and key into a final cache key.
 395
 396      See the :ref:`cache documentation <cache_key_transformation>`
 397      for more information.
 398
 399In this example, a filesystem backend is being configured with a timeout
 400of 60 seconds, and a maximum capacity of 1000 items::
 401
 402    CACHES = {
 403        'default': {
 404            'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
 405            'LOCATION': '/var/tmp/django_cache',
 406            'TIMEOUT': 60,
 407            'OPTIONS': {
 408                'MAX_ENTRIES': 1000
 409            }
 410        }
 411    }
 412
 413Invalid arguments are silently ignored, as are invalid values of known
 414arguments.
 415
 416The per-site cache
 417==================
 418
 419Once the cache is set up, the simplest way to use caching is to cache your
 420entire site. You'll need to add
 421``'django.middleware.cache.UpdateCacheMiddleware'`` and
 422``'django.middleware.cache.FetchFromCacheMiddleware'`` to your
 423:setting:`MIDDLEWARE_CLASSES` setting, as in this example::
 424
 425    MIDDLEWARE_CLASSES = (
 426        'django.middleware.cache.UpdateCacheMiddleware',
 427        'django.middleware.common.CommonMiddleware',
 428        'django.middleware.cache.FetchFromCacheMiddleware',
 429    )
 430
 431.. note::
 432
 433    No, that's not a typo: the "update" middleware must be first in the list,
 434    and the "fetch" middleware must be last. The details are a bit obscure, but
 435    see `Order of MIDDLEWARE_CLASSES`_ below if you'd like the full story.
 436
 437Then, add the following required settings to your Django settings file:
 438
 439* :setting:`CACHE_MIDDLEWARE_ALIAS` -- The cache alias to use for storage.
 440* :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should
 441  be cached.
 442* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across
 443  multiple sites using the same Django installation, set this to the name of
 444  the site, or some other string that is unique to this Django instance, to
 445  prevent key collisions. Use an empty string if you don't care.
 446
 447The cache middleware caches every page that doesn't have GET or POST
 448parameters. Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`
 449setting is ``True``, only anonymous requests (i.e., not those made by a
 450logged-in user) will be cached. This is a simple and effective way of disabling
 451caching for any user-specific pages (including Django's admin interface). Note
 452that if you use :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make
 453sure you've activated ``AuthenticationMiddleware``. The cache middleware
 454expects that a HEAD request is answered with the same response headers as
 455the corresponding GET request; in which case it can return a cached GET
 456response for HEAD request.
 457
 458Additionally, the cache middleware automatically sets a few headers in each
 459:class:`~django.http.HttpResponse`:
 460
 461    * Sets the ``Last-Modified`` header to the current date/time when a fresh
 462      (uncached) version of the page is requested.
 463
 464    * Sets the ``Expires`` header to the current date/time plus the defined
 465      :setting:`CACHE_MIDDLEWARE_SECONDS`.
 466
 467    * Sets the ``Cache-Control`` header to give a max age for the page --
 468      again, from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting.
 469
 470See :doc:`/topics/http/middleware` for more on middleware.
 471
 472If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
 473its ``Cache-Control`` header) then the page will be cached until the expiry
 474time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in
 475``django.views.decorators.cache`` you can easily set a view's expiry time
 476(using the ``cache_control`` decorator) or disable caching for a view (using
 477the ``never_cache`` decorator). See the `using other headers`__ section for
 478more on these decorators.
 479
 480.. _i18n-cache-key:
 481
 482.. versionadded:: 1.2
 483
 484If :setting:`USE_I18N` is set to ``True`` then the generated cache key will
 485include the name of the active :term:`language<language code>`.
 486This allows you to easily cache multilingual sites without having to create
 487the cache key yourself.
 488
 489See :doc:`/topics/i18n/deployment` for more on how Django discovers the active
 490language.
 491
 492__ `Controlling cache: Using other headers`_
 493
 494The per-view cache
 495==================
 496
 497.. function ``django.views.decorators.cache.cache_page``
 498
 499A more granular way to use the caching framework is by caching the output of
 500individual views. ``django.views.decorators.cache`` defines a ``cache_page``
 501decorator that will automatically cache the view's response for you. It's easy
 502to use::
 503
 504    from django.views.decorators.cache import cache_page
 505
 506    @cache_page(60 * 15)
 507    def my_view(request):
 508        ...
 509
 510``cache_page`` takes a single argument: the cache timeout, in seconds. In the
 511above example, the result of the ``my_view()`` view will be cached for 15
 512minutes. (Note that we've written it as ``60 * 15`` for the purpose of
 513readability. ``60 * 15`` will be evaluated to ``900`` -- that is, 15 minutes
 514multiplied by 60 seconds per minute.)
 515
 516The per-view cache, like the per-site cache, is keyed off of the URL. If
 517multiple URLs point at the same view, each URL will be cached separately.
 518Continuing the ``my_view`` example, if your URLconf looks like this::
 519
 520    urlpatterns = ('',
 521        (r'^foo/(\d{1,2})/$', my_view),
 522    )
 523
 524then requests to ``/foo/1/`` and ``/foo/23/`` will be cached separately, as
 525you may expect. But once a particular URL (e.g., ``/foo/23/``) has been
 526requested, subsequent requests to that URL will use the cache.
 527
 528``cache_page`` can also take an optional keyword argument, ``cache``,
 529which directs the decorator to use a specific cache alias when caching view
 530results. By default, the ``default`` alias will be used, but you can specify
 531any cache alias you want::
 532
 533    @cache_page(60 * 15, cache="special_cache")
 534    def my_view(request):
 535        ...
 536
 537You can also override the cache prefix on a per-view basis. ``cache_page``
 538takes an optional keyword argument, ``key_prefix``,
 539which works in the same way as the :setting:`CACHE_MIDDLEWARE_KEY_PREFIX`
 540setting for the middleware.  It can be used like this::
 541
 542    @cache_page(60 * 15, key_prefix="site1")
 543    def my_view(request):
 544        ...
 545
 546The two settings can also be combined. If you specify a ``cache`` *and*
 547a ``key_prefix``, you will get all the settings of the requested cache
 548alias, but with the key_prefix overridden.
 549
 550Specifying per-view cache in the URLconf
 551----------------------------------------
 552
 553The examples in the previous section have hard-coded the fact that the view is
 554cached, because ``cache_page`` alters the ``my_view`` function in place. This
 555approach couples your view to the cache system, which is not ideal for several
 556reasons. For instance, you might want to reuse the view functions on another,
 557cache-less site, or you might want to distribute the views to people who might
 558want to use them without being cached. The solution to these problems is to
 559specify the per-view cache in the URLconf rather than next to the view functions
 560themselves.
 561
 562Doing so is easy: simply wrap the view function with ``cache_page`` when you
 563refer to it in the URLconf. Here's the old URLconf from earlier::
 564
 565    urlpatterns = ('',
 566        (r'^foo/(\d{1,2})/$', my_view),
 567    )
 568
 569Here's the same thing, with ``my_view`` wrapped in ``cache_page``::
 570
 571    from django.views.decorators.cache import cache_page
 572
 573    urlpatterns = ('',
 574        (r'^foo/(\d{1,2})/$', cache_page(my_view, 60 * 15)),
 575    )
 576
 577If you take this approach, don't forget to import ``cache_page`` within your
 578URLconf.
 579
 580Template fragment caching
 581=========================
 582
 583If you're after even more control, you can also cache template fragments using
 584the ``cache`` template tag. To give your template access to this tag, put
 585``{% load cache %}`` near the top of your template.
 586
 587The ``{% cache %}`` template tag caches the contents of the block for a given
 588amount of time. It takes at least two arguments: the cache timeout, in seconds,
 589and the name to give the cache fragment. For example:
 590
 591.. code-block:: html+django
 592
 593    {% load cache %}
 594    {% cache 500 sidebar %}
 595        .. sidebar ..
 596    {% endcache %}
 597
 598Sometimes you might want to cache multiple copies of a fragment depending on
 599some dynamic data that appears inside the fragment. For example, you might want a
 600separate cached copy of the sidebar used in the previous example for every user
 601of your site. Do this by passing additional arguments to the ``{% cache %}``
 602template tag to uniquely identify the cache fragment:
 603
 604.. code-block:: html+django
 605
 606    {% load cache %}
 607    {% cache 500 sidebar request.user.username %}
 608        .. sidebar for logged in user ..
 609    {% endcache %}
 610
 611It's perfectly fine to specify more than one argument to identify the fragment.
 612Simply pass as many arguments to ``{% cache %}`` as you need.
 613
 614If :setting:`USE_I18N` is set to ``True`` the per-site middleware cache will
 615:ref:`respect the active language<i18n-cache-key>`. For the ``cache`` template
 616tag you could use one of the
 617:ref:`translation-specific variables<template-translation-vars>` available in
 618templates to achieve the same result:
 619
 620.. code-block:: html+django
 621
 622    {% load i18n %}
 623    {% load cache %}
 624
 625    {% get_current_language as LANGUAGE_CODE %}
 626
 627    {% cache 600 welcome LANGUAGE_CODE %}
 628        {% trans "Welcome to example.com" %}
 629    {% endcache %}
 630
 631The cache timeout can be a template variable, as long as the template variable
 632resolves to an integer value. For example, if the template variable
 633``my_timeout`` is set to the value ``600``, then the following two examples are
 634equivalent:
 635
 636.. code-block:: html+django
 637
 638    {% cache 600 sidebar %} ... {% endcache %}
 639    {% cache my_timeout sidebar %} ... {% endcache %}
 640
 641This feature is useful in avoiding repetition in templates. You can set the
 642timeout in a variable, in one place, and just reuse that value.
 643
 644The low-level cache API
 645=======================
 646
 647.. highlight:: python
 648
 649Sometimes, caching an entire rendered page doesn't gain you very much and is,
 650in fact, inconvenient overkill.
 651
 652Perhaps, for instance, your site includes a view whose results depend on
 653several expensive queries, the results of which change at different intervals.
 654In this case, it would not be ideal to use the full-page caching that the
 655per-site or per-view cache strategies offer, because you wouldn't want to
 656cache the entire result (since some of the data changes often), but you'd still
 657want to cache the results that rarely change.
 658
 659For cases like this, Django exposes a simple, low-level cache API. You can use
 660this API to store objects in the cache with any level of granularity you like.
 661You can cache any Python object that can be pickled safely: strings,
 662dictionaries, lists of model objects, and so forth. (Most common Python objects
 663can be pickled; refer to the Python documentation for more information about
 664pickling.)
 665
 666The cache module, ``django.core.cache``, has a ``cache`` object that's
 667automatically created from the ``'default'`` entry in the :setting:`CACHES`
 668setting::
 669
 670    >>> from django.core.cache import cache
 671
 672The basic interface is ``set(key, value, timeout)`` and ``get(key)``::
 673
 674    >>> cache.set('my_key', 'hello, world!', 30)
 675    >>> cache.get('my_key')
 676    'hello, world!'
 677
 678The ``timeout`` argument is optional and defaults to the ``timeout``
 679argument of the ``'default'`` backend in :setting:`CACHES` setting
 680(explained above). It's the number of seconds the value should be stored
 681in the cache.
 682
 683If the object doesn't exist in the cache, ``cache.get()`` returns ``None``::
 684
 685    # Wait 30 seconds for 'my_key' to expire...
 686
 687    >>> cache.get('my_key')
 688    None
 689
 690We advise against storing the literal value ``None`` in the cache, because you
 691won't be able to distinguish between your stored ``None`` value and a cache
 692miss signified by a return value of ``None``.
 693
 694``cache.get()`` can take a ``default`` argument. This specifies which value to
 695return if the object doesn't exist in the cache::
 696
 697    >>> cache.get('my_key', 'has expired')
 698    'has expired'
 699
 700To add a key only if it doesn't already exist, use the ``add()`` method.
 701It takes the same parameters as ``set()``, but it will not attempt to
 702update the cache if the key specified is already present::
 703
 704    >>> cache.set('add_key', 'Initial value')
 705    >>> cache.add('add_key', 'New value')
 706    >>> cache.get('add_key')
 707    'Initial value'
 708
 709If you need to know whether ``add()`` stored a value in the cache, you can
 710check the return value. It will return ``True`` if the value was stored,
 711``False`` otherwise.
 712
 713There's also a ``get_many()`` interface that only hits the cache once.
 714``get_many()`` returns a dictionary with all the keys you asked for that
 715actually exist in the cache (and haven't expired)::
 716
 717    >>> cache.set('a', 1)
 718    >>> cache.set('b', 2)
 719    >>> cache.set('c', 3)
 720    >>> cache.get_many(['a', 'b', 'c'])
 721    {'a': 1, 'b': 2, 'c': 3}
 722
 723.. versionadded:: 1.2
 724
 725To set multiple values more efficiently, use ``set_many()`` to pass a dictionary
 726of key-value pairs::
 727
 728    >>> cache.set_many({'a': 1, 'b': 2, 'c': 3})
 729    >>> cache.get_many(['a', 'b', 'c'])
 730    {'a': 1, 'b': 2, 'c': 3}
 731
 732Like ``cache.set()``, ``set_many()`` takes an optional ``timeout`` parameter.
 733
 734You can delete keys explicitly with ``delete()``. This is an easy way of
 735clearing the cache for a particular object::
 736
 737    >>> cache.delete('a')
 738
 739.. versionadded:: 1.2
 740
 741If you want to clear a bunch of keys at once, ``delete_many()`` can take a list
 742of keys to be cleared::
 743
 744    >>> cache.delete_many(['a', 'b', 'c'])
 745
 746.. versionadded:: 1.2
 747
 748Finally, if you want to delete all the keys in the cache, use
 749``cache.clear()``.  Be careful with this; ``clear()`` will remove *everything*
 750from the cache, not just the keys set by your application. ::
 751
 752    >>> cache.clear()
 753
 754You can also increment or decrement a key that already exists using the
 755``incr()`` or ``decr()`` methods, respectively. By default, the existing cache
 756value will incremented or decremented by 1. Other increment/decrement values
 757can be specified by providing an argument to the increment/decrement call. A
 758ValueError will be raised if you attempt to increment or decrement a
 759nonexistent cache key.::
 760
 761    >>> cache.set('num', 1)
 762    >>> cache.incr('num')
 763    2
 764    >>> cache.incr('num', 10)
 765    12
 766    >>> cache.decr('num')
 767    11
 768    >>> cache.decr('num', 5)
 769    6
 770
 771.. note::
 772
 773    ``incr()``/``decr()`` methods are not guaranteed to be atomic. On those
 774    backends that support atomic increment/decrement (most notably, the
 775    memcached backend), increment and decrement operations will be atomic.
 776    However, if the backend doesn't natively provide an increment/decrement
 777    operation, it will be implemented using a two-step retrieve/update.
 778
 779.. _cache_key_prefixing:
 780
 781Cache key prefixing
 782-------------------
 783
 784.. versionadded:: 1.3
 785
 786If you are sharing a cache instance between servers, or between your
 787production and development environments, it's possible for data cached
 788by one server to be used by another server. If the format of cached
 789data is different between servers, this can lead to some very hard to
 790diagnose problems.
 791
 792To prevent this, Django provides the ability to prefix all cache keys
 793used by a server. When a particular cache key is saved or retrieved,
 794Django will automatically prefix the cache key with the value of the
 795:setting:`KEY_PREFIX <CACHES-KEY_PREFIX>` cache setting.
 796
 797By ensuring each Django instance has a different
 798:setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`, you can ensure that there will be no
 799collisions in cache values.
 800
 801.. _cache_versioning:
 802
 803Cache versioning
 804----------------
 805
 806.. versionadded:: 1.3
 807
 808When you change running code that uses cached values, you may need to
 809purge any existing cached values. The easiest way to do this is to
 810flush the entire cache, but this can lead to the loss of cache values
 811that are still valid and useful.
 812
 813Django provides a better way to target individual cache values.
 814Django's cache framework has a system-wide version identifier,
 815specified using the :setting:`VERSION <CACHES-VERSION>` cache setting.
 816The value of this setting is automatically combined with the cache
 817prefix and the user-provided cache key to obtain the final cache key.
 818
 819By default, any key request will automatically include the site
 820default cache key version. However, the primitive cache functions all
 821include a ``version`` argument, so you can specify a particular cache
 822key version to set or get. For example::
 823
 824    # Set version 2 of a cache key
 825    >>> cache.set('my_key', 'hello world!', version=2)
 826    # Get the default version (assuming version=1)
 827    >>> cache.get('my_key')
 828    None
 829    # Get version 2 of the same key
 830    >>> cache.get('my_key', version=2)
 831    'hello world!'
 832
 833The version of a specific key can be incremented and decremented using
 834the :func:`incr_version()` and :func:`decr_version()` methods. This
 835enables specific keys to be bumped to a new version, leaving other
 836keys unaffected. Continuing our previous example::
 837
 838    # Increment the version of 'my_key'
 839    >>> cache.incr_version('my_key')
 840    # The default version still isn't available
 841    >>> cache.get('my_key')
 842    None
 843    # Version 2 isn't available, either
 844    >>> cache.get('my_key', version=2)
 845    None
 846    # But version 3 *is* available
 847    >>> cache.get('my_key', version=3)
 848    'hello world!'
 849
 850.. _cache_key_transformation:
 851
 852Cache key transformation
 853------------------------
 854
 855.. versionadded:: 1.3
 856
 857As described in the previous two sections, the cache key provided by a
 858user is not used verbatim -- it is combined with the cache prefix and
 859key version to provide a final cache key. By default, the three parts
 860are joined using colons to produce a final string::
 861
 862    def make_key(key, key_prefix, version):
 863        return ':'.join([key_prefix, str(version), smart_str(key)])
 864
 865If you want to combine the parts in different ways, or apply other
 866processing to the final key (e.g., taking a hash digest of the key
 867parts), you can provide a custom key function.
 868
 869The :setting:`KEY_FUNCTION <CACHES-KEY_FUNCTION>` cache setting
 870specifies a dotted-path to a function matching the prototype of
 871:func:`make_key()` above. If provided, this custom key function will
 872be used instead of the default key combining function.
 873
 874Cache key warnings
 875------------------
 876
 877.. versionadded:: 1.3
 878
 879Memcached, the most commonly-used production cache backend, does not allow
 880cache keys longer than 250 characters or containing whitespace or control
 881characters, and using such keys will cause an exception. To encourage
 882cache-portable code and minimize unpleasant surprises, the other built-in cache
 883backends issue a warning (``django.core.cache.backends.base.CacheKeyWarning``)
 884if a key is used that would cause an error on memcached.
 885
 886If you are using a production backend that can accept a wider range of keys (a
 887custom backend, or one of the non-memcached built-in backends), and want to use
 888this wider range without warnings, you can silence ``CacheKeyWarning`` with
 889this code in the ``management`` module of one of your
 890:setting:`INSTALLED_APPS`::
 891
 892     import warnings
 893
 894     from django.core.cache import CacheKeyWarning
 895
 896     warnings.simplefilter("ignore", CacheKeyWarning)
 897
 898If you want to instead provide custom key validation logic for one of the
 899built-in backends, you can subclass it, override just the ``validate_key``
 900method, and follow the instructions for `using a custom cache backend`_. For
 901instance, to do this for the ``locmem`` backend, put this code in a module::
 902
 903    from django.core.cache.backends.locmem import LocMemCache
 904
 905    class CustomLocMemCache(LocMemCache):
 906        def validate_key(self, key):
 907            """Custom validation, raising exceptions or warnings as needed."""
 908            # ...
 909
 910...and use the dotted Python path to this class in the
 911:setting:`BACKEND <CACHES-BACKEND>` portion of your :setting:`CACHES` setting.
 912
 913Upstream caches
 914===============
 915
 916So far, this document has focused on caching your *own* data. But another type
 917of caching is relevant to Web development, too: caching performed by "upstream"
 918caches. These are systems that cache pages for users even before the request
 919reaches your Web site.
 920
 921Here are a few examples of upstream caches:
 922
 923    * Your ISP may cache certain pages, so if you requested a page from
 924      http://example.com/, your ISP would send you the page without having to
 925      access example.com directly. The maintainers of example.com have no
 926      knowledge of this caching; the ISP sits between example.com and your Web
 927      browser, handling all of the caching transparently.
 928
 929    * Your Django Web site may sit behind a *proxy cache*, such as Squid Web
 930      Proxy Cache (http://www.squid-cache.org/), that caches pages for
 931      performance. In this case, each request first would be handled by the
 932      proxy, and it would be passed to your application only if needed.
 933
 934    * Your Web browser caches pages, too. If a Web page sends out the
 935      appropriate headers, your browser will use the local cached copy for
 936      subsequent requests to that page, without even contacting the Web page
 937      again to see whether it has changed.
 938
 939Upstream caching is a nice efficiency boost, but there's a danger to it:
 940Many Web pages' contents differ based on authentication and a host of other
 941variables, and cache systems that blindly save pages based purely on URLs could
 942expose incorrect or sensitive data to subsequent visitors to those pages.
 943
 944For example, say you operate a Web e-mail system, and the contents of the
 945"inbox" page obviously depend on which user is logged in. If an ISP blindly
 946cached your site, then the first user who logged in through that ISP would have
 947his user-specific inbox page cached for subsequent visitors to the site. That's
 948not cool.
 949
 950Fortunately, HTTP provides a solution to this problem. A number of HTTP headers
 951exist to instruct upstream caches to differ their cache contents depending on
 952designated variables, and to tell caching mechanisms not to cache particular
 953pages. We'll look at some of these headers in the sections that follow.
 954
 955.. _using-vary-headers:
 956
 957Using Vary headers
 958==================
 959
 960The ``Vary`` header defines which request headers a cache
 961mechanism should take into account when building its cache key. For example, if
 962the contents of a Web page depend on a user's language preference, the page is
 963said to "vary on language."
 964
 965.. versionchanged:: 1.3
 966    In Django 1.3 the full request path -- including the query -- is used
 967    to create the cache keys, instead of only the path component in Django 1.2.
 968
 969By default, Django's cache system creates its cache keys using the requested
 970path and query -- e.g., ``"/stories/2005/?order_by=author"``. This means every
 971request to that URL will use the same cached version, regardless of user-agent
 972differences such as cookies or language preferences. However, if this page
 973produces different content based on some difference in request headers -- such
 974as a cookie, or a language, or a user-agent -- you'll need to use the ``Vary``
 975header to tell caching mechanisms that the page output depends on those things.
 976
 977To do this in Django, use the convenient ``vary_on_headers`` view decorator,
 978like so::
 979
 980    from django.views.decorators.vary import vary_on_headers
 981
 982    @vary_on_headers('User-Agent')
 983    def my_view(request):
 984        # ...
 985
 986In this case, a caching mechanism (such as Django's own cache middleware) will
 987cache a separate version of the page for each unique user-agent.
 988
 989The advantage to using the ``vary_on_headers`` decorator rather than manually
 990setting the ``Vary`` header (using something like
 991``response['Vary'] = 'user-agent'``) is that the decorator *adds* to the
 992``Vary`` header (which may already exist), rather than setting it from scratch
 993and potentially overriding anything that was already in there.
 994
 995You can pass multiple headers to ``vary_on_headers()``::
 996
 997    @vary_on_headers('User-Agent', 'Cookie')
 998    def my_view(request):
 999        # ...
1000
1001This tells upstream caches to vary on *both*, which means each combination of
1002user-agent and cookie will get its own cache value. For example, a request with
1003the user-agent ``Mozilla`` and the cookie value ``foo=bar`` will be considered
1004different from a request with the user-agent ``Mozilla`` and the cookie value
1005``foo=ham``.
1006
1007Because varying on cookie is so common, there's a ``vary_on_cookie``
1008decorator. These two views are equivalent::
1009
1010    @vary_on_cookie
1011    def my_view(request):
1012        # ...
1013
1014    @vary_on_headers('Cookie')
1015    def my_view(request):
1016        # ...
1017
1018The headers you pass to ``vary_on_headers`` are not case sensitive;
1019``"User-Agent"`` is the same thing as ``"user-agent"``.
1020
1021You can also use a helper function, ``django.utils.cache.patch_vary_headers``,
1022directly. This function sets, or adds to, the ``Vary header``. For example::
1023
1024    from django.utils.cache import patch_vary_headers
1025
1026    def my_view(request):
1027        # ...
1028        response = render_to_response('template_name', context)
1029        patch_vary_headers(response, ['Cookie'])
1030        return response
1031
1032``patch_vary_headers`` takes an :class:`~django.http.HttpResponse` instance as
1033its first argument and a list/tuple of case-insensitive header names as its
1034second argument.
1035
1036For more on Vary headers, see the `official Vary spec`_.
1037
1038.. _`official Vary spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
1039
1040Controlling cache: Using other headers
1041======================================
1042
1043Other problems with caching are the privacy of data and the question of where
1044data should be stored in a cascade of caches.
1045
1046A user usually faces two kinds of caches: his or her own browser cache (a
1047private cache) and his or her provider's cache (a public cache). A public cache
1048is used by multiple users and controlled by someone else. This poses problems
1049with sensitive data--you don't want, say, your bank account number stored in a
1050public cache. So Web applications need a way to tell caches which data is
1051private and which is public.
1052
1053The solution is to indicate a page's cache should be "private." To do this in
1054Django, use the ``cache_control`` view decorator. Example::
1055
1056    from django.views.decorators.cache import cache_control
1057
1058    @cache_control(private=True)
1059    def my_view(request):
1060        # ...
1061
1062This decorator takes care of sending out the appropriate HTTP header behind the
1063scenes.
1064
1065Note that the cache control settings "private" and "public" are mutually
1066exclusive. The decorator ensures that the "public" directive is removed if
1067"private" should be set (and vice versa). An example use of the two directives
1068would be a blog site that offers both private and public entries. Public
1069entries may be cached on any shared cache. The following code uses
1070``patch_cache_control``, the manual way to modify the cache control header
1071(it is internally called by the ``cache_control`` decorator)::
1072
1073    from django.views.decorators.cache import patch_cache_control
1074    from django.views.decorators.vary import vary_on_cookie
1075
1076    @vary_on_cookie
1077    def list_blog_entries_view(request):
1078        if request.user.is_anonymous():
1079            response = render_only_public_entries()
1080            patch_cache_control(response, public=True)
1081        else:
1082            response = render_private_and_public_entries(request.user)
1083            patch_cache_control(response, private=True)
1084
1085        return response
1086
1087There are a few other ways to control cache parameters. For example, HTTP
1088allows applications to do the following:
1089
1090    * Define the maximum time a page should be cached.
1091
1092    * Specify whether a cache should always check for newer versions, only
1093      delivering the cached content when there are no changes. (Some caches
1094      might deliver cached content even if the server page changed, simply
1095      because the cache copy isn't yet expired.)
1096
1097In Django, use the ``cache_control`` view decorator to specify these cache
1098parameters. In this example, ``cache_control`` tells caches to revalidate the
1099cache on every access and to store cached versions for, at most, 3,600 seconds::
1100
1101    from django.views.decorators.cache import cache_control
1102
1103    @cache_control(must_revalidate=True, max_age=3600)
1104    def my_view(request):
1105        # ...
1106
1107Any valid ``Cache-Control`` HTTP directive is valid in ``cache_control()``.
1108Here's a full list:
1109
1110    * ``public=True``
1111    * ``private=True``
1112    * ``no_cache=True``
1113    * ``no_transform=True``
1114    * ``must_revalidate=True``
1115    * ``proxy_revalidate=True``
1116    * ``max_age=num_seconds``
1117    * ``s_maxage=num_seconds``
1118
1119For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_.
1120
1121(Note that the caching middleware already sets the cache header's max-age with
1122the value of the :setting:`CACHE_MIDDLEWARE_SECONDS` setting. If you use a custom
1123``max_age`` in a ``cache_control`` decorator, the decorator will take
1124precedence, and the header values will be merged correctly.)
1125
1126If you want to use headers to disable caching altogether,
1127``django.views.decorators.cache.never_cache`` is a view decorator that adds
1128headers to ensure the response won't be cached by browsers or other caches.
1129Example::
1130
1131    from django.views.decorators.cache import never_cache
1132
1133    @never_cache
1134    def myview(request):
1135        # ...
1136
1137.. _`Cache-Control spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
1138
1139Other optimizations
1140===================
1141
1142Django comes with a few other pieces of middleware that can help optimize your
1143site's performance:
1144
1145    * ``django.middleware.http.ConditionalGetMiddleware`` adds support for
1146      modern browsers to conditionally GET responses based on the ``ETag``
1147      and ``Last-Modified`` headers.
1148
1149    * :class:`django.middleware.gzip.GZipMiddleware` compresses responses for all
1150      moderns browsers, saving bandwidth and transfer time.
1151
1152Order of MIDDLEWARE_CLASSES
1153===========================
1154
1155If you use caching middleware, it's important to put each half in the right
1156place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache
1157middleware needs to know which headers by which to vary the cache storage.
1158Middleware always adds something to the ``Vary`` response header when it can.
1159
1160``UpdateCacheMiddleware`` runs during the response phase, where middleware is
1161run in reverse order, so an item at the top of the list runs *last* during the
1162response phase. Thus, you need to make sure that ``UpdateCacheMiddleware``
1163appears *before* any other middleware that might add something to the ``Vary``
1164header. The following middleware modules do so:
1165
1166    * ``SessionMiddleware`` adds ``Cookie``
1167    * ``GZipMiddleware`` adds ``Accept-Encoding``
1168    * ``LocaleMiddleware`` adds ``Accept-Language``
1169
1170``FetchFromCacheMiddleware``, on the other hand, runs during the request phase,
1171where middleware is applied first-to-last, so an item at the top of the list
1172runs *first* during the request phase. The ``FetchFromCacheMiddleware`` also
1173needs to run after other middleware updates the ``Vary`` header, so
1174``FetchFromCacheMiddleware`` must be *after* any item that does so.