Ticket #14738: link-settings-in-cache-docs.diff
| File link-settings-in-cache-docs.diff, 13.1 KB (added by , 14 years ago) |
|---|
-
docs/ref/settings.txt
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 87219b2..b551a27 100644
a b caches every page that doesn't have GET or POST parameters. 169 169 If you set the value of this setting to ``True``, you should make sure you've 170 170 activated ``AuthenticationMiddleware``. 171 171 172 See the :doc:`cache documentation </topics/cache>` for more information.172 See :doc:`/topics/cache`. 173 173 174 174 .. setting:: CACHE_MIDDLEWARE_KEY_PREFIX 175 175 … … CACHE_MIDDLEWARE_KEY_PREFIX 178 178 179 179 Default: ``''`` (Empty string) 180 180 181 The cache key prefix that the cache middleware should use. See 182 :doc:`/topics/cache`. 181 The cache key prefix that the cache middleware should use. 182 183 See :doc:`/topics/cache`. 183 184 184 185 .. setting:: CACHE_MIDDLEWARE_SECONDS 185 186 … … Default: ``600`` 191 192 The default number of seconds to cache a page when the caching middleware or 192 193 ``cache_page()`` decorator is used. 193 194 195 See :doc:`/topics/cache`. 196 194 197 .. setting:: CACHE_PREFIX 195 198 196 199 CACHE_PREFIX -
docs/topics/cache.txt
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index a98762f..b3aa4a8 100644
a b explaining how this would work for a dynamically generated Web page:: 31 31 Django comes with a robust cache system that lets you save dynamic pages so 32 32 they don't have to be calculated for each request. For convenience, Django 33 33 offers different levels of cache granularity: You can cache the output of 34 specific views, you can cache only the pieces that are difficult to produce, or35 you can cache your entire site.34 specific views, you can cache only the pieces that are difficult to produce, 35 or you can cache your entire site. 36 36 37 37 Django also works well with "upstream" caches, such as Squid 38 38 (http://www.squid-cache.org/) and browser-based caches. These are the types of … … where your cached data should live -- whether in a database, on the filesystem 47 47 or directly in memory. This is an important decision that affects your cache's 48 48 performance; yes, some cache types are faster than others. 49 49 50 Your cache preference goes in the ``CACHE_BACKEND`` setting in your settings 51 file. Here's an explanation of all available values for ``CACHE_BACKEND``. 50 Your cache preference goes in the :setting:`CACHE_BACKEND` setting in your 51 settings file. Here's an explanation of all available values for 52 :setting:`CACHE_BACKEND`. 52 53 53 54 Memcached 54 55 --------- … … This is available at ftp://ftp.tummy.com/pub/python-memcached/ 75 76 a lack of maintenance on the ``cmemcache`` library itself. Support for 76 77 ``cmemcache`` will be removed completely in Django 1.4. 77 78 78 To use Memcached with Django, set ``CACHE_BACKEND`` to79 To use Memcached with Django, set :setting:`CACHE_BACKEND` to 79 80 ``memcached://ip:port/``, where ``ip`` is the IP address of the Memcached 80 81 daemon and ``port`` is the port on which Memcached is running. 81 82 … … One excellent feature of Memcached is its ability to share cache over multiple 87 88 servers. This means you can run Memcached daemons on multiple machines, and the 88 89 program will treat the group of machines as a *single* cache, without the need 89 90 to duplicate cache values on each machine. To take advantage of this feature, 90 include all server addresses in ``CACHE_BACKEND``, separated by semicolons. 91 include all server addresses in :setting:`CACHE_BACKEND`, separated by 92 semicolons. 91 93 92 94 In this example, the cache is shared over Memcached instances running on IP 93 95 address 172.19.26.240 and 172.19.26.242, both on port 11211:: … … not already being used in your database.) This command creates a single table 123 125 in your database that is in the proper format that Django's database-cache 124 126 system expects. 125 127 126 Once you've created that database table, set your ``CACHE_BACKEND`` setting to 127 ``"db://tablename"``, where ``tablename`` is the name of the database table. 128 In this example, the cache table's name is ``my_cache_table``:: 128 Once you've created that database table, set your :setting:`CACHE_BACKEND` 129 setting to ``"db://tablename"``, where ``tablename`` is the name of the 130 database table. In this example, the cache table's name is 131 ``my_cache_table``:: 129 132 130 133 CACHE_BACKEND = 'db://my_cache_table' 131 134 … … Filesystem caching 181 184 ------------------ 182 185 183 186 To store cached items on a filesystem, use the ``"file://"`` cache type for 184 ``CACHE_BACKEND``. For example, to store cached data in ``/var/tmp/django_cache``, 185 use this setting::187 :setting:`CACHE_BACKEND`. For example, to store cached data in 188 ``/var/tmp/django_cache``, use this setting:: 186 189 187 190 CACHE_BACKEND = 'file:///var/tmp/django_cache' 188 191 … … Local-memory caching 212 215 213 216 If you want the speed advantages of in-memory caching but don't have the 214 217 capability of running Memcached, consider the local-memory cache backend. This 215 cache is multi-process and thread-safe. To use it, set ``CACHE_BACKEND`` to216 ``"locmem://"``. For example::218 cache is multi-process and thread-safe. To use it, set :setting:`CACHE_BACKEND` 219 to ``"locmem://"``. For example:: 217 220 218 221 CACHE_BACKEND = 'locmem://' 219 222 … … just implements the cache interface without doing anything. 231 234 This is useful if you have a production site that uses heavy-duty caching in 232 235 various places but a development/test environment where you don't want to cache 233 236 and don't want to have to change your code to special-case the latter. To 234 activate dummy caching, set ``CACHE_BACKEND`` like so::237 activate dummy caching, set :setting:`CACHE_BACKEND` like so:: 235 238 236 239 CACHE_BACKEND = 'dummy://' 237 240 … … Using a custom cache backend 243 246 While Django includes support for a number of cache backends out-of-the-box, 244 247 sometimes you might want to use a customized cache backend. To use an external 245 248 cache backend with Django, use a Python import path as the scheme portion (the 246 part before the initial colon) of the ``CACHE_BACKEND`` URI, like so::249 part before the initial colon) of the :setting:`CACHE_BACKEND` URI, like so:: 247 250 248 251 CACHE_BACKEND = 'path.to.backend://' 249 252 … … CACHE_BACKEND arguments 259 262 ----------------------- 260 263 261 264 Each cache backend may take arguments. They're given in query-string style on 262 the ``CACHE_BACKEND`` setting. Valid arguments are as follows:265 the :setting:`CACHE_BACKEND` setting. Valid arguments are as follows: 263 266 264 267 * ``timeout``: The default timeout, in seconds, to use for the cache. 265 268 This argument defaults to 300 seconds (5 minutes). … … entire site. You'll need to add 315 318 316 319 Then, add the following required settings to your Django settings file: 317 320 318 * ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be319 cached.320 * ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple321 sites using the same Django installation, set this to the name of the site,322 or some other string that is unique to this Django instance, to prevent key323 collisions. Use an empty string if you don't care.321 * :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should 322 be cached. 323 * :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across 324 multiple sites using the same Django installation, set this to the name of 325 the site, or some other string that is unique to this Django instance, to 326 prevent key collisions. Use an empty string if you don't care. 324 327 325 328 The cache middleware caches every page that doesn't have GET or POST 326 parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is 327 ``True``, only anonymous requests (i.e., not those made by a logged-in user) 328 will be cached. This is a simple and effective way of disabling caching for any 329 user-specific pages (include Django's admin interface). Note that if you use 330 ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated 331 ``AuthenticationMiddleware``. The cache middleware expects that a HEAD request 332 is answered with the same response headers exactly like the corresponding GET 333 request, in that case it could return cached GET response for HEAD request. 329 parameters. Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` 330 setting is ``True``, only anonymous requests (i.e., not those made by a 331 logged-in user) will be cached. This is a simple and effective way of disabling 332 caching for any user-specific pages (include Django's admin interface). Note 333 that if you use :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make 334 sure you've activated ``AuthenticationMiddleware``. The cache middleware 335 expects that a HEAD request is answered with the same response headers exactly 336 like the corresponding GET request, in that case it could return cached GET 337 response for HEAD request. 334 338 335 339 Additionally, the cache middleware automatically sets a few headers in each 336 340 ``HttpResponse``: … … Additionally, the cache middleware automatically sets a few headers in each 339 343 (uncached) version of the page is requested. 340 344 341 345 * Sets the ``Expires`` header to the current date/time plus the defined 342 ``CACHE_MIDDLEWARE_SECONDS``.346 :setting:`CACHE_MIDDLEWARE_SECONDS`. 343 347 344 348 * Sets the ``Cache-Control`` header to give a max age for the page -- 345 again, from the ``CACHE_MIDDLEWARE_SECONDS`` setting.349 again, from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting. 346 350 347 351 See :doc:`/topics/http/middleware` for more on middleware. 348 352 … … See :doc:`/topics/http/middleware` for more on middleware. 350 354 351 355 If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in 352 356 its ``Cache-Control`` header) then the page will be cached until the expiry 353 time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in357 time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in 354 358 ``django.views.decorators.cache`` you can easily set a view's expiry time 355 359 (using the ``cache_control`` decorator) or disable caching for a view (using 356 360 the ``never_cache`` decorator). See the `using other headers`__ section for … … __ `Controlling cache: Using other headers`_ 373 377 The per-view cache 374 378 ================== 375 379 380 .. function ``django.views.decorators.cache.cache_page`` 381 376 382 A more granular way to use the caching framework is by caching the output of 377 383 individual views. ``django.views.decorators.cache`` defines a ``cache_page`` 378 384 decorator that will automatically cache the view's response for you. It's easy … … then requests to ``/foo/1/`` and ``/foo/23/`` will be cached separately, as 402 408 you may expect. But once a particular URL (e.g., ``/foo/23/``) has been 403 409 requested, subsequent requests to that URL will use the cache. 404 410 405 ``cache_page`` can also take an optional keyword argument, ``key_prefix``, which406 w orks in the same way as the ``CACHE_MIDDLEWARE_KEY_PREFIX`` setting for the407 middleware. It can be used like this::411 ``cache_page`` can also take an optional keyword argument, ``key_prefix``, 412 which works in the same way as the :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` 413 setting for the middleware. It can be used like this:: 408 414 409 415 @cache_page(60 * 15, key_prefix="site1") 410 416 def my_view(request): … … can be pickled; refer to the Python documentation for more information about 529 535 pickling.) 530 536 531 537 The cache module, ``django.core.cache``, has a ``cache`` object that's 532 automatically created from the ``CACHE_BACKEND`` setting::538 automatically created from the :setting:`CACHE_BACKEND` setting:: 533 539 534 540 >>> from django.core.cache import cache 535 541 … … The basic interface is ``set(key, value, timeout)`` and ``get(key)``:: 540 546 'hello, world!' 541 547 542 548 The ``timeout`` argument is optional and defaults to the ``timeout`` 543 argument in the ``CACHE_BACKEND`` setting (explained above). It's the number of544 seconds the value should be stored in the cache.549 argument in the :setting:`CACHE_BACKEND` setting (explained above). It's the 550 number of seconds the value should be stored in the cache. 545 551 546 552 If the object doesn't exist in the cache, ``cache.get()`` returns ``None``:: 547 553 … … Here's a full list: 957 963 For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_. 958 964 959 965 (Note that the caching middleware already sets the cache header's max-age with 960 the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom966 the value of the :setting:`CACHE_MIDDLEWARE_SETTINGS` setting. If you use a custom 961 967 ``max_age`` in a ``cache_control`` decorator, the decorator will take 962 968 precedence, and the header values will be merged correctly.) 963 969 … … site's performance: 984 990 modern browsers to conditionally GET responses based on the ``ETag`` 985 991 and ``Last-Modified`` headers. 986 992 987 * ``django.middleware.gzip.GZipMiddleware`` compresses responses for all993 * :class:`django.middleware.gzip.GZipMiddleware` compresses responses for all 988 994 moderns browsers, saving bandwidth and transfer time. 989 995 990 996 Order of MIDDLEWARE_CLASSES 991 997 =========================== 992 998 993 999 If you use caching middleware, it's important to put each half in the right 994 place within the ``MIDDLEWARE_CLASSES`` setting. That's because the cache1000 place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache 995 1001 middleware needs to know which headers by which to vary the cache storage. 996 1002 Middleware always adds something to the ``Vary`` response header when it can. 997 1003