EVOLUTION-MANAGER

Edit File: caching.txt

.. _caching_toplevel: ======= Caching ======= Any template or component can be cached using the ``cache`` argument to the ``<%page>``, ``<%def>`` or ``<%block>`` directives: .. sourcecode:: mako <%page cached="True"/> template text The above template, after being executed the first time, will store its content within a cache that by default is scoped within memory. Subsequent calls to the template's :meth:`~.Template.render` method will return content directly from the cache. When the :class:`.Template` object itself falls out of scope, its corresponding cache is garbage collected along with the template. By default, caching requires that the `Beaker <http://beaker.readthedocs.org/>`_ package be installed on the system, however the mechanism of caching can be customized to use any third party or user defined system -- see :ref:`cache_plugins`. In addition to being available on the ``<%page>`` tag, the caching flag and all its options can be used with the ``<%def>`` tag as well: .. sourcecode:: mako <%def name="mycomp" cached="True" cache_timeout="60"> other text </%def> ... and equivalently with the ``<%block>`` tag, anonymous or named: .. sourcecode:: mako <%block cached="True" cache_timeout="60"> other text </%block> Cache Arguments =============== Mako has two cache arguments available on tags that are available in all cases. The rest of the arguments available are specific to a backend. The two generic tags arguments are: * ``cached="True"`` - enable caching for this ``<%page>``, ``<%def>``, or ``<%block>``. * ``cache_key`` - the "key" used to uniquely identify this content in the cache. Usually, this key is chosen automatically based on the name of the rendering callable (i.e. ``body`` when used in ``<%page>``, the name of the def when using ``<%def>``, the explicit or internally-generated name when using ``<%block>``). Using the ``cache_key`` parameter, the key can be overridden using a fixed or programmatically generated value. For example, here's a page that caches any page which inherits from it, based on the filename of the calling template: .. sourcecode:: mako <%page cached="True" cache_key="${self.filename}"/> ${next.body()} ## rest of template On a :class:`.Template` or :class:`.TemplateLookup`, the caching can be configured using these arguments: * ``cache_enabled`` - Setting this to ``False`` will disable all caching functionality when the template renders. Defaults to ``True``. e.g.: .. sourcecode:: python lookup = TemplateLookup( directories='/path/to/templates', cache_enabled = False ) * ``cache_impl`` - The string name of the cache backend to use. This defaults to ``'beaker'``, which has historically been the only cache backend supported by Mako. .. versionadded:: 0.6.0 For example, here's how to use the upcoming `dogpile.cache <http://dogpilecache.readthedocs.org>`_ backend: .. sourcecode:: python lookup = TemplateLookup( directories='/path/to/templates', cache_impl = 'dogpile.cache', cache_args = {'regions':my_dogpile_regions} ) * ``cache_args`` - A dictionary of cache parameters that will be consumed by the cache backend. See :ref:`beaker_backend` for examples. .. versionadded:: 0.6.0 Backend-Specific Cache Arguments -------------------------------- The ``<%page>``, ``<%def>``, and ``<%block>`` tags accept any named argument that starts with the prefix ``"cache_"``. Those arguments are then packaged up and passed along to the underlying caching implementation, minus the ``"cache_"`` prefix. The actual arguments understood are determined by the backend. * :ref:`beaker_backend` - Includes arguments understood by Beaker. * :ref:`dogpile.cache_backend` - Includes arguments understood by dogpile.cache. .. _beaker_backend: Using the Beaker Cache Backend ------------------------------ When using Beaker, new implementations will want to make usage of **cache regions** so that cache configurations can be maintained externally to templates. These configurations live under named "regions" that can be referred to within templates themselves. .. versionadded:: 0.6.0 Support for Beaker cache regions. For example, suppose we would like two regions. One is a "short term" region that will store content in a memory-based dictionary, expiring after 60 seconds. The other is a Memcached region, where values should expire in five minutes. To configure our :class:`.TemplateLookup`, first we get a handle to a :class:`beaker.cache.CacheManager`: .. sourcecode:: python from beaker.cache import CacheManager manager = CacheManager(cache_regions={ 'short_term':{ 'type': 'memory', 'expire': 60 }, 'long_term':{ 'type': 'ext:memcached', 'url': '127.0.0.1:11211', 'expire': 300 } }) lookup = TemplateLookup( directories=['/path/to/templates'], module_directory='/path/to/modules', cache_impl='beaker', cache_args={ 'manager':manager } ) Our templates can then opt to cache data in one of either region, using the ``cache_region`` argument. Such as using ``short_term`` at the ``<%page>`` level: .. sourcecode:: mako <%page cached="True" cache_region="short_term"> ## ... Or, ``long_term`` at the ``<%block>`` level: .. sourcecode:: mako <%block name="header" cached="True" cache_region="long_term"> other text </%block> The Beaker backend also works without regions. There are a variety of arguments that can be passed to the ``cache_args`` dictionary, which are also allowable in templates via the ``<%page>``, ``<%block>``, and ``<%def>`` tags specific to those sections. The values given override those specified at the :class:`.TemplateLookup` or :class:`.Template` level. With the possible exception of ``cache_timeout``, these arguments are probably better off staying at the template configuration level. Each argument specified as ``cache_XYZ`` in a template tag is specified without the ``cache_`` prefix in the ``cache_args`` dictionary: * ``cache_timeout`` - number of seconds in which to invalidate the cached data. After this timeout, the content is re-generated on the next call. Available as ``timeout`` in the ``cache_args`` dictionary. * ``cache_type`` - type of caching. ``'memory'``, ``'file'``, ``'dbm'``, or ``'ext:memcached'`` (note that the string ``memcached`` is also accepted by the dogpile.cache Mako plugin, though not by Beaker itself). Available as ``type`` in the ``cache_args`` dictionary. * ``cache_url`` - (only used for ``memcached`` but required) a single IP address or a semi-colon separated list of IP address of memcache servers to use. Available as ``url`` in the ``cache_args`` dictionary. * ``cache_dir`` - in the case of the ``'file'`` and ``'dbm'`` cache types, this is the filesystem directory with which to store data files. If this option is not present, the value of ``module_directory`` is used (i.e. the directory where compiled template modules are stored). If neither option is available an exception is thrown. Available as ``dir`` in the ``cache_args`` dictionary. .. _dogpile.cache_backend: Using the dogpile.cache Backend ------------------------------- `dogpile.cache`_ is a new replacement for Beaker. It provides a modernized, slimmed down interface and is generally easier to use than Beaker. As of this writing it has not yet been released. dogpile.cache includes its own Mako cache plugin -- see :mod:`dogpile.cache.plugins.mako_cache` in the dogpile.cache documentation. Programmatic Cache Access ========================= The :class:`.Template`, as well as any template-derived :class:`.Namespace`, has an accessor called ``cache`` which returns the :class:`.Cache` object for that template. This object is a facade on top of the underlying :class:`.CacheImpl` object, and provides some very rudimental capabilities, such as the ability to get and put arbitrary values: .. sourcecode:: mako <% local.cache.set("somekey", type="memory", "somevalue") %> Above, the cache associated with the ``local`` namespace is accessed and a key is placed within a memory cache. More commonly, the ``cache`` object is used to invalidate cached sections programmatically: .. sourcecode:: python template = lookup.get_template('/sometemplate.html') # invalidate the "body" of the template template.cache.invalidate_body() # invalidate an individual def template.cache.invalidate_def('somedef') # invalidate an arbitrary key template.cache.invalidate('somekey') You can access any special method or attribute of the :class:`.CacheImpl` itself using the :attr:`impl <.Cache.impl>` attribute: .. sourcecode:: python template.cache.impl.do_something_special() Note that using implementation-specific methods will mean you can't swap in a different kind of :class:`.CacheImpl` implementation at a later time. .. _cache_plugins: Cache Plugins ============= The mechanism used by caching can be plugged in using a :class:`.CacheImpl` subclass. This class implements the rudimental methods Mako needs to implement the caching API. Mako includes the :class:`.BeakerCacheImpl` class to provide the default implementation. A :class:`.CacheImpl` class is acquired by Mako using a ``pkg_resources`` entrypoint, using the name given as the ``cache_impl`` argument to :class:`.Template` or :class:`.TemplateLookup`. This entry point can be installed via the standard `setuptools`/``setup()`` procedure, underneath the `EntryPoint` group named ``"mako.cache"``. It can also be installed at runtime via a convenience installer :func:`.register_plugin` which accomplishes essentially the same task. An example plugin that implements a local dictionary cache: .. sourcecode:: python from mako.cache import Cacheimpl, register_plugin class SimpleCacheImpl(CacheImpl): def __init__(self, cache): super(SimpleCacheImpl, self).__init__(cache) self._cache = {} def get_or_create(self, key, creation_function, **kw): if key in self._cache: return self._cache[key] else: self._cache[key] = value = creation_function() return value def set(self, key, value, **kwargs): self._cache[key] = value def get(self, key, **kwargs): return self._cache.get(key) def invalidate(self, key, **kwargs): self._cache.pop(key, None) # optional - register the class locally register_plugin("simple", __name__, "SimpleCacheImpl") Enabling the above plugin in a template would look like: .. sourcecode:: python t = Template("mytemplate", file="mytemplate.html", cache_impl='simple') Guidelines for Writing Cache Plugins ------------------------------------ * The :class:`.CacheImpl` is created on a per-:class:`.Template` basis. The class should ensure that only data for the parent :class:`.Template` is persisted or returned by the cache methods. The actual :class:`.Template` is available via the ``self.cache.template`` attribute. The ``self.cache.id`` attribute, which is essentially the unique modulename of the template, is a good value to use in order to represent a unique namespace of keys specific to the template. * Templates only use the :meth:`.CacheImpl.get_or_create()` method in an implicit fashion. The :meth:`.CacheImpl.set`, :meth:`.CacheImpl.get`, and :meth:`.CacheImpl.invalidate` methods are only used in response to direct programmatic access to the corresponding methods on the :class:`.Cache` object. * :class:`.CacheImpl` will be accessed in a multithreaded fashion if the :class:`.Template` itself is used multithreaded. Care should be taken to ensure caching implementations are threadsafe. * A library like `Dogpile <http://pypi.python.org/pypi/dogpile.core>`_, which is a minimal locking system derived from Beaker, can be used to help implement the :meth:`.CacheImpl.get_or_create` method in a threadsafe way that can maximize effectiveness across multiple threads as well as processes. :meth:`.CacheImpl.get_or_create` is the key method used by templates. * All arguments passed to ``**kw`` come directly from the parameters inside the ``<%def>``, ``<%block>``, or ``<%page>`` tags directly, minus the ``"cache_"`` prefix, as strings, with the exception of the argument ``cache_timeout``, which is passed to the plugin as the name ``timeout`` with the value converted to an integer. Arguments present in ``cache_args`` on :class:`.Template` or :class:`.TemplateLookup` are passed directly, but are superseded by those present in the most specific template tag. * The directory where :class:`.Template` places module files can be acquired using the accessor ``self.cache.template.module_directory``. This directory can be a good place to throw cache-related work files, underneath a prefix like ``_my_cache_work`` so that name conflicts with generated modules don't occur. API Reference ============= .. autoclass:: mako.cache.Cache :members: :show-inheritance: .. autoclass:: mako.cache.CacheImpl :members: :show-inheritance: .. autofunction:: mako.cache.register_plugin .. autoclass:: mako.ext.beaker_cache.BeakerCacheImpl :members: :show-inheritance: