Toggle navigation

Cache

werkzeug.contrib.cache

The main problem with dynamic Web sites is, well, they’re dynamic. Each time a user requests a page, the webserver executes a lot of code, queries the database, renders templates until the visitor gets the page he sees.

This is a lot more expensive than just loading a file from the file system and sending it to the visitor.

For most Web applications, this overhead isn’t a big deal but once it becomes, you will be glad to have a cache system in place.

How Caching Works

Caching is pretty simple. Basically you have a cache object lurking around somewhere that is connected to a remote cache or the file system or something else. When the request comes in you check if the current page is already in the cache and if so, you’re returning it from the cache. Otherwise you generate the page and put it into the cache. (Or a fragment of the page, you don’t have to cache the full thing)

Here is a simple example of how to cache a sidebar for 5 minutes:

def get_sidebar(user):
    identifier = 'sidebar_for/user%d' % user.id
    value = cache.get(identifier)
    if value is not None:
        return value
    value = generate_sidebar_for(user=user)
    cache.set(identifier, value, timeout=60 * 5)
    return value

Creating a Cache Object

To create a cache object you just import the cache system of your choice from the cache module and instantiate it. Then you can start working with that object:

[UNKNOWN NODE doctest_block]

Please keep in mind that you have to create the cache and put it somewhere you have access to it (either as a module global you can import or you just put it into your WSGI application).

copyright
  1. 2014 by the Werkzeug Team, see AUTHORS for more details.
license
BSD, see LICENSE for more details.

Cache System API

class werkzeug.contrib.cache.BaseCache(default_timeout=300)

Baseclass for the cache systems. All the cache systems implement this API or a superset of it.

Parameters
default_timeout – the default timeout (in seconds) that is used if no timeout is specified on set(). A timeout of 0 indicates that the cache never expires.
add(key, value, timeout=None)

Works like set() but does not overwrite the values of already existing keys.

Parameters
  • key – the key to set
  • value – the value for the key
  • timeout – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 idicates that the cache never expires.
Returns
Same as set(), but also False for already existing keys.
Return type
boolean
clear()

Clears the cache. Keep in mind that not all caches support completely clearing the cache.

Returns
Whether the cache has been cleared.
Return type
boolean
dec(key, delta=1)

Decrements the value of a key by [UNKNOWN NODE title_reference]. If the key does not yet exist it is initialized with [UNKNOWN NODE title_reference].

For supporting caches this is an atomic operation.

Parameters
  • key – the key to increment.
  • delta – the delta to subtract.
Returns
The new value or [UNKNOWN NODE title_reference] for backend errors.
delete(key)

Delete [UNKNOWN NODE title_reference] from the cache.

Parameters
key – the key to delete.
Returns
Whether the key existed and has been deleted.
Return type
boolean
delete_many(*keys)

Deletes multiple keys at once.

Parameters
keys – The function accepts multiple keys as positional arguments.
Returns
Whether all given keys have been deleted.
Return type
boolean
get(key)

Look up key in the cache and return the value for it.

Parameters
key – the key to be looked up.
Returns
The value if it exists and is readable, else None.
get_dict(*keys)

Like get_many() but return a dict:

d = cache.get_dict("foo", "bar")
foo = d["foo"]
bar = d["bar"]
Parameters
keys – The function accepts multiple keys as positional arguments.
get_many(*keys)

Returns a list of values for the given keys. For each key an item in the list is created:

foo, bar = cache.get_many("foo", "bar")

Has the same error handling as get().

Parameters
keys – The function accepts multiple keys as positional arguments.
has(key)

Checks if a key exists in the cache without returning it. This is a cheap operation that bypasses loading the actual data on the backend.

This method is optional and may not be implemented on all caches.

Parameters
key – the key to check
inc(key, delta=1)

Increments the value of a key by [UNKNOWN NODE title_reference]. If the key does not yet exist it is initialized with [UNKNOWN NODE title_reference].

For supporting caches this is an atomic operation.

Parameters
  • key – the key to increment.
  • delta – the delta to add.
Returns
The new value or None for backend errors.
set(key, value, timeout=None)

Add a new key/value to the cache (overwrites value, if key already exists in the cache).

Parameters
  • key – the key to set
  • value – the value for the key
  • timeout – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 idicates that the cache never expires.
Returns
True if key has been updated, False for backend errors. Pickling errors, however, will raise a subclass of pickle.PickleError.
Return type
boolean
set_many(mapping, timeout=None)

Sets multiple keys and values from a mapping.

Parameters
  • mapping – a mapping with the keys/values to set.
  • timeout – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 idicates that the cache never expires.
Returns
Whether all given keys have been set.
Return type
boolean

Cache Systems

class werkzeug.contrib.cache.NullCache(default_timeout=300)

A cache that doesn’t cache. This can be useful for unit testing.

Parameters
default_timeout – a dummy parameter that is ignored but exists for API compatibility with other caches.
class werkzeug.contrib.cache.SimpleCache(threshold=500, default_timeout=300)

Simple memory cache for single process environments. This class exists mainly for the development server and is not 100% thread safe. It tries to use as many atomic operations as possible and no locks for simplicity but it could happen under heavy load that keys are added multiple times.

Parameters
  • threshold – the maximum number of items the cache stores before it starts deleting some.
  • default_timeout – the default timeout that is used if no timeout is specified on set(). A timeout of 0 indicates that the cache never expires.
class werkzeug.contrib.cache.MemcachedCache(servers=None, default_timeout=300, key_prefix=None)

A cache that uses memcached as backend.

The first argument can either be an object that resembles the API of a memcache.Client or a tuple/list of server addresses. In the event that a tuple/list is passed, Werkzeug tries to import the best available memcache library.

This cache looks into the following packages/modules to find bindings for memcached:

  • pylibmc
  • google.appengine.api.memcached
  • memcached
  • libmc

Implementation notes: This cache backend works around some limitations in memcached to simplify the interface. For example unicode keys are encoded to utf-8 on the fly. Methods such as get_dict() return the keys in the same format as passed. Furthermore all get methods silently ignore key errors to not cause problems when untrusted user data is passed to the get methods which is often the case in web applications.

Parameters
  • servers – a list or tuple of server addresses or alternatively a memcache.Client or a compatible client.
  • default_timeout – the default timeout that is used if no timeout is specified on set(). A timeout of 0 indicates that the cache never expires.
  • key_prefix – a prefix that is added before all keys. This makes it possible to use the same memcached server for different applications. Keep in mind that clear() will also clear keys with a different prefix.
class werkzeug.contrib.cache.GAEMemcachedCache

This class is deprecated in favour of MemcachedCache which now supports Google Appengine as well.

Changed in version 0.8: Deprecated in favour of MemcachedCache.

class werkzeug.contrib.cache.RedisCache(host='localhost', port=6379, password=None, db=0, default_timeout=300, key_prefix=None, **kwargs)

Uses the Redis key-value store as a cache backend.

The first argument can be either a string denoting address of the Redis server or an object resembling an instance of a redis.Redis class.

Note: Python Redis API already takes care of encoding unicode strings on the fly.

New in version 0.7.

New in version 0.8: [UNKNOWN NODE title_reference] was added.

Changed in version 0.8: This cache backend now properly serializes objects.

Changed in version 0.8.3: This cache backend now supports password authentication.

Changed in version 0.10: **kwargs is now passed to the redis object.

Parameters
  • host – address of the Redis server or an object which API is compatible with the official Python Redis client (redis-py).
  • port – port number on which Redis server listens for connections.
  • password – password authentication for the Redis server.
  • db – db (zero-based numeric index) on Redis Server to connect.
  • default_timeout – the default timeout that is used if no timeout is specified on set(). A timeout of 0 indicates that the cache never expires.
  • key_prefix – A prefix that should be added to all keys.

Any additional keyword arguments will be passed to redis.Redis.

class werkzeug.contrib.cache.FileSystemCache(cache_dir, threshold=500, default_timeout=300, mode=384)

A cache that stores the items on the file system. This cache depends on being the only user of the [UNKNOWN NODE title_reference]. Make absolutely sure that nobody but this cache stores files there or otherwise the cache will randomly delete files therein.

Parameters
  • cache_dir – the directory where cache files are stored.
  • threshold – the maximum number of items the cache stores before it starts deleting some. A threshold value of 0 indicates no threshold.
  • default_timeout – the default timeout that is used if no timeout is specified on set(). A timeout of 0 indicates that the cache never expires.
  • mode – the file mode wanted for the cache files, default 0600
class werkzeug.contrib.cache.UWSGICache(default_timeout=300, cache='')

Implements the cache using uWSGI’s caching framework.

Parameters
  • default_timeout – The default timeout in seconds.
  • cache – The name of the caching instance to connect to, for example: mycache@localhost:3031, defaults to an empty string, which means uWSGI will cache in the local instance. If the cache is in the same instance as the werkzeug app, you only have to provide the name of the cache.