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
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:
|
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 MemcachedCache and GAEMemcachedCache. |
CACHE_MEMCACHED_SERVERS |
A list or a tuple of server addresses. Used only for MemcachedCache |
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_DIR |
Directory to store cache. Used only for FileSystemCache. |
In addition the standard Flask TESTING
configuration option is used. If this
is True then Flask-Cache will use NullCache only.
Set Up¶
Cache is managed through a Cache
instance:
from flask import Flask
from flaskext.cache import Cache
app = Flask(__name__)
cache = Cache(app)
You may also set up your Cache
instance later at configuration time using
init_app method:
cache = Cache()
app = Flask(__name__)
cache.init_app(app)
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 instance objects, since it will take into account that functions id. The theory here 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.:
User(db.Model):
@cache.memoize(50)
def has_membership(role):
return self.groups.filter_by(role=role).count() >= 1
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('has_membership')
Note
If only the function name is given as parameter, all the memoized versions
of it will be erazed. However, you can delete specific cache by providing the
same parameter values as when caching. In following example only the user
-roled cache is erased:
has_membership('admin')
has_membership('user')
cache.delete_memoized('has_membership', 'user')
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, args, kwargs):
args.append(app.config['REDIS_SERVERS'])
return RedisCache(*args, **kwargs)
With this example, your CACHE_TYPE
might be the_app.custom.redis
API¶
Changelog¶
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