Class Cache

Decorator function that can be used to cache any function/method.

Example::

    @cache('key', 5000, cache.ram)
    def f():
        return time.ctime()

When the function f is called, web2py tries to retrieve
the value corresponding to `key` from the cache of the
object exists and if it did not expire, else it calles the function `f`
and stores the output in the cache corresponding to `key`. In the case
the output of the function is returned.

:param key: the key of the object to be store or retrieved
:param time_expire: expiration of the cache in microseconds
:param cache_model: "ram", "disk", or other
    (like "memcache" if defined). It defaults to "ram".

Notes
-----
`time_expire` is used to compare the curret time with the time when the
requested object was last saved in cache. It does not affect future
requests.
Setting `time_expire` to 0 or negative value forces the cache to
refresh.

If the function `f` is an action, we suggest using
@cache.client instead

Parameters
----------
request:
    the global request object

Overrides: object.__init__

Experimental!
Currently only HTTP 1.1 compliant
reference : http://code.google.com/p/doctype-mirror/wiki/ArticleHttpCaching
time_expire: same as @cache
cache_model: same as @cache
prefix: add a prefix to the calculated key
session: adds response.session_id to the key
vars: adds request.env.query_string
lang: adds T.accepted_language
user_agent: if True, adds is_mobile and is_tablet to the key.
    Pass a dict to use all the needed values (uses str(.items())) (e.g. user_agent=request.user_agent())
    used only if session is not True
public: if False forces the Cache-Control to be 'private'
valid_statuses: by default only status codes starting with 1,2,3 will be cached.
    pass an explicit list of statuses on which turn the cache on
quick: Session,Vars,Lang,User-agent,Public:
    fast overrides with initial strings, e.g. 'SVLP' or 'VLP', or 'VLP'