Clever Harold Caching Support
-----------------------------

Clever Harold includes WSGI_ middleware and a function decorator to
cache rendered web pages and expensive computations.  The three
back-end storage types included are:

- memory (Python dictionary)
- memcached 
- dbm file


Middleware
==========

The ``paster init-harold`` command creates an entry for caching
middleware in your project but leaves the configuration up to you.  To
complete the configuration, you must supply a sequence of dictionaries
in the ``mapping`` entry.  Here is a simple example::

    [filter:my_cache_filter]
    use = egg:CleverHarold#cache
    mapping = python:[dict(pattern='/.*', ttl=60),
                      dict(pattern='/private/*.', keys='HTTP_USER', ttl=5)]

Each dictionary must specify a pattern, and may specify an optional
ttl, and an optional environment key or sequence of keys.

The pattern is a regular expression that, when matched to a request
path, indicates the result of the request is cacheable.

The ttl value is the number of seconds to cache the result of the
request.  If not supplied, the framework will use the default value of
60 seconds.  If the ttl is 0 (zero) or negative, the result will be cached
indefinitely.

The optional keys parameter indicates one or more WSGI_ environment
variable values to use in conjunction with the matching URL to form
the cache entry key.  By specifying values from the WSGI_ request
environment, you can cache entries unique to each site visitor, for
example.

The caching middleware can be configured for different storage types
in your project configuration file.  To specify the storage, include a
``store`` parameter and the additional values required by the storage
type.  Here are example sections for both memcached and dbm::

    [filter:my_memcached_filter]
    use = egg:CleverHarold#cache
    mapping = ...
    store = harold.cache.storage:MemCachedStorage
    servers = 127.0.0.1:11211 cacheserver:11211 othercacheserver:11211

    [filter:my_dbm_cache_filter]
    use = egg:CleverHarold#cache
    mapping = ...
    store = harold.cache.storage:DbmStorage
    filename = /tmp/mysite.db


The caching middleware is transparent to the applications when it's
configured in your project configuration file.

To use the caching middleware directly in a WSGI_ stack, refer to the
`Caching API documentation`_.


Decorator
=========

To use the caching decorator in your programs, import it and add it
to your callable's decorator stack, like so::

    from harold.cache import cacheable

    @cacheable()
    def long_operation():
        ...

Note the decorator is created by calling it -- those parenthesis are
not optional.

The decorator takes optional ``store`` and ``ttl`` parameters.  For now,
you'll have to specify these manually, but they will probably be
supplied from your project configuration in an upcoming release.

There aren't any administrative knobs exposed by the caching
middleware or decorator, at least not yet.  If you have need for such
things, please post a message to the mailing list and let us know your
requirements.


Further Reading
---------------

- WSGI_ Specification
- `Caching API Documentation`_


.. _WSGI: http://www.python.org/dev/peps/pep-0333/
.. _Caching API Documentation: http://trac.cleverharold.org/wiki/CacheApiDocs
