Flask-CacheControl

Description

A light-weight library to conveniently set Cache-Control headers on the response. Decorate view functions with cache_for, cache, or dont_cache decorators. Makes use of Flask response.cache_control.

This extension does not provide any caching of its own. Its sole purpose is to set Cache-Control and related HTTP headers on the response, so that clients, intermediary proxies or reverse proxies in your jurisdiction which evaluate Cache-Control headers, such as Varnish Cache, do the caching for you.

By default, Cache-Control headers are only appended in case of a successful response (status code 2xx). This behaviour can be controlled with the only_if argument to cache_for and cache decorators. Included options are Always, ResponseIsSuccessful, ResponseIsSuccessfulOrRedirect. Custom behaviour can be implemented by subclassing OnlyIfEvaluatorBase.

If the vary keyword argument is given to cache_for or cache decorators, the Vary HTTP header is returned with the response. Vary headers are appended independent of response status code.

Example

from flask import Flask, render_template
from flask_cachecontrol import (
    cache,
    cache_for,
    dont_cache,
    Always, 
    ResponseIsSuccessfulOrRedirect)


app = Flask(__name__)


@app.route('/')
@cache_for(hours=3)
def index_view():
    return render_template('index_template')

@app.route('/users')
@cache_for(minutes=5, only_if=ResponseIsSuccessfulOrRedirect)
def users_view():
    return render_template('user_template')

@app.route('/stats')
@cache(max_age=3600, public=True, only_if=Always, vary=['User-Agent', 'Referer'])
def stats_view():
    return render_template('stats_template')

@app.route('/dashboard')
@dont_cache()
def dashboard_view():
    return render_template('dashboard_template')

Changelog

0.3.0

• Add only_if evaluator for successful or redirect (2xx, 3xx) responses (#7)
• Support Vary-headers (#6)
• Improve instantiation of callbacks and registry provider
• BREAKING: Simplify instantiation and hooking into flask response handling (#8)
  • No more need to instantiate FlaskCacheControl for Flask app.
• BREAKING: Drop support for only_if=None
  • Use more explicit only_if=Always instead
• BREAKING: Restructure modules
  • Direct imports from modules inside the package need to be adapted.
• Improve test structuring
• Fix flask instantiation and import in example

v0.2.1

• Fix import statement in example

v0.2.0

• Add tests
• BREAKING: By default, cache control headers are only applied to successful requests. (status code 2xx) This behaviour can be customized by providing only_if= as a kw to all caching decorators.
• BREAKING: Requires python 3.3 or higher