.. module:: flaskext.cache

Install the extension with one of the following commands:

$ easy_install Flask-Cache

or alternatively if you have pip installed:

$ pip install Flask-Cache

The following configuration values exist for Flask-Cache:

.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|

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

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)

To cache view functions you will use the :meth:`~Cache.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.

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()

See :meth:`~Cache.memoize`

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

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.:

@cache.memoize(50)
def user_has_membership(user, role):
        return Group.query.filter_by(user=user, role=role).count() >= 1

.. versionadded:: 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 :meth:`~Cache.delete_memoized` function.:

cache.delete_memoized('has_membership')

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

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

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 :class:`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

.. autoclass:: Cache
   :members: get, set, add, delete, cached, memoize, delete_memoized