Flask-Cache¶

Installation¶

Install the extension with one of the following commands:

$ easy_install Flask-Cache

or alternatively if you have pip installed:

$ pip install Flask-Cache

Set Up¶

Cache is managed through a Cache instance:

from flask import Flask
from flask.ext.cache import Cache

app = Flask(__name__)
# Check Configuring Flask-Cache section for more details
cache = Cache(app,config={'CACHE_TYPE': 'simple'})

You may also set up your Cache instance later at configuration time using init_app method:

cache = Cache(config={'CACHE_TYPE': 'simple'})

app = Flask(__name__)
cache.init_app(app)

You may also provide an alternate configuration dictionary, useful if there will be multiple Cache instances each with a different backend.:

#: Method A: During instantiation of class
cache = Cache(config={'CACHE_TYPE': 'simple'})
#: Method B: During init_app call
cache.init_app(app, config={'CACHE_TYPE': 'simple'})

New in version 0.7.

Caching View Functions¶

To cache view functions you will use the cached() decorator. This decorator will use request.path by default for the cache_key.:

@cache.cached(timeout=50)
def index():
    return render_template('index.html')

The cached decorator has another optional argument called unless. This argument accepts a callable that returns True or False. If unless returns True then it will bypass the caching mechanism entirely.

Caching Other Functions¶

Using the same @cached decorator you are able to cache the result of other non-view related functions. The only stipulation is that you replace the key_prefix, otherwise it will use the request.path cache_key.:

@cache.cached(timeout=50, key_prefix='all_comments')
def get_all_comments():
    comments = do_serious_dbio()
    return [x.author for x in comments]

cached_comments = get_all_comments()

Memoization¶

See memoize()

In memoization, the functions arguments are also included into the cache_key.

Note

With functions that do not receive arguments, cached() and memoize() are effectively the same.

Memoize is also designed for methods, since it will take into account the identity. of the ‘self’ or ‘cls’ argument as part of the cache key.

The theory behind memoization is that if you have a function you need to call several times in one request, it would only be calculated the first time that function is called with those arguments. For example, an sqlalchemy object that determines if a user has a role. You might need to call this function many times during a single request. To keep from hitting the database every time this information is needed you might do something like the following:

class Person(db.Model):
    @cache.memoize(50)
    def has_membership(self, role_id):
            return Group.query.filter_by(user=self, role_id=role_id).count() >= 1

Warning

Using mutable objects (classes, etc) as part of the cache key can become tricky. It is suggested to not pass in an object instance into a memoized function. However, the memoize does perform a repr() on the passed in arguments so that if the object has a __repr__ function that returns a uniquely identifying string for that object, that will be used as part of the cache key.

For example, an sqlalchemy person object that returns the database id as part of the unique identifier.:

class Person(db.Model):
    def __repr__(self):
        return "%s(%s)" % (self.__class__.__name__, self.id)

Deleting memoize cache¶

New in version 0.2.

You might need to delete the cache on a per-function bases. Using the above example, lets say you change the users permissions and assign them to a role, but now you need to re-calculate if they have certain memberships or not. You can do this with the delete_memoized() function.:

cache.delete_memoized('user_has_membership')

Note

If only the function name is given as parameter, all the memoized versions of it will be invalidated. However, you can delete specific cache by providing the same parameter values as when caching. In following example only the user-role cache is deleted:

user_has_membership('demo', 'admin')
user_has_membership('demo', 'user')

cache.delete_memoized('user_has_membership', 'demo', 'user')

Caching Jinja2 Snippets¶

Usage:

{% cache [timeout [,[key1, [key2, ...]]]] %}
...
{% endcache %}

By default the value of “path to template file” + “block start line” is used as cache key. Also key name can be set manually. Keys are concated together into a single string. that can be used to avoid the same block evaluating in different templates.

Set timeout to “del” to delete cached value:

{% cache 'del' %}...

If keys are provided, you may easily generate the template fragment key and delete it from outside of the template context:

from flask.ext.cache import make_template_fragment_key
key = make_template_fragment_key("key1", vary_on=["key2", "key3"])
cache.delete(key)

Example:

Considering we have render_form_field and render_submit macroses.
{% cache 60*5 %}
<div>
    <form>
    {% render_form_field form.username %}
    {% render_submit %}
    </form>
</div>
{% endcache %}

Clearing Cache¶

See clear().

Here’s an example script to empty your application’s cache:

from flask.ext.cache import Cache

from yourapp import app, your_cache_config

cache = Cache()


def main():
    cache.init_app(app, config=your_cache_config)

    with app.app_context():
        cache.clear()

if __name__ == '__main__':
    main()

Warning

Some backend implementations do not support completely clearing the cache. Also, if you’re not using a key prefix, some implementations (e.g. Redis) will flush the whole database. Make sure you’re not storing any other data in your caching database.

Configuring Flask-Cache¶

The following configuration values exist for Flask-Cache:

`CACHE_TYPE`	Specifies which type of caching object to use. This is an import string that will be imported and instantiated. It is assumed that the import object is a function that will return a cache object that adheres to the werkzeug cache API. For werkzeug.contrib.cache objects, you do not need to specify the entire import string, just one of the following names. Built-in cache types: null: NullCache (default) simple: SimpleCache memcached: MemcachedCache (pylibmc or memcache required) gaememcached: GAEMemcachedCache redis: RedisCache (Werkzeug 0.7 required) filesystem: FileSystemCache saslmemcached: SASLMemcachedCache (pylibmc required)
`CACHE_NO_NULL_WARNING`	Silents the warning message when using cache type of ‘null’.
`CACHE_ARGS`	Optional list to unpack and pass during the cache class instantiation.
`CACHE_OPTIONS`	Optional dictionary to pass during the cache class instantiation.
`CACHE_DEFAULT_TIMEOUT`	The default timeout that is used if no timeout is specified. Unit of time is seconds.
`CACHE_THRESHOLD`	The maximum number of items the cache will store before it starts deleting some. Used only for SimpleCache and FileSystemCache
`CACHE_KEY_PREFIX`	A prefix that is added before all keys. This makes it possible to use the same memcached server for different apps. Used only for RedisCache, MemcachedCache and GAEMemcachedCache.
`CACHE_MEMCACHED_SERVERS`	A list or a tuple of server addresses. Used only for MemcachedCache
`CACHE_MEMCACHED_USERNAME`	Username for SASL authentication with memcached. Used only for SASLMemcachedCache
`CACHE_MEMCACHED_PASSWORD`	Password for SASL authentication with memcached. Used only for SASLMemcachedCache
`CACHE_REDIS_HOST`	A Redis server host. Used only for RedisCache.
`CACHE_REDIS_PORT`	A Redis server port. Default is 6379. Used only for RedisCache.
`CACHE_REDIS_PASSWORD`	A Redis password for server. Used only for RedisCache.
`CACHE_REDIS_DB`	A Redis db (zero-based number index). Default is 0. Used only for RedisCache.
`CACHE_DIR`	Directory to store cache. Used only for FileSystemCache.
`CACHE_REDIS_URL`	URL to connect to Redis server. Example `redis://user:password@localhost:6379/2`. Used only for RedisCache.

In addition the standard Flask TESTING configuration option is used. If this is True then Flask-Cache will use NullCache only.

Built-in Cache Backends¶

NullCache – null¶

Cache that doesn’t cache

CACHE_ARGS
CACHE_OPTIONS

SimpleCache – simple¶

Uses a local python dictionary for caching. This is not really thread safe.

Relevant configuration values

CACHE_DEFAULT_TIMEOUT
CACHE_THRESHOLD
CACHE_ARGS
CACHE_OPTIONS

FileSystemCache – filesystem¶

Uses the filesystem to store cached values

CACHE_DEFAULT_TIMEOUT
CACHE_DIR
CACHE_THRESHOLD
CACHE_ARGS
CACHE_OPTIONS

MemcachedCache – memcached¶

Uses a memcached server as a backend. Supports either pylibmc or memcache or google app engine memcache library.

Relevant configuration values

CACHE_DEFAULT_TIMEOUT
CACHE_KEY_PREFIX
CACHE_MEMCACHED_SERVERS
CACHE_ARGS
CACHE_OPTIONS

GAEMemcachedCache – gaememcached¶

Is MemcachedCache under a different name

SASLMemcachedCache – saslmemcached¶

Uses a memcached server as a backend. Intended to be used with a SASL enabled connection to the memcached server. pylibmc is required and SASL must be supported by libmemcached.

Relevant configuration values

CACHE_DEFAULT_TIMEOUT
CACHE_KEY_PREFIX
CACHE_MEMCACHED_SERVERS
CACHE_MEMCACHED_USERNAME
CACHE_MEMCACHED_PASSWORD
CACHE_ARGS
CACHE_OPTIONS

New in version 0.10.

SpreadSASLMemcachedCache – spreadsaslmemcachedcache¶

Same as SASLMemcachedCache however, it has the ablity to spread value across multiple keys if it is bigger than the memcached treshold which by default is 1M. Uses pickle.

New in version 0.11.

RedisCache – redis¶

CACHE_DEFAULT_TIMEOUT
CACHE_KEY_PREFIX
CACHE_REDIS_HOST
CACHE_REDIS_PORT
CACHE_REDIS_PASSWORD
CACHE_REDIS_DB
CACHE_ARGS
CACHE_OPTIONS
CACHE_REDIS_URL

Custom Cache Backends¶

You are able to easily add your own custom cache backends by exposing a function that can instantiate and return a cache object. CACHE_TYPE will be the import string to your custom function. It should expect to receive three arguments.

app
args
kwargs

Your custom cache object must also subclass the werkzeug.contrib.cache.BaseCache class. Flask-Cache will make sure that threshold is already included in the kwargs options dictionary since it is common to all BaseCache classes.

An example Redis cache implementation:

#: the_app/custom.py
class RedisCache(BaseCache):
    def __init__(self, servers, default_timeout=500):
        pass

def redis(app, config, args, kwargs):
   args.append(app.config['REDIS_SERVERS'])
   return RedisCache(*args, **kwargs)

With this example, your CACHE_TYPE might be the_app.custom.redis

An example PylibMC cache implementation to change binary setting and provide username/password if SASL is enabled on the library:

#: the_app/custom.py
def pylibmccache(app, config, args, kwargs):
    return pylibmc.Client(servers=config['CACHE_MEMCACHED_SERVERS'],
                          username=config['CACHE_MEMCACHED_USERNAME'],
                          password=config['CACHE_MEMCACHED_PASSWORD'],
                          binary=True)

With this example, your CACHE_TYPE might be the_app.custom.pylibmccache

API¶

class flask.ext.cache.Cache(app=None, with_jinja2_ext=True, config=None)¶

This class is used to control the cache objects.

init_app(app, config=None)¶: This is used to initialize cache with your app object

get(*args, **kwargs)¶: Proxy function for internal cache object.

set(*args, **kwargs)¶: Proxy function for internal cache object.

add(*args, **kwargs)¶: Proxy function for internal cache object.

delete(*args, **kwargs)¶: Proxy function for internal cache object.

get_many(*args, **kwargs)¶: Proxy function for internal cache object.

set_many(*args, **kwargs)¶: Proxy function for internal cache object.

delete_many(*args, **kwargs)¶: Proxy function for internal cache object.

clear()¶: Proxy function for internal cache object.

cached(timeout=None, key_prefix='view/%s', unless=None)¶

Decorator. Use this to cache a function. By default the cache key is view/request.path. You are able to use this decorator with any function by changing the key_prefix. If the token %s is located within the key_prefix then it will replace that with request.path

Example:

# An example view function
@cache.cached(timeout=50)
def big_foo():
    return big_bar_calc()

# An example misc function to cache.
@cache.cached(key_prefix='MyCachedList')
def get_list():
    return [random.randrange(0, 1) for i in range(50000)]

my_list = get_list()

Note

You MUST have a request context to actually called any functions that are cached.

New in version 0.4: The returned decorated function now has three function attributes assigned to it. These attributes are readable/writable.

uncached

The original undecorated function

cache_timeout

The cache timeout value for this function. For a custom value to take affect, this must be set before the function is called.

make_cache_key

A function used in generating the cache_key used.

Parameters:

Parameters:	timeout – Default None. If set to an integer, will cache for that amount of time. Unit of time is in seconds. key_prefix – Default ‘view/%(request.path)s’. Beginning key to . use for the cache key. New in version 0.3.4: Can optionally be a callable which takes no arguments but returns a string that will be used as the cache_key. unless – Default None. Cache will always execute the caching facilities unless this callable is true. This will bypass the caching entirely.

timeout – Default None. If set to an integer, will cache for that amount of time. Unit of time is in seconds.
key_prefix –
Default ‘view/%(request.path)s’. Beginning key to . use for the cache key.

New in version 0.3.4: Can optionally be a callable which takes no arguments but returns a string that will be used as the cache_key.
unless – Default None. Cache will always execute the caching facilities unless this callable is true. This will bypass the caching entirely.

memoize(timeout=None, make_name=None, unless=None)¶

Use this to cache the result of a function, taking its arguments into account in the cache key.

Information on Memoization.

Example:

@cache.memoize(timeout=50)
def big_foo(a, b):
    return a + b + random.randrange(0, 1000)

>>> big_foo(5, 2)
753
>>> big_foo(5, 3)
234
>>> big_foo(5, 2)
753

New in version 0.4: The returned decorated function now has three function attributes assigned to it.

uncached

The original undecorated function. readable only

cache_timeout

The cache timeout value for this function. For a custom value to take affect, this must be set before the function is called.

readable and writable

make_cache_key

A function used in generating the cache_key used.

readable and writable

Parameters:

Parameters:	timeout – Default None. If set to an integer, will cache for that amount of time. Unit of time is in seconds. make_name – Default None. If set this is a function that accepts a single argument, the function name, and returns a new string to be used as the function name. If not set then the function name is used. unless – Default None. Cache will always execute the caching facilities unelss this callable is true. This will bypass the caching entirely.

timeout – Default None. If set to an integer, will cache for that amount of time. Unit of time is in seconds.
make_name – Default None. If set this is a function that accepts a single argument, the function name, and returns a new string to be used as the function name. If not set then the function name is used.
unless – Default None. Cache will always execute the caching facilities unelss this callable is true. This will bypass the caching entirely.

New in version 0.5: params make_name, unless

delete_memoized(f, *args, **kwargs)¶

Deletes the specified functions caches, based by given parameters. If parameters are given, only the functions that were memoized with them will be erased. Otherwise all versions of the caches will be forgotten.

Example:

@cache.memoize(50)
def random_func():
    return random.randrange(1, 50)

@cache.memoize()
def param_func(a, b):
    return a+b+random.randrange(1, 50)

>>> random_func()
43
>>> random_func()
43
>>> cache.delete_memoized('random_func')
>>> random_func()
16
>>> param_func(1, 2)
32
>>> param_func(1, 2)
32
>>> param_func(2, 2)
47
>>> cache.delete_memoized('param_func', 1, 2)
>>> param_func(1, 2)
13
>>> param_func(2, 2)
47

Delete memoized is also smart about instance methods vs class methods.

When passing a instancemethod, it will only clear the cache related to that instance of that object. (object uniqueness can be overridden

by defining the __repr__ method, such as user id).

When passing a classmethod, it will clear all caches related across all instances of that class.

Example:

class Adder(object):
    @cache.memoize()
    def add(self, b):
        return b + random.random()

>>> adder1 = Adder()
>>> adder2 = Adder()
>>> adder1.add(3)
3.23214234
>>> adder2.add(3)
3.60898509
>>> cache.delete_memoized(adder.add)
>>> adder1.add(3)
3.01348673
>>> adder2.add(3)
3.60898509
>>> cache.delete_memoized(Adder.add)
>>> adder1.add(3)
3.53235667
>>> adder2.add(3)
3.72341788

Parameters:	fname – Name of the memoized function, or a reference to the function. args – A list of positional parameters used with memoized function. *kwargs – A dict of named parameters used with memoized function.

Note

Flask-Cache uses inspect to order kwargs into positional args when the function is memoized. If you pass a function reference into fname instead of the function name, Flask-Cache will be able to place the args/kwargs in the proper order, and delete the positional cache.

However, if delete_memoized is just called with the name of the function, be sure to pass in potential arguments in the same order as defined in your function as args only, otherwise Flask-Cache will not be able to compute the same cache key.

Note

Flask-Cache maintains an internal random version hash for the function. Using delete_memoized will only swap out the version hash, causing the memoize function to recompute results and put them into another key.

This leaves any computed caches for this memoized function within the caching backend.

It is recommended to use a very high timeout with memoize if using this function, so that when the version has is swapped, the old cached results would eventually be reclaimed by the caching backend.

delete_memoized_verhash(f, *args)¶

Delete the version hash associated with the function.

..warning:

Performing this operation could leave keys behind that have
been created with this version hash. It is up to the application
to make sure that all keys that may have been created with this
version hash at least have timeouts so they will not sit orphaned
in the cache backend.

Changelog¶

Version 0.13 2014-04-21¶

Port to Python >= 3.3 (requiring Python 2.6/2.7 for 2.x).
Fixed bug with using per-memoize timeouts greater than the default timeout
Added better support for per-instance memoization.
Various bug fixes

Version 0.12 2013-04-29¶

Changes jinja2 cache templates to use stable predictable keys. Previously the key for a cache tag included the line number of the template, which made it difficult to predict what the key would be outside of the application.
Adds config variable CACHE_NO_NULL_WARNING to silence warning messages when using ‘null’ cache as part of testing.
Adds passthrough to clear entire cache backend.

Version 0.11.1 2013-04-7¶

Bugfix for using memoize on instance methods. The previous key was id(self), the new key is repr(self)

Version 0.11 2013-03-23¶

Fail gracefully in production if cache backend raises an exception.
Support for redis DB number
Jinja2 templatetag cache now concats all args together into a single key instead of treating each arg as a separate key name.
Added delete memcache version hash function
Support for multiple cache objects on a single app again.
Added SpreadSASLMemcached, if a value is greater than the memcached threshold which defaults to 1MB, this splits the value across multiple keys.
Added support to use URL to connect to redis.

Version 0.10.1 2013-01-13¶

Added warning message when using cache type of ‘null’
Changed imports to relative instead of absolute for AppEngine compatibility

Version 0.10.0 2013-01-05¶

Added saslmemcached backend to support Memcached behind SASL authentication.
Fixes a bug with memoize when the number of args != number of kwargs

Version 0.9.2 2012-11-18¶

Bugfix with default kwargs

Version 0.9.1 2012-11-16¶

Fixes broken memoized on functions that use default kwargs

Version 0.9.0 2012-10-14¶

Fixes memoization to work on methods.

Version 0.8.0 2012-09-30¶

Migrated to the new flask extension naming convention of flask_cache instead of flaskext.cache
Removed unnecessary dependencies in setup.py file.
Documentation updates

Version 0.7.0 2012-08-25¶

Allows multiple cache objects to be instantiated with different configuration values.

Version 0.6.0 2012-08-12¶

Memoization is now safer for multiple applications using the same backing store.
Removed the explicit set of NullCache if the Flask app is set testing=True
Swapped Conditional order for key_prefix

Version 0.5.0 2012-02-03¶

Deleting memoized functions now properly functions in production environments where multiple instances of the application are running.
get_memoized_names and get_memoized_keys have been removed.
Added make_name to memoize, make_name is an optional callable that can be passed to memoize to modify the cache_key that gets generated.
Added unless to memoize, this is the same as the unless parameter in cached
memoization now converts all kwargs to positional arguments, this is so that when a function is called multiple ways, it would evaluate to the same cache_key

Version 0.4.0 2011-12-11¶

Added attributes for uncached, make_cache_key, cache_timeout to the decorated functions.

Version 0.3.4 2011-09-10¶

UTF-8 encoding of cache key
key_prefix argument of the cached decorator now supports callables.

Version 0.3.3 2011-06-03¶

Uses base64 for memoize caching. This fixes rare issues where the cache_key was either a tuple or larger than the caching backend would be able to support.

Adds support for deleting memoized caches optionally based on function parameters.

Python 2.5 compatibility, plus bugfix with string.format.

Added the ability to retrieve memoized function names or cache keys.

Version 0.3.2¶

Bugfix release. Fixes a bug that would cause an exception if no CACHE_TYPE was supplied.

Version 0.3.1¶

Pypi egg fix.

Version 0.3¶

CACHE_TYPE changed. Now one of [‘null’, ‘simple’, ‘memcached’, ‘gaememcached’, ‘filesystem’], or an import string to a function that will instantiate a cache object. This allows Flask-Cache to be much more extensible and configurable.

Version 0.2¶

CACHE_TYPE now uses an import_string.
Added CACHE_OPTIONS and CACHE_ARGS configuration values.
Added delete_memoized

Version 0.1¶

Initial public release