diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..af28ca5a --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,83 @@ +API +=== + +This section contains the API documentation of the Flask-Caching extension and +lists the backends which are supported out of the box. +The `Configuration `_ section explains +how the backends can be used. + + +.. module:: flask_caching + +Cache API +--------- + +.. autoclass:: Cache + :members: init_app, get, set, add, delete, get_many, set_many, delete_many, + clear, cached, memoize, delete_memoized, delete_memoized_verhash + + +Backends +-------- + +.. module:: flask_caching.backends + +BaseCache +````````` + +.. autoclass:: flask_caching.backends.base.BaseCache + :members: + +NullCache +````````` + +.. autoclass:: NullCache + :members: + +SimpleCache +``````````` + +.. autoclass:: SimpleCache + :members: + +FileSystemCache +``````````````` + +.. autoclass:: FileSystemCache + :members: + +RedisCache +`````````` + +.. autoclass:: RedisCache + :members: + +RedisSentinelCache +`````````````````` + +.. autoclass:: RedisSentinelCache + :members: + +UWSGICache +`````````` + +.. autoclass:: UWSGICache + :members: + +MemcachedCache +`````````````` + +.. autoclass:: MemcachedCache + :members: + +SASLMemcachedCache +`````````````````` + +.. autoclass:: SASLMemcachedCache + :members: + +SpreadSASLMemcachedCache +```````````````````````` + +.. autoclass:: SpreadSASLMemcachedCache + :members: diff --git a/docs/conf.py b/docs/conf.py index c82f438d..1ef77f36 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,8 @@ # The master toctree document. master_doc = 'index' +autodoc_member_order = "bysource" + # General information about the project. project = u'Flask-Caching' copyright = u'2016, Thadeus Burgess, Peter Justin' diff --git a/docs/index.rst b/docs/index.rst index 432de66c..1e7481f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,9 +30,15 @@ Cache is managed through a ``Cache`` instance:: from flask import Flask from flask_caching import Cache + config = { + "DEBUG": True, # some Flask specific configs + "CACHE_TYPE": "simple", # Flask-Caching related configs + "CACHE_DEFAULT_TIMEOUT": 300 + } app = Flask(__name__) - # Check Configuring Flask-Caching section for more details - cache = Cache(app, config={'CACHE_TYPE': 'simple'}) + # tell Flask to use the above defined config + app.config.from_mapping(config) + cache = Cache(app) You may also set up your ``Cache`` instance later at configuration time using **init_app** method:: @@ -42,8 +48,8 @@ You may also set up your ``Cache`` instance later at configuration time using 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:: +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'}) @@ -252,6 +258,28 @@ Here's an example script to empty your application's cache: data in your caching database. +Explicitly Caching Data +----------------------- + +Data can be cached explicitly by using the proxy methods like +:meth:`Cache.set`, and :meth:`Cache.get` directly. There are many other proxy +methods available via the :class:`Cache` class. + +For example: + +.. code-block:: python + + @app.route("/html") + @app.route("/html/") + def html(foo=None): + if foo is not None: + cache.set("foo", foo) + bar = cache.get("foo") + return render_template_string( + "foo cache: {{bar}}", bar=bar + ) + + Configuring Flask-Caching ------------------------- @@ -282,7 +310,7 @@ The following configuration values exist for Flask-Caching: * **redissentinel**: RedisSentinelCache (redis required) * **uwsgi**: UWSGICache (uwsgi required) * **memcached**: MemcachedCache (pylibmc or memcache required) - * **gaememcached**: same as memcached -- backwards compatibility) + * **gaememcached**: same as memcached (for backwards compatibility) * **saslmemcached**: SASLMemcachedCache (pylibmc required) * **spreadsaslmemcached**: SpreadSASLMemcachedCache (pylibmc required) @@ -536,9 +564,10 @@ With this example, your ``CACHE_TYPE`` might be ``the_app.custom.pylibmccache`` API --- -.. autoclass:: Cache - :members: init_app, get, set, add, delete, get_many, set_many, delete_many, - clear, cached, memoize, delete_memoized, delete_memoized_verhash +.. toctree:: + :maxdepth: 2 + + api Additional Information diff --git a/examples/hello.py b/examples/hello.py index 8d99ce69..e1596e60 100644 --- a/examples/hello.py +++ b/examples/hello.py @@ -1,31 +1,31 @@ import random from datetime import datetime -from flask import Flask, jsonify -from flask_caching import Cache +from flask import Flask, jsonify, render_template_string +from flask_caching import Cache app = Flask(__name__) -app.config.from_pyfile('hello.cfg') +app.config.from_pyfile("hello.cfg") cache = Cache(app) #: This is an example of a cached view -@app.route('/api/now') +@app.route("/api/now") @cache.cached(50) def current_time(): return str(datetime.now()) #: This is an example of a cached function -@cache.cached(key_prefix='binary') +@cache.cached(key_prefix="binary") def random_binary(): return [random.randrange(0, 2) for i in range(500)] -@app.route('/api/get/binary') +@app.route("/api/get/binary") def get_binary(): - return jsonify({'data': random_binary()}) + return jsonify({"data": random_binary()}) #: This is an example of a memoized function @@ -39,21 +39,31 @@ def _sub(a, b): return a - b - random.randrange(0, 1000) -@app.route('/api/add//') +@app.route("/api/add//") def add(a, b): return str(_add(a, b)) -@app.route('/api/sub//') +@app.route("/api/sub//") def sub(a, b): return str(_sub(a, b)) -@app.route('/api/cache/delete') +@app.route("/api/cache/delete") def delete_cache(): - cache.delete_memoized('_add', '_sub') - return 'OK' + cache.delete_memoized("_add", "_sub") + return "OK" + + +@app.route("/html") +@app.route("/html/") +def html(foo=None): + if foo is not None: + cache.set("foo", foo) + return render_template_string( + "foo cache: {{foo}}", foo=cache.get("foo") + ) -if __name__ == '__main__': +if __name__ == "__main__": app.run() diff --git a/flask_caching/backends/rediscache.py b/flask_caching/backends/rediscache.py index 87bbc05b..521826b0 100644 --- a/flask_caching/backends/rediscache.py +++ b/flask_caching/backends/rediscache.py @@ -167,6 +167,28 @@ def dec(self, key, delta=1): class RedisSentinelCache(RedisCache): + """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. + + + :param sentinels: A list or a tuple of Redis sentinel addresses. + :param master: The name of the master server in a sentinel configuration. + :param password: password authentication for the Redis server. + :param db: db (zero-based numeric index) on Redis Server to connect. + :param default_timeout: the default timeout that is used if no timeout is + specified on :meth:`~BaseCache.set`. A timeout of + 0 indicates that the cache never expires. + :param key_prefix: A prefix that should be added to all keys. + + Any additional keyword arguments will be passed to + ``redis.sentinel.Sentinel``. + """ + def __init__( self, sentinels=None,