File: loaders.html

package info (click to toggle)
jinja 1.2-3
links: PTS, VCS
area: main
in suites: squeeze
size: 1,412 kB
ctags: 1,171
sloc: python: 6,438; ansic: 397; makefile: 74
file content (593 lines) | stat: -rw-r--r-- 44,826 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <title>Template Loaders &mdash; Jinja Documentation</title>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">
  <link rel="stylesheet" href="style.css" type="text/css">
  <style type="text/css">
    .syntax  { background: #ffffff; }
.syntax .c { color: #888888 } /* Comment */
.syntax .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.syntax .k { color: #008800; font-weight: bold } /* Keyword */
.syntax .cm { color: #888888 } /* Comment.Multiline */
.syntax .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.syntax .c1 { color: #888888 } /* Comment.Single */
.syntax .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.syntax .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.syntax .ge { font-style: italic } /* Generic.Emph */
.syntax .gr { color: #aa0000 } /* Generic.Error */
.syntax .gh { color: #303030 } /* Generic.Heading */
.syntax .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.syntax .go { color: #888888 } /* Generic.Output */
.syntax .gp { color: #555555 } /* Generic.Prompt */
.syntax .gs { font-weight: bold } /* Generic.Strong */
.syntax .gu { color: #606060 } /* Generic.Subheading */
.syntax .gt { color: #aa0000 } /* Generic.Traceback */
.syntax .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.syntax .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.syntax .kp { color: #008800 } /* Keyword.Pseudo */
.syntax .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.syntax .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.syntax .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.syntax .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.syntax .na { color: #336699 } /* Name.Attribute */
.syntax .nb { color: #003388 } /* Name.Builtin */
.syntax .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.syntax .no { color: #003366; font-weight: bold } /* Name.Constant */
.syntax .nd { color: #555555 } /* Name.Decorator */
.syntax .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.syntax .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.syntax .nl { color: #336699; font-style: italic } /* Name.Label */
.syntax .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.syntax .py { color: #336699; font-weight: bold } /* Name.Property */
.syntax .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.syntax .nv { color: #336699 } /* Name.Variable */
.syntax .ow { color: #008800 } /* Operator.Word */
.syntax .w { color: #bbbbbb } /* Text.Whitespace */
.syntax .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.syntax .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.syntax .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.syntax .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.syntax .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.syntax .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.syntax .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.syntax .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.syntax .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.syntax .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.syntax .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.syntax .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.syntax .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.syntax .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.syntax .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.syntax .bp { color: #003388 } /* Name.Builtin.Pseudo */
.syntax .vc { color: #336699 } /* Name.Variable.Class */
.syntax .vg { color: #dd7700 } /* Name.Variable.Global */
.syntax .vi { color: #3333bb } /* Name.Variable.Instance */
.syntax .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
  </style>
</head>
<body>
  <div id="content">
    
      <h1 class="heading"><span>Jinja</span></h1>
      <h2 class="subheading">Template Loaders</h2>
    
    
    <div id="toc">
      <h2>Navigation</h2>
      <ul>
        <li><a href="index.html">back to index</a></li>
      </ul>
      
        <h2>Contents</h2>
        <ul class="contents">
        
          <li><a href="#builtin-loaders">Builtin Loaders</a></li>
        
          <li><a href="#loader-baseclasses">Loader Baseclasses</a></li>
        
          <li><a href="#developing-loaders">Developing Loaders</a></li>
        
          <li><a href="#how-mixin-classes-work">How Mixin Classes Work</a></li>
        
          <li><a href="#combining-everything">Combining Everything</a></li>
        
        </ul>
      
    </div>
    
    <div id="contentwrapper">
      <p>This part of the documentation explains how to use and write a template loader.</p>
<div class="section">
<h2><a id="builtin-loaders" name="builtin-loaders">Builtin Loaders</a></h2>
<p>This list contains the builtin loaders you can use without further
modification:</p>
<dl class="docutils">
<dt><cite>ChoiceLoader</cite></dt>
<dd><p class="first">A loader that tries multiple loaders in the order they are given to
the <cite>ChoiceLoader</cite>:</p>
<div class="last"><div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja</span> <span class="k">import</span> <span class="n">ChoiceLoader</span><span class="p">,</span> <span class="n">FileSystemLoader</span>
<span class="n">loader1</span> <span class="o">=</span> <span class="n">FileSystemLoader</span><span class="p">(</span><span class="s">&quot;templates1&quot;</span><span class="p">)</span>
<span class="n">loader2</span> <span class="o">=</span> <span class="n">FileSystemLoader</span><span class="p">(</span><span class="s">&quot;templates2&quot;</span><span class="p">)</span>
<span class="n">loader</span> <span class="o">=</span> <span class="n">ChoiceLoader</span><span class="p">([</span><span class="n">loader1</span><span class="p">,</span> <span class="n">loader2</span><span class="p">])</span>
</pre></div>
</div></dd>
<dt><cite>DictLoader</cite></dt>
<dd><p class="first">Load templates from a given dict:</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja</span> <span class="k">import</span> <span class="n">Environment</span><span class="p">,</span> <span class="n">DictLoader</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">Environment</span><span class="p">(</span><span class="n">loader</span><span class="o">=</span><span class="n">DictLoader</span><span class="p">(</span><span class="nb">dict</span><span class="p">(</span>
    <span class="n">layout</span><span class="o">=</span><span class="s">&#39;...&#39;</span><span class="p">,</span>
    <span class="n">index</span><span class="o">=</span><span class="s">&#39;{</span><span class="si">% e</span><span class="s">xtends &#39;</span><span class="n">layout</span><span class="s">&#39; %}...&#39;</span>
<span class="p">)))</span>
</pre></div>
<p class="last">This loader does not have any caching capabilities.</p>
</dd>
<dt><cite>FileSystemLoader</cite></dt>
<dd><p class="first">Loads templates from the filesystem:</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja</span> <span class="k">import</span> <span class="n">Environment</span><span class="p">,</span> <span class="n">FileSystemLoader</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">Environment</span><span class="p">(</span><span class="n">loader</span><span class="o">=</span><span class="n">FileSystemLoader</span><span class="p">(</span><span class="s">&#39;templates/&#39;</span><span class="p">))</span>
</pre></div>
<p>You can pass the following keyword arguments to the loader on
initialization:</p>
<table border="1" class="last docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">searchpath</span></tt></td>
<td>String with the path to the templates on the
filesystem.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">use_memcache</span></tt></td>
<td>Set this to <tt class="docutils literal"><span class="pre">True</span></tt> to enable memory caching.
This is usually a good idea in production mode,
but disable it during development since it won't
reload template changes automatically.
This only works in persistent environments like
FastCGI.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">memcache_size</span></tt></td>
<td>Number of template instance you want to cache.
Defaults to <tt class="docutils literal"><span class="pre">40</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cache_folder</span></tt></td>
<td>Set this to an existing directory to enable
caching of templates on the file system. Note
that this only affects templates transformed
into python code. Default is <tt class="docutils literal"><span class="pre">None</span></tt> which means
that caching is disabled.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">auto_reload</span></tt></td>
<td>Set this to <cite>False</cite> for a slightly better
performance. In that case Jinja won't check for
template changes on the filesystem.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cache_salt</span></tt></td>
<td>Optional unique number to not confuse the
caching system when caching more than one
template loader in the same folder. Defaults
to the searchpath. <em>New in Jinja 1.1</em></td>
</tr>
</tbody>
</table>
</dd>
<dt><cite>FunctionLoader</cite></dt>
<dd><p class="first">Loads templates by calling a function which has to return a string
or <cite>None</cite> if an error occoured.</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja</span> <span class="k">import</span> <span class="n">Environment</span><span class="p">,</span> <span class="n">FunctionLoader</span>

<span class="k">def</span> <span class="nf">my_load_func</span><span class="p">(</span><span class="n">template_name</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">template_name</span> <span class="o">==</span> <span class="s">&#39;foo&#39;</span><span class="p">:</span>
        <span class="k">return</span> <span class="s">&#39;...&#39;</span>

<span class="n">e</span> <span class="o">=</span> <span class="n">Environment</span><span class="p">(</span><span class="n">loader</span><span class="o">=</span><span class="n">FunctionLoader</span><span class="p">(</span><span class="n">my_load_func</span><span class="p">))</span>
</pre></div>
<p>Because the interface is limited there is no way to cache such
templates. Usually you should try to use a loader with a more
solid backend.</p>
<p>You can pass the following keyword arguments to the loader on
initialization:</p>
<table border="1" class="last docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">loader_func</span></tt></td>
<td>Function that takes the name of the template to
load. If it returns a string or unicode object
it's used to load a template. If the return
value is None it's considered missing.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">getmtime_func</span></tt></td>
<td>Function used to check if templates requires
reloading. Has to return the UNIX timestamp of
the last template change or <tt class="docutils literal"><span class="pre">-1</span></tt> if this template
does not exist or requires updates at any cost.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">use_memcache</span></tt></td>
<td>Set this to <tt class="docutils literal"><span class="pre">True</span></tt> to enable memory caching.
This is usually a good idea in production mode,
but disable it during development since it won't
reload template changes automatically.
This only works in persistent environments like
FastCGI.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">memcache_size</span></tt></td>
<td>Number of template instance you want to cache.
Defaults to <tt class="docutils literal"><span class="pre">40</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cache_folder</span></tt></td>
<td>Set this to an existing directory to enable
caching of templates on the file system. Note
that this only affects templates transformed
into python code. Default is <tt class="docutils literal"><span class="pre">None</span></tt> which means
that caching is disabled.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">auto_reload</span></tt></td>
<td>Set this to <cite>False</cite> for a slightly better
performance. In that case of <cite>getmtime_func</cite>
not being provided this won't have an effect.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cache_salt</span></tt></td>
<td>Optional unique number to not confuse the
caching system when caching more than one
template loader in the same folder.</td>
</tr>
</tbody>
</table>
</dd>
<dt><cite>MemcachedFileSystemLoader</cite></dt>
<dd><p class="first">Loads templates from the filesystem and caches them on a memcached
server.</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja</span> <span class="k">import</span> <span class="n">Environment</span><span class="p">,</span> <span class="n">MemcachedFileSystemLoader</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">Environment</span><span class="p">(</span><span class="n">loader</span><span class="o">=</span><span class="n">MemcachedFileSystemLoader</span><span class="p">(</span><span class="s">&#39;templates/&#39;</span><span class="p">,</span>
    <span class="n">memcache_host</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;192.168.2.250:11211&#39;</span><span class="p">]</span>
<span class="p">))</span>
</pre></div>
<p>You can pass the following keyword arguments to the loader on
initialization:</p>
<table border="1" class="last docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">searchpath</span></tt></td>
<td>String with the path to the templates on the
filesystem.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">use_memcache</span></tt></td>
<td>Set this to <tt class="docutils literal"><span class="pre">True</span></tt> to enable memcached caching.
In that case it behaves like a normal
<cite>FileSystemLoader</cite> with disabled caching.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">memcache_time</span></tt></td>
<td>The expire time of a template in the cache.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">memcache_host</span></tt></td>
<td>a list of memcached servers.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">item_prefix</span></tt></td>
<td>The prefix for the items on the server. Defaults
to <tt class="docutils literal"><span class="pre">'template/'</span></tt>.</td>
</tr>
</tbody>
</table>
</dd>
<dt><cite>PackageLoader</cite></dt>
<dd><p class="first">Loads templates from python packages using setuptools.</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja</span> <span class="k">import</span> <span class="n">Environment</span><span class="p">,</span> <span class="n">PackageLoader</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">Environment</span><span class="p">(</span><span class="n">loader</span><span class="o">=</span><span class="n">PackageLoader</span><span class="p">(</span><span class="s">&#39;yourapp&#39;</span><span class="p">,</span> <span class="s">&#39;template/path&#39;</span><span class="p">))</span>
</pre></div>
<p>You can pass the following keyword arguments to the loader on
initialization:</p>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">package_name</span></tt></td>
<td>Name of the package containing the templates.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">package_path</span></tt></td>
<td>Path of the templates inside the package.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">use_memcache</span></tt></td>
<td>Set this to <tt class="docutils literal"><span class="pre">True</span></tt> to enable memory caching.
This is usually a good idea in production mode,
but disable it during development since it won't
reload template changes automatically.
This only works in persistent environments like
FastCGI.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">memcache_size</span></tt></td>
<td>Number of template instance you want to cache.
Defaults to <tt class="docutils literal"><span class="pre">40</span></tt>.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cache_folder</span></tt></td>
<td>Set this to an existing directory to enable
caching of templates on the file system. Note
that this only affects templates transformed
into python code. Default is <tt class="docutils literal"><span class="pre">None</span></tt> which means
that caching is disabled.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">auto_reload</span></tt></td>
<td>Set this to <cite>False</cite> for a slightly better
performance. In that case Jinja won't check for
template changes on the filesystem. If the
templates are inside of an egg file this won't
have an effect.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cache_salt</span></tt></td>
<td>Optional unique number to not confuse the
caching system when caching more than one
template loader in the same folder. Defaults
to <tt class="docutils literal"><span class="pre">package_name</span> <span class="pre">+</span> <span class="pre">'/'</span> <span class="pre">+</span> <span class="pre">package_path</span></tt>.
<em>New in Jinja 1.1</em></td>
</tr>
</tbody>
</table>
<p class="last">Important note: If you're using an application that is inside of an
egg never set <cite>auto_reload</cite> to <cite>True</cite>. The egg resource manager will
automatically export files to the file system and touch them so that
you not only end up with additional temporary files but also an automatic
reload each time you load a template.</p>
</dd>
</dl>
</div>
<div class="section">
<h2><a id="loader-baseclasses" name="loader-baseclasses">Loader Baseclasses</a></h2>
<p>With Jinja 1.1 onwards all the loaders have (except of the uncached)
baseclasses. You can use them to mix your own caching layer in. This technique
is described below. The <cite>BaseLoader</cite> itself is also a loader baseclass but
because it's the baseclass of all loaders it's covered in the &quot;Developing
Loaders&quot; section.</p>
<dl class="docutils">
<dt><cite>BaseFileSystemLoader</cite></dt>
<dd><p class="first">Baseclass for the file system loader that does not do any caching.
It exists to avoid redundant code, just don't use it without subclassing.</p>
<p>How subclassing can work:</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">BaseFileSystemLoader</span>

<span class="k">class</span> <span class="nc">MyFileSystemLoader</span><span class="p">(</span><span class="n">BaseFileSystemLoader</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">BaseFileSystemLoader</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="s">&#39;/path/to/templates&#39;</span><span class="p">)</span>
</pre></div>
<p class="last">The base file system loader only takes one parameter beside self which
is the path to the templates.</p>
</dd>
<dt><cite>BaseFunctionLoader</cite></dt>
<dd><p class="first">Baseclass for the function loader that doesn't do any caching.</p>
<p>It just accepts one parameter which is the function which is called
with the name of the requested template. If the return value is <cite>None</cite>
the loader will raise a <cite>TemplateNotFound</cite> error.</p>
<div class="last"><div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">BaseFunctionLoader</span>

<span class="n">templates</span> <span class="o">=</span> <span class="p">{</span><span class="o">...</span><span class="p">}</span>

<span class="k">class</span> <span class="nc">MyFunctionLoader</span><span class="p">(</span><span class="n">BaseFunctionLoader</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">BaseFunctionLoader</span><span class="p">(</span><span class="n">templates</span><span class="o">.</span><span class="n">get</span><span class="p">)</span>
</pre></div>
</div></dd>
<dt><cite>BasePackageLoader</cite></dt>
<dd><p class="first">Baseclass for the package loader that does not do any caching.</p>
<p>It accepts two parameters: The name of the package and the path relative
to the package:</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">BasePackageLoader</span>

<span class="k">class</span> <span class="nc">MyPackageLoader</span><span class="p">(</span><span class="n">BasePackageLoader</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">BasePackageLoader</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="s">&#39;my_package&#39;</span><span class="p">,</span> <span class="s">&#39;shared/templates&#39;</span><span class="p">)</span>
</pre></div>
<p>The relative path must use slashes as path delimiters, even on Mac OS
and Microsoft Windows.</p>
<p class="last">It uses the <cite>pkg_resources</cite> libraries distributed with setuptools for
retrieving the data from the packages. This works for eggs too so you
don't have to mark your egg as non zip safe. If pkg_resources is not
available it just falls back to path joining relative to the package.</p>
</dd>
</dl>
</div>
<div class="section">
<h2><a id="developing-loaders" name="developing-loaders">Developing Loaders</a></h2>
<p>Template loaders are just normal Python classes that have to provide some
functions used to load and translate templates. Because some of the tasks
a loader has to do are redundant there are some classes that make loader
development easier.</p>
<p>Here the implementation of a simple loader based on the <cite>BaseLoader</cite> from
<cite>jinja.loaders</cite>:</p>
<div class="syntax"><pre><span class="k">import</span> <span class="nn">codecs</span>
<span class="k">from</span> <span class="nn">os.path</span> <span class="k">import</span> <span class="n">join</span>
<span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">BaseLoader</span>
<span class="k">from</span> <span class="nn">jinja.exceptions</span> <span class="k">import</span> <span class="n">TemplateNotFound</span>

<span class="k">class</span> <span class="nc">SimpleLoader</span><span class="p">(</span><span class="n">BaseLoader</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">path</span> <span class="o">=</span> <span class="n">path</span>

    <span class="k">def</span> <span class="nf">get_source</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>
            <span class="k">raise</span> <span class="n">TemplateNotFound</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
        <span class="n">f</span> <span class="o">=</span> <span class="n">codecs</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;r&#39;</span><span class="p">,</span> <span class="n">environment</span><span class="o">.</span><span class="n">template_charset</span><span class="p">)</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
        <span class="k">finally</span><span class="p">:</span>
            <span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
<p>The functions <cite>load</cite> and <cite>parse</cite> which are a requirement for a loader are
added automatically by the <cite>BaseLoader</cite>. Instead of the normal <cite>BaseLoader</cite>
you can use one of the other base loaders that already come with a proper
<cite>get_source</cite> method for further modification. Those loaders however are
new in Jinja 1.1.</p>
<div class="section">
<h3><a id="cachedloadermixin" name="cachedloadermixin">CachedLoaderMixin</a></h3>
<p>Additionally to the <cite>BaseLoader</cite> there is a mixin class called
<cite>CachedLoaderMixin</cite> that implements memory and disk caching of templates.
Note that you have to give it a higher priority in the MRO than the
<cite>BaseLoader</cite> which means that's the first base class when inheriting from it:</p>
<div class="syntax"><pre><span class="k">import</span> <span class="nn">codecs</span>
<span class="k">from</span> <span class="nn">os.path</span> <span class="k">import</span> <span class="n">join</span><span class="p">,</span> <span class="n">getmtime</span><span class="p">,</span> <span class="n">exists</span>
<span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">BaseLoaderCachedLoaderMixin</span>
<span class="k">from</span> <span class="nn">jinja.exceptions</span> <span class="k">import</span> <span class="n">TemplateNotFound</span>

<span class="k">class</span> <span class="nc">CachedLoader</span><span class="p">(</span><span class="n">CachedLoaderMixin</span><span class="p">,</span> <span class="n">BaseLoader</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">path</span> <span class="o">=</span> <span class="n">path</span>
        <span class="n">CachedLoaderMixin</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
            <span class="bp">True</span><span class="p">,</span>       <span class="c"># use memory caching</span>
            <span class="mf">40</span><span class="p">,</span>         <span class="c"># for up to 40 templates</span>
            <span class="s">&#39;/tmp&#39;</span><span class="p">,</span>     <span class="c"># additionally save the compiled templates in /tmp</span>
            <span class="bp">True</span><span class="p">,</span>       <span class="c"># and reload cached templates automatically if changed</span>
            <span class="s">&#39;foo&#39;</span>       <span class="c"># optional salt used to keep templates with the same</span>
                        <span class="c"># name in the same cache folder, but from different</span>
                        <span class="c"># loaders. New in Jinja 1.1 and can be omitted.</span>
        <span class="p">)</span>

    <span class="k">def</span> <span class="nf">get_source</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>
            <span class="k">raise</span> <span class="n">TemplateNotFound</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
        <span class="n">f</span> <span class="o">=</span> <span class="n">codecs</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;r&#39;</span><span class="p">,</span> <span class="n">environment</span><span class="o">.</span><span class="n">template_charset</span><span class="p">)</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
        <span class="k">finally</span><span class="p">:</span>
            <span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

    <span class="k">def</span> <span class="nf">check_source_changed</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
        <span class="n">fn</span> <span class="o">=</span> <span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">exists</span><span class="p">(</span><span class="n">fn</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">getmtime</span><span class="p">(</span><span class="n">fn</span><span class="p">)</span>
        <span class="k">return</span> <span class="o">-</span><span class="mf">1</span>
</pre></div>
<p>You don't have to provide the <cite>check_source_changed</cite> method. If it doesn't
exist the option <cite>auto_reload</cite> won't have an effect. Also note that the
<cite>check_source_changed</cite> method must not raise an exception if the template
does not exist but return <tt class="docutils literal"><span class="pre">-1</span></tt>. The return value <tt class="docutils literal"><span class="pre">-1</span></tt> is considered
&quot;always reload&quot; whereas <tt class="docutils literal"><span class="pre">0</span></tt> means &quot;do not reload&quot;. The default return
value for not existing templates should be <tt class="docutils literal"><span class="pre">-1</span></tt>.</p>
<p>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 <cite>CachedLoaderMixin</cite>.</p>
</div>
<div class="section">
<h3><a id="memcachedloadermixin" name="memcachedloadermixin">MemcachedLoaderMixin</a></h3>
<p><em>New in Jinja 1.1</em></p>
<p>The <cite>MemcachedLoaderMixin</cite> class adds support for <a class="reference" href="http://www.danga.com/memcached/">memcached</a> caching.
There is only one builtin loader that mixes it in: The
<cite>MemcachedFileSystemLoader</cite>. If you need other loaders with this mixin
you can easily subclass one of the existing base loaders. Here an example
for the <cite>FunctionLoader</cite>:</p>
<div class="syntax"><pre><span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">FunctionLoader</span><span class="p">,</span> <span class="n">MemcachedLoaderMixin</span>

<span class="k">class</span> <span class="nc">MemcachedFunctionLoader</span><span class="p">(</span><span class="n">MemcachedLoaderMixin</span><span class="p">,</span> <span class="n">FunctionLoader</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">loader_func</span><span class="p">):</span>
        <span class="n">BaseFunctionLoader</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">loader_func</span><span class="p">)</span>
        <span class="n">MemcachedLoaderMixin</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
            <span class="bp">True</span><span class="p">,</span>                   <span class="c"># use memcached</span>
            <span class="mf">60</span> <span class="o">*</span> <span class="mf">60</span> <span class="o">*</span> <span class="mf">24</span> <span class="o">*</span> <span class="mf">7</span><span class="p">,</span>       <span class="c"># 7 days expiration</span>
            <span class="p">[</span><span class="s">&#39;127.0.0.1:11211&#39;</span><span class="p">],</span>    <span class="c"># the memcached hosts</span>
            <span class="s">&#39;template/&#39;</span>             <span class="c"># string prefix for the cache keys</span>
        <span class="p">)</span>
</pre></div>
<p>This mixin requires the <a class="reference" href="http://www.tummy.com/Community/software/python-memcached/">python-memcached</a> library.</p>
</div>
</div>
<div class="section">
<h2><a id="how-mixin-classes-work" name="how-mixin-classes-work">How Mixin Classes Work</a></h2>
<p>The idea of the cached loader mixins is that you override the <cite>load</cite>
method of the other base class so that it's only called to get the data
from the loader and put it into a cache and then bypass the original <cite>load</cite>.</p>
<p>This works because mixin classes, as well as the loaders are so called &quot;new
style classes&quot; with a MRO (method resolution order). So it's possible to
access the parent without actually knowing the name of it.</p>
<p>Here as small mixin class that stores everything after loading in a
dict:</p>
<div class="syntax"><pre><span class="k">class</span> <span class="nc">SimpleCacheMixin</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span> <span class="o">=</span> <span class="p">{}</span>

    <span class="k">def</span> <span class="nf">load</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">translator</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">name</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
        <span class="n">tmpl</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">SimpleCacheMixin</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span>
                                                  <span class="n">translator</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">tmpl</span>
        <span class="k">return</span> <span class="n">tmpl</span>
</pre></div>
<p>You can then mix the class in like any other mixin class. Note that
all non public attributes <strong>must</strong> be prefixed with two underscores to
enable the name mangling. Otherwise the mixin class could break the
internal structure of the loader.</p>
<p>The <tt class="docutils literal"><span class="pre">super(SimpleCacheMixin,</span> <span class="pre">self)</span></tt> call returns an object that looks
up all the attributes you request in all the parent classes. The
<cite>SimpleCacheMixin</cite> just has the <cite>object</cite> parent which makes it a new
style class, but as soon as a loader is mixed in it will call the
<cite>load</cite> method of the loader that is the other parent of the resulting
class. Here a full example.</p>
</div>
<div class="section">
<h2><a id="combining-everything" name="combining-everything">Combining Everything</a></h2>
<p>Here a full example with a custom cache mixin and a custom base loader:</p>
<div class="syntax"><pre><span class="k">import</span> <span class="nn">codecs</span>
<span class="k">from</span> <span class="nn">os.path</span> <span class="k">import</span> <span class="n">join</span>
<span class="k">from</span> <span class="nn">jinja.loaders</span> <span class="k">import</span> <span class="n">BaseLoader</span>
<span class="k">from</span> <span class="nn">jinja.exceptions</span> <span class="k">import</span> <span class="n">TemplateNotFound</span>

<span class="k">class</span> <span class="nc">SimpleBaseLoader</span><span class="p">(</span><span class="n">BaseLoader</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">path</span> <span class="o">=</span> <span class="n">path</span>

    <span class="k">def</span> <span class="nf">get_source</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>
            <span class="k">raise</span> <span class="n">TemplateNotFound</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
        <span class="n">f</span> <span class="o">=</span> <span class="n">codecs</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;r&#39;</span><span class="p">,</span> <span class="n">environment</span><span class="o">.</span><span class="n">template_charset</span><span class="p">)</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
        <span class="k">finally</span><span class="p">:</span>
            <span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>


<span class="k">class</span> <span class="nc">SimpleCacheMixin</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span> <span class="o">=</span> <span class="p">{}</span>

    <span class="k">def</span> <span class="nf">load</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">translator</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">name</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
        <span class="n">tmpl</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">SimpleCacheMixin</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">environment</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span>
                                                  <span class="n">translator</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__cache</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">tmpl</span>
        <span class="k">return</span> <span class="n">tmpl</span>


<span class="k">class</span> <span class="nc">SimpleLoader</span><span class="p">(</span><span class="n">SimpleBaseLoader</span><span class="p">,</span> <span class="n">SimpleCacheMixin</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
        <span class="n">SimpleBaseLoader</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">)</span>
        <span class="n">SimpleCacheMixin</span><span class="o">.</span><span class="n">__init__</span><span class="p">()</span>
</pre></div>
<p>You can of course put all the functionallity into the <cite>SimpleLoader</cite> but then
you cannot exchange parts of it without rewriting much code. In the example
above replacing the <cite>SimpleCacheMixin</cite> with a <cite>MemcachedLoaderMixin</cite> is a
matter of 20 seconds.</p>
</div>

    </div>
  </div>
</body>
<!-- generated on: 2007-11-17 18:18:06.505013
     file id: loaders -->
</html>