diff options
Diffstat (limited to 'docs/topics/cache.txt')
| -rw-r--r-- | docs/topics/cache.txt | 170 |
1 files changed, 85 insertions, 85 deletions
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index ae6bb5c604..768bd245b8 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -94,15 +94,15 @@ two most common are `python-memcached`_ and `pylibmc`_. To use Memcached with Django: - * Set :setting:`BACKEND <CACHES-BACKEND>` to - ``django.core.cache.backends.memcached.MemcachedCache`` or - ``django.core.cache.backends.memcached.PyLibMCCache`` (depending - on your chosen memcached binding) +* Set :setting:`BACKEND <CACHES-BACKEND>` to + ``django.core.cache.backends.memcached.MemcachedCache`` or + ``django.core.cache.backends.memcached.PyLibMCCache`` (depending + on your chosen memcached binding) - * Set :setting:`LOCATION <CACHES-LOCATION>` to ``ip:port`` values, - where ``ip`` is the IP address of the Memcached daemon and ``port`` is the - port on which Memcached is running, or to a ``unix:path`` value, where - ``path`` is the path to a Memcached Unix socket file. +* Set :setting:`LOCATION <CACHES-LOCATION>` to ``ip:port`` values, + where ``ip`` is the IP address of the Memcached daemon and ``port`` is the + port on which Memcached is running, or to a ``unix:path`` value, where + ``path`` is the path to a Memcached Unix socket file. In this example, Memcached is running on localhost (127.0.0.1) port 11211, using the ``python-memcached`` binding:: @@ -358,55 +358,55 @@ backend, each cache backend can be given additional arguments to control caching behavior. These arguments are provided as additional keys in the :setting:`CACHES` setting. Valid arguments are as follows: - * :setting:`TIMEOUT <CACHES-TIMEOUT>`: The default timeout, in - seconds, to use for the cache. This argument defaults to 300 - seconds (5 minutes). +* :setting:`TIMEOUT <CACHES-TIMEOUT>`: The default timeout, in + seconds, to use for the cache. This argument defaults to 300 + seconds (5 minutes). - * :setting:`OPTIONS <CACHES-OPTIONS>`: Any options that should be - passed to cache backend. The list options understood by each - backend vary with each backend. +* :setting:`OPTIONS <CACHES-OPTIONS>`: Any options that should be + passed to cache backend. The list options understood by each + backend vary with each backend. - Cache backends that implement their own culling strategy (i.e., - the ``locmem``, ``filesystem`` and ``database`` backends) will - honor the following options: + Cache backends that implement their own culling strategy (i.e., + the ``locmem``, ``filesystem`` and ``database`` backends) will + honor the following options: - * ``MAX_ENTRIES``: the maximum number of entries allowed in - the cache before old values are deleted. This argument - defaults to ``300``. + * ``MAX_ENTRIES``: the maximum number of entries allowed in + the cache before old values are deleted. This argument + defaults to ``300``. - * ``CULL_FREQUENCY``: The fraction of entries that are culled - when ``MAX_ENTRIES`` is reached. The actual ratio is - ``1/CULL_FREQUENCY``, so set ``CULL_FREQUENCY``: to ``2`` to - cull half of the entries when ``MAX_ENTRIES`` is reached. + * ``CULL_FREQUENCY``: The fraction of entries that are culled + when ``MAX_ENTRIES`` is reached. The actual ratio is + ``1/CULL_FREQUENCY``, so set ``CULL_FREQUENCY``: to ``2`` to + cull half of the entries when ``MAX_ENTRIES`` is reached. - A value of ``0`` for ``CULL_FREQUENCY`` means that the - entire cache will be dumped when ``MAX_ENTRIES`` is reached. - This makes culling *much* faster at the expense of more - cache misses. + A value of ``0`` for ``CULL_FREQUENCY`` means that the + entire cache will be dumped when ``MAX_ENTRIES`` is reached. + This makes culling *much* faster at the expense of more + cache misses. - Cache backends backed by a third-party library will pass their - options directly to the underlying cache library. As a result, - the list of valid options depends on the library in use. + Cache backends backed by a third-party library will pass their + options directly to the underlying cache library. As a result, + the list of valid options depends on the library in use. - * :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`: A string that will be - automatically included (prepended by default) to all cache keys - used by the Django server. +* :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`: A string that will be + automatically included (prepended by default) to all cache keys + used by the Django server. - See the :ref:`cache documentation <cache_key_prefixing>` for - more information. + See the :ref:`cache documentation <cache_key_prefixing>` for + more information. - * :setting:`VERSION <CACHES-VERSION>`: The default version number - for cache keys generated by the Django server. +* :setting:`VERSION <CACHES-VERSION>`: The default version number + for cache keys generated by the Django server. - See the :ref:`cache documentation <cache_versioning>` for more - information. + See the :ref:`cache documentation <cache_versioning>` for more + information. - * :setting:`KEY_FUNCTION <CACHES-KEY_FUNCTION>` - A string containing a dotted path to a function that defines how - to compose a prefix, version and key into a final cache key. +* :setting:`KEY_FUNCTION <CACHES-KEY_FUNCTION>` + A string containing a dotted path to a function that defines how + to compose a prefix, version and key into a final cache key. - See the :ref:`cache documentation <cache_key_transformation>` - for more information. + See the :ref:`cache documentation <cache_key_transformation>` + for more information. In this example, a filesystem backend is being configured with a timeout of 60 seconds, and a maximum capacity of 1000 items:: @@ -470,14 +470,14 @@ response for HEAD request. Additionally, the cache middleware automatically sets a few headers in each :class:`~django.http.HttpResponse`: - * Sets the ``Last-Modified`` header to the current date/time when a fresh - (uncached) version of the page is requested. +* Sets the ``Last-Modified`` header to the current date/time when a fresh + (uncached) version of the page is requested. - * Sets the ``Expires`` header to the current date/time plus the defined - :setting:`CACHE_MIDDLEWARE_SECONDS`. +* Sets the ``Expires`` header to the current date/time plus the defined + :setting:`CACHE_MIDDLEWARE_SECONDS`. - * Sets the ``Cache-Control`` header to give a max age for the page -- - again, from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting. +* Sets the ``Cache-Control`` header to give a max age for the page -- + again, from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting. See :doc:`/topics/http/middleware` for more on middleware. @@ -932,21 +932,21 @@ reaches your Web site. Here are a few examples of upstream caches: - * Your ISP may cache certain pages, so if you requested a page from - http://example.com/, your ISP would send you the page without having to - access example.com directly. The maintainers of example.com have no - knowledge of this caching; the ISP sits between example.com and your Web - browser, handling all of the caching transparently. +* Your ISP may cache certain pages, so if you requested a page from + http://example.com/, your ISP would send you the page without having to + access example.com directly. The maintainers of example.com have no + knowledge of this caching; the ISP sits between example.com and your Web + browser, handling all of the caching transparently. - * Your Django Web site may sit behind a *proxy cache*, such as Squid Web - Proxy Cache (http://www.squid-cache.org/), that caches pages for - performance. In this case, each request first would be handled by the - proxy, and it would be passed to your application only if needed. +* Your Django Web site may sit behind a *proxy cache*, such as Squid Web + Proxy Cache (http://www.squid-cache.org/), that caches pages for + performance. In this case, each request first would be handled by the + proxy, and it would be passed to your application only if needed. - * Your Web browser caches pages, too. If a Web page sends out the - appropriate headers, your browser will use the local cached copy for - subsequent requests to that page, without even contacting the Web page - again to see whether it has changed. +* Your Web browser caches pages, too. If a Web page sends out the + appropriate headers, your browser will use the local cached copy for + subsequent requests to that page, without even contacting the Web page + again to see whether it has changed. Upstream caching is a nice efficiency boost, but there's a danger to it: Many Web pages' contents differ based on authentication and a host of other @@ -1099,12 +1099,12 @@ entries may be cached on any shared cache. The following code uses There are a few other ways to control cache parameters. For example, HTTP allows applications to do the following: - * Define the maximum time a page should be cached. +* Define the maximum time a page should be cached. - * Specify whether a cache should always check for newer versions, only - delivering the cached content when there are no changes. (Some caches - might deliver cached content even if the server page changed, simply - because the cache copy isn't yet expired.) +* Specify whether a cache should always check for newer versions, only + delivering the cached content when there are no changes. (Some caches + might deliver cached content even if the server page changed, simply + because the cache copy isn't yet expired.) In Django, use the ``cache_control`` view decorator to specify these cache parameters. In this example, ``cache_control`` tells caches to revalidate the @@ -1119,14 +1119,14 @@ cache on every access and to store cached versions for, at most, 3,600 seconds:: Any valid ``Cache-Control`` HTTP directive is valid in ``cache_control()``. Here's a full list: - * ``public=True`` - * ``private=True`` - * ``no_cache=True`` - * ``no_transform=True`` - * ``must_revalidate=True`` - * ``proxy_revalidate=True`` - * ``max_age=num_seconds`` - * ``s_maxage=num_seconds`` +* ``public=True`` +* ``private=True`` +* ``no_cache=True`` +* ``no_transform=True`` +* ``must_revalidate=True`` +* ``proxy_revalidate=True`` +* ``max_age=num_seconds`` +* ``s_maxage=num_seconds`` For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_. @@ -1154,12 +1154,12 @@ Other optimizations Django comes with a few other pieces of middleware that can help optimize your site's performance: - * ``django.middleware.http.ConditionalGetMiddleware`` adds support for - modern browsers to conditionally GET responses based on the ``ETag`` - and ``Last-Modified`` headers. +* ``django.middleware.http.ConditionalGetMiddleware`` adds support for + modern browsers to conditionally GET responses based on the ``ETag`` + and ``Last-Modified`` headers. - * :class:`django.middleware.gzip.GZipMiddleware` compresses responses for all - modern browsers, saving bandwidth and transfer time. +* :class:`django.middleware.gzip.GZipMiddleware` compresses responses for all + modern browsers, saving bandwidth and transfer time. Order of MIDDLEWARE_CLASSES =========================== @@ -1175,9 +1175,9 @@ response phase. Thus, you need to make sure that ``UpdateCacheMiddleware`` appears *before* any other middleware that might add something to the ``Vary`` header. The following middleware modules do so: - * ``SessionMiddleware`` adds ``Cookie`` - * ``GZipMiddleware`` adds ``Accept-Encoding`` - * ``LocaleMiddleware`` adds ``Accept-Language`` +* ``SessionMiddleware`` adds ``Cookie`` +* ``GZipMiddleware`` adds ``Accept-Encoding`` +* ``LocaleMiddleware`` adds ``Accept-Language`` ``FetchFromCacheMiddleware``, on the other hand, runs during the request phase, where middleware is applied first-to-last, so an item at the top of the list |