[svn] added baseclasses for loaders, added the memcaching loader, updated documentation for loaders
--HG--
branch : trunk
diff --git a/docs/generate.py b/docs/generate.py
index f8e8238..6b6b0ac 100755
--- a/docs/generate.py
+++ b/docs/generate.py
@@ -101,6 +101,30 @@
return '\n\n'.join(result)
+def generate_list_of_baseloaders():
+ from jinja import loaders as loader_module
+
+ result = []
+ loaders = []
+ for item in dir(loader_module):
+ obj = getattr(loader_module, item)
+ try:
+ if issubclass(obj, loader_module.BaseLoader) and \
+ obj.__name__ != 'BaseLoader' and \
+ obj.__name__ not in loader_module.__all__:
+ loaders.append(obj)
+ except TypeError:
+ pass
+ loaders.sort(key=lambda x: x.__name__.lower())
+
+ for loader in loaders:
+ doclines = []
+ for line in inspect.getdoc(loader).splitlines():
+ doclines.append(' ' + line)
+ result.append('`%s`\n%s' % (loader.__name__, '\n'.join(doclines)))
+
+ return '\n\n'.join(result)
+
def generate_environment_doc():
from jinja.environment import Environment
return '%s\n\n%s' % (
@@ -115,6 +139,7 @@
LIST_OF_FILTERS = generate_list_of_filters()
LIST_OF_TESTS = generate_list_of_tests()
LIST_OF_LOADERS = generate_list_of_loaders()
+LIST_OF_BASELOADERS = generate_list_of_baseloaders()
ENVIRONMENT_DOC = generate_environment_doc()
CHANGELOG = file(os.path.join(os.path.dirname(__file__), os.pardir, 'CHANGES'))\
.read().decode('utf-8')
@@ -240,6 +265,7 @@
data = data.replace('[[list_of_filters]]', LIST_OF_FILTERS)\
.replace('[[list_of_tests]]', LIST_OF_TESTS)\
.replace('[[list_of_loaders]]', LIST_OF_LOADERS)\
+ .replace('[[list_of_baseloaders]]', LIST_OF_BASELOADERS)\
.replace('[[environment_doc]]', ENVIRONMENT_DOC)\
.replace('[[changelog]]', CHANGELOG)
parts = publish_parts(
diff --git a/docs/src/loaders.txt b/docs/src/loaders.txt
index 29da849..306b14d 100644
--- a/docs/src/loaders.txt
+++ b/docs/src/loaders.txt
@@ -7,8 +7,21 @@
Builtin Loaders
===============
+This list contains the builtin loaders you can use without further
+modification:
+
[[list_of_loaders]]
+Loader Baseclasses
+==================
+
+With Jinja 1.1 onwards all the loaders have (except of the uncached) now have
+baseclasses you can use to mix your own caching layer in. This technique is
+explained below. The `BaseLoader` itself is also a loader baseclass but because
+it's the baseclass of each loader it's explained in detail below.
+
+[[list_of_baseloaders]]
+
Developing Loaders
==================
@@ -43,7 +56,13 @@
f.close()
The functions `load` and `parse` which are a requirement for a loader are
-added automatically by the `BaseLoader`.
+added automatically by the `BaseLoader`. Instead of the normal `BaseLoader`
+you can use one of the other base loaders that already come with a proper
+`get_source` method for further modification. Those loaders however are
+new in Jinja 1.1.
+
+CachedLoaderMixin
+-----------------
Additionally to the `BaseLoader` there is a mixin class called
`CachedLoaderMixin` that implements memory and disk caching of templates.
@@ -91,4 +110,37 @@
exist the option `auto_reload` won't have an effect. Also note that the
`check_source_changed` method must not raise an exception if the template
does not exist but return ``-1``. The return value ``-1`` is considered
-"always reload" whereas ``0`` means "do not reload".
+"always reload" whereas ``0`` means "do not reload". The default return
+value for not existing templates should be ``-1``.
+
+For the default base classes that come with Jinja 1.1 onwards there exist
+also concrete implementations that support caching. The implementation
+just mixes in the `CachedLoaderMixin`.
+
+MemcachedLoaderMixin
+--------------------
+
+*New in Jinja 1.1*
+
+The `MemcachedLoaderMixin` class adds support for `memcached`_ caching.
+There is only one builtin loader that mixes it in: The
+`MemcachedFileSystemLoader`. If you need other loaders with this mixin
+you can easily subclass one of the existing base loaders. Here an example
+for the `FunctionLoader`:
+
+.. sourcecode:: python
+
+ from jinja.loaders import FunctionLoader, MemcachedLoaderMixin
+
+ class MemcachedFunctionLoader(MemcachedLoaderMixin, FunctionLoader):
+
+ def __init__(self, loader_func):
+ BaseFunctionLoader.__init__(self, loader_func)
+ MemcachedLoaderMixin.__init__(self,
+ True, # use memcached
+ 60 * 60 * 24 * 7, # 7 days expiration
+ ['127.0.0.1:11211'], # the memcached hosts
+ 'template/' # string prefix for the cache keys
+ )
+
+.. _memcached: http://www.danga.com/memcached/