<html xmlns="http://www.w3.org/1999/xhtml">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
<head>
<title>
Usage
—
Mako 0.9.0 Documentation
</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/docs.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.9.0',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Mako 0.9.0 Documentation" href="index.html" />
<link rel="next" title="Syntax" href="syntax.html" />
<link rel="prev" title="Table of Contents" href="index.html" />
<link rel="stylesheet" href="_static/site.css"></link>
</head>
<body>
<div id="wrap">
<div class="rightbar">
<div class="slogan">
Hyperfast and lightweight templating for the Python platform.
</div>
</div>
<a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
<hr/>
<div id="docs-container">
<div id="docs-header">
<h1>Mako 0.9.0 Documentation</h1>
<div id="docs-search">
Search:
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<div id="docs-version-header">
Release: <span class="version-num">0.9.0</span>
</div>
</div>
<div id="docs-top-navigation">
<div id="docs-top-page-control" class="docs-navigation-links">
<ul>
<li>Prev:
<a href="index.html" title="previous chapter">Table of Contents</a>
</li>
<li>Next:
<a href="syntax.html" title="next chapter">Syntax</a>
</li>
<li>
<a href="index.html">Table of Contents</a> |
<a href="genindex.html">Index</a>
| <a href="_sources/usage.txt">view source
</li>
</ul>
</div>
<div id="docs-navigation-banner">
<a href="index.html">Mako 0.9.0 Documentation</a>
»
Usage
<h2>
Usage
</h2>
</div>
</div>
<div id="docs-body-container">
<div id="docs-sidebar">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Usage</a><ul>
<li><a class="reference internal" href="#basic-usage">Basic Usage</a></li>
<li><a class="reference internal" href="#using-file-based-templates">Using File-Based Templates</a></li>
<li><a class="reference internal" href="#using-templatelookup">Using <tt class="docutils literal"><span class="pre">TemplateLookup</span></tt></a><ul>
<li><a class="reference internal" href="#setting-the-collection-size">Setting the Collection Size</a></li>
<li><a class="reference internal" href="#setting-filesystem-checks">Setting Filesystem Checks</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-unicode-and-encoding">Using Unicode and Encoding</a></li>
<li><a class="reference internal" href="#handling-exceptions">Handling Exceptions</a></li>
<li><a class="reference internal" href="#common-framework-integrations">Common Framework Integrations</a><ul>
<li><a class="reference internal" href="#wsgi">WSGI</a></li>
<li><a class="reference internal" href="#pygments">Pygments</a></li>
<li><a class="reference internal" href="#babel">Babel</a></li>
</ul>
</li>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
</ul>
</li>
</ul>
<h4>Previous Topic</h4>
<p>
<a href="index.html" title="previous chapter">Table of Contents</a>
</p>
<h4>Next Topic</h4>
<p>
<a href="syntax.html" title="next chapter">Syntax</a>
</p>
<h4>Quick Search</h4>
<p>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</p>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="usage">
<span id="usage-toplevel"></span><h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
<div class="section" id="basic-usage">
<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h2>
<p>This section describes the Python API for Mako templates. If you
are using Mako within a web framework such as Pylons, the work
of integrating Mako’s API is already done for you, in which case
you can skip to the next section, <a class="reference internal" href="syntax.html"><em>Syntax</em></a>.</p>
<p>The most basic way to create a template and render it is through
the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">"hello world!"</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>Above, the text argument to <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> is <strong>compiled</strong> into a
Python module representation. This module contains a function
called <tt class="docutils literal"><span class="pre">render_body()</span></tt>, which produces the output of the
template. When <tt class="docutils literal"><span class="pre">mytemplate.render()</span></tt> is called, Mako sets up a
runtime environment for the template and calls the
<tt class="docutils literal"><span class="pre">render_body()</span></tt> function, capturing the output into a buffer and
returning its string contents.</p>
<p>The code inside the <tt class="docutils literal"><span class="pre">render_body()</span></tt> function has access to a
namespace of variables. You can specify these variables by
sending them as additional keyword arguments to the <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a>
method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">"hello, ${name}!"</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"jack"</span><span class="p">)</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> method calls upon Mako to create a
<a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> object, which stores all the variable names accessible
to the template and also stores a buffer used to capture output.
You can create this <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> yourself and have the template
render with it, using the <a class="reference internal" href="#mako.template.Template.render_context" title="mako.template.Template.render_context"><tt class="xref py py-meth docutils literal"><span class="pre">render_context()</span></tt></a> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="kn">from</span> <span class="nn">mako.runtime</span> <span class="kn">import</span> <span class="n">Context</span>
<span class="kn">from</span> <span class="nn">StringIO</span> <span class="kn">import</span> <span class="n">StringIO</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">"hello, ${name}!"</span><span class="p">)</span>
<span class="n">buf</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">()</span>
<span class="n">ctx</span> <span class="o">=</span> <span class="n">Context</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">"jack"</span><span class="p">)</span>
<span class="n">mytemplate</span><span class="o">.</span><span class="n">render_context</span><span class="p">(</span><span class="n">ctx</span><span class="p">)</span>
<span class="k">print</span> <span class="n">buf</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="using-file-based-templates">
<h2>Using File-Based Templates<a class="headerlink" href="#using-file-based-templates" title="Permalink to this headline">¶</a></h2>
<p>A <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> can also load its template source code from a file,
using the <tt class="docutils literal"><span class="pre">filename</span></tt> keyword argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">filename</span><span class="o">=</span><span class="s">'/docs/mytmpl.txt'</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>For improved performance, a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> which is loaded from a
file can also cache the source code to its generated module on
the filesystem as a regular Python module file (i.e. a <tt class="docutils literal"><span class="pre">.py</span></tt>
file). To do this, just add the <tt class="docutils literal"><span class="pre">module_directory</span></tt> argument to
the template:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">filename</span><span class="o">=</span><span class="s">'/docs/mytmpl.txt'</span><span class="p">,</span> <span class="n">module_directory</span><span class="o">=</span><span class="s">'/tmp/mako_modules'</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>When the above code is rendered, a file
<tt class="docutils literal"><span class="pre">/tmp/mako_modules/docs/mytmpl.txt.py</span></tt> is created containing the
source code for the module. The next time a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> with the
same arguments is created, this module file will be
automatically re-used.</p>
</div>
<div class="section" id="using-templatelookup">
<span id="usage-templatelookup"></span><h2>Using <tt class="docutils literal"><span class="pre">TemplateLookup</span></tt><a class="headerlink" href="#using-templatelookup" title="Permalink to this headline">¶</a></h2>
<p>All of the examples thus far have dealt with the usage of a
single <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object. If the code within those templates
tries to locate another template resource, it will need some way
to find them, using simple URI strings. For this need, the
resolution of other templates from within a template is
accomplished by the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> class. This class is
constructed given a list of directories in which to search for
templates, as well as keyword arguments that will be passed to
the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> objects it creates:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>
<span class="n">mylookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">'/docs'</span><span class="p">])</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">"""<</span><span class="si">%i</span><span class="s">nclude file="header.txt"/> hello world!"""</span><span class="p">,</span> <span class="n">lookup</span><span class="o">=</span><span class="n">mylookup</span><span class="p">)</span>
</pre></div>
</div>
<p>Above, we created a textual template which includes the file
<tt class="docutils literal"><span class="pre">"header.txt"</span></tt>. In order for it to have somewhere to look for
<tt class="docutils literal"><span class="pre">"header.txt"</span></tt>, we passed a <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> object to it, which
will search in the directory <tt class="docutils literal"><span class="pre">/docs</span></tt> for the file <tt class="docutils literal"><span class="pre">"header.txt"</span></tt>.</p>
<p>Usually, an application will store most or all of its templates
as text files on the filesystem. So far, all of our examples
have been a little bit contrived in order to illustrate the
basic concepts. But a real application would get most or all of
its templates directly from the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>, using the
aptly named <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><tt class="xref py py-meth docutils literal"><span class="pre">get_template()</span></tt></a> method, which accepts the URI of the
desired template:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>
<span class="n">mylookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">'/docs'</span><span class="p">],</span> <span class="n">module_directory</span><span class="o">=</span><span class="s">'/tmp/mako_modules'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">serve_template</span><span class="p">(</span><span class="n">templatename</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">mylookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="n">templatename</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
<p>In the example above, we create a <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> which will
look for templates in the <tt class="docutils literal"><span class="pre">/docs</span></tt> directory, and will store
generated module files in the <tt class="docutils literal"><span class="pre">/tmp/mako_modules</span></tt> directory. The
lookup locates templates by appending the given URI to each of
its search directories; so if you gave it a URI of
<tt class="docutils literal"><span class="pre">/etc/beans/info.txt</span></tt>, it would search for the file
<tt class="docutils literal"><span class="pre">/docs/etc/beans/info.txt</span></tt>, else raise a <tt class="xref py py-class docutils literal"><span class="pre">TopLevelNotFound</span></tt>
exception, which is a custom Mako exception.</p>
<p>When the lookup locates templates, it will also assign a <tt class="docutils literal"><span class="pre">uri</span></tt>
property to the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> which is the URI passed to the
<a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><tt class="xref py py-meth docutils literal"><span class="pre">get_template()</span></tt></a> call. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> uses this URI to calculate the
name of its module file. So in the above example, a
<tt class="docutils literal"><span class="pre">templatename</span></tt> argument of <tt class="docutils literal"><span class="pre">/etc/beans/info.txt</span></tt> will create a
module file <tt class="docutils literal"><span class="pre">/tmp/mako_modules/etc/beans/info.txt.py</span></tt>.</p>
<div class="section" id="setting-the-collection-size">
<h3>Setting the Collection Size<a class="headerlink" href="#setting-the-collection-size" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> also serves the important need of caching a
fixed set of templates in memory at a given time, so that
successive URI lookups do not result in full template
compilations and/or module reloads on each request. By default,
the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> size is unbounded. You can specify a fixed
size using the <tt class="docutils literal"><span class="pre">collection_size</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mylookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">'/docs'</span><span class="p">],</span>
<span class="n">module_directory</span><span class="o">=</span><span class="s">'/tmp/mako_modules'</span><span class="p">,</span> <span class="n">collection_size</span><span class="o">=</span><span class="mi">500</span><span class="p">)</span>
</pre></div>
</div>
<p>The above lookup will continue to load templates into memory
until it reaches a count of around 500. At that point, it will
clean out a certain percentage of templates using a least
recently used scheme.</p>
</div>
<div class="section" id="setting-filesystem-checks">
<h3>Setting Filesystem Checks<a class="headerlink" href="#setting-filesystem-checks" title="Permalink to this headline">¶</a></h3>
<p>Another important flag on <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> is
<tt class="docutils literal"><span class="pre">filesystem_checks</span></tt>. This defaults to <tt class="docutils literal"><span class="pre">True</span></tt>, and says that each
time a template is returned by the <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><tt class="xref py py-meth docutils literal"><span class="pre">get_template()</span></tt></a> method, the
revision time of the original template file is checked against
the last time the template was loaded, and if the file is newer
will reload its contents and recompile the template. On a
production system, setting <tt class="docutils literal"><span class="pre">filesystem_checks</span></tt> to <tt class="docutils literal"><span class="pre">False</span></tt> can
afford a small to moderate performance increase (depending on
the type of filesystem used).</p>
</div>
</div>
<div class="section" id="using-unicode-and-encoding">
<span id="usage-unicode"></span><h2>Using Unicode and Encoding<a class="headerlink" href="#using-unicode-and-encoding" title="Permalink to this headline">¶</a></h2>
<p>Both <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> and <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> accept <tt class="docutils literal"><span class="pre">output_encoding</span></tt>
and <tt class="docutils literal"><span class="pre">encoding_errors</span></tt> parameters which can be used to encode the
output in any Python supported codec:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>
<span class="n">mylookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">'/docs'</span><span class="p">],</span> <span class="n">output_encoding</span><span class="o">=</span><span class="s">'utf-8'</span><span class="p">,</span> <span class="n">encoding_errors</span><span class="o">=</span><span class="s">'replace'</span><span class="p">)</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">mylookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s">"foo.txt"</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>When using Python 3, the <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> method will return a <tt class="docutils literal"><span class="pre">bytes</span></tt>
object, <strong>if</strong> <tt class="docutils literal"><span class="pre">output_encoding</span></tt> is set. Otherwise it returns a
<tt class="docutils literal"><span class="pre">string</span></tt>.</p>
<p>Additionally, the <a class="reference internal" href="#mako.template.Template.render_unicode" title="mako.template.Template.render_unicode"><tt class="xref py py-meth docutils literal"><span class="pre">render_unicode()</span></tt></a> method exists which will
return the template output as a Python <tt class="docutils literal"><span class="pre">unicode</span></tt> object, or in
Python 3 a <tt class="docutils literal"><span class="pre">string</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">()</span>
</pre></div>
</div>
<p>The above method disregards the output encoding keyword
argument; you can encode yourself by saying:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">()</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">'utf-8'</span><span class="p">,</span> <span class="s">'replace'</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that Mako’s ability to return data in any encoding and/or
<tt class="docutils literal"><span class="pre">unicode</span></tt> implies that the underlying output stream of the
template is a Python unicode object. This behavior is described
fully in <a class="reference internal" href="unicode.html"><em>The Unicode Chapter</em></a>.</p>
</div>
<div class="section" id="handling-exceptions">
<span id="id1"></span><h2>Handling Exceptions<a class="headerlink" href="#handling-exceptions" title="Permalink to this headline">¶</a></h2>
<p>Template exceptions can occur in two distinct places. One is
when you <strong>lookup, parse and compile</strong> the template, the other
is when you <strong>run</strong> the template. Within the running of a
template, exceptions are thrown normally from whatever Python
code originated the issue. Mako has its own set of exception
classes which mostly apply to the lookup and lexer/compiler
stages of template construction. Mako provides some library
routines that can be used to help provide Mako-specific
information about any exception’s stack trace, as well as
formatting the exception within textual or HTML format. In all
cases, the main value of these handlers is that of converting
Python filenames, line numbers, and code samples into Mako
template filenames, line numbers, and code samples. All lines
within a stack trace which correspond to a Mako template module
will be converted to be against the originating template file.</p>
<p>To format exception traces, the <a class="reference internal" href="#mako.exceptions.text_error_template" title="mako.exceptions.text_error_template"><tt class="xref py py-func docutils literal"><span class="pre">text_error_template()</span></tt></a> and
<a class="reference internal" href="#mako.exceptions.html_error_template" title="mako.exceptions.html_error_template"><tt class="xref py py-func docutils literal"><span class="pre">html_error_template()</span></tt></a> functions are provided. They make usage of
<tt class="docutils literal"><span class="pre">sys.exc_info()</span></tt> to get at the most recently thrown exception.
Usage of these handlers usually looks like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako</span> <span class="kn">import</span> <span class="n">exceptions</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">lookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
<span class="k">except</span><span class="p">:</span>
<span class="k">print</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">text_error_template</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>Or for the HTML render function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako</span> <span class="kn">import</span> <span class="n">exceptions</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">lookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
<span class="k">except</span><span class="p">:</span>
<span class="k">print</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">html_error_template</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#mako.exceptions.html_error_template" title="mako.exceptions.html_error_template"><tt class="xref py py-func docutils literal"><span class="pre">html_error_template()</span></tt></a> template accepts two options:
specifying <tt class="docutils literal"><span class="pre">full=False</span></tt> causes only a section of an HTML
document to be rendered. Specifying <tt class="docutils literal"><span class="pre">css=False</span></tt> will disable the
default stylesheet from being rendered.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">html_error_template</span><span class="p">()</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">full</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
<p>The HTML render function is also available built-in to
<a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> using the <tt class="docutils literal"><span class="pre">format_exceptions</span></tt> flag. In this case, any
exceptions raised within the <strong>render</strong> stage of the template
will result in the output being substituted with the output of
<a class="reference internal" href="#mako.exceptions.html_error_template" title="mako.exceptions.html_error_template"><tt class="xref py py-func docutils literal"><span class="pre">html_error_template()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">filename</span><span class="o">=</span><span class="s">"/foo/bar"</span><span class="p">,</span> <span class="n">format_exceptions</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p>Note that the compile stage of the above template occurs when
you construct the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> itself, and no output stream is
defined. Therefore exceptions which occur within the
lookup/parse/compile stage will not be handled and will
propagate normally. While the pre-render traceback usually will
not include any Mako-specific lines anyway, it will mean that
exceptions which occur previous to rendering and those which
occur within rendering will be handled differently... so the
<tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">except</span></tt> patterns described previously are probably of more
general use.</p>
<p>The underlying object used by the error template functions is
the <a class="reference internal" href="#mako.exceptions.RichTraceback" title="mako.exceptions.RichTraceback"><tt class="xref py py-class docutils literal"><span class="pre">RichTraceback</span></tt></a> object. This object can also be used
directly to provide custom error views. Here’s an example usage
which describes its general API:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.exceptions</span> <span class="kn">import</span> <span class="n">RichTraceback</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">lookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
<span class="k">except</span><span class="p">:</span>
<span class="n">traceback</span> <span class="o">=</span> <span class="n">RichTraceback</span><span class="p">()</span>
<span class="k">for</span> <span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">lineno</span><span class="p">,</span> <span class="n">function</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span> <span class="ow">in</span> <span class="n">traceback</span><span class="o">.</span><span class="n">traceback</span><span class="p">:</span>
<span class="k">print</span> <span class="s">"File </span><span class="si">%s</span><span class="s">, line </span><span class="si">%s</span><span class="s">, in </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">lineno</span><span class="p">,</span> <span class="n">function</span><span class="p">)</span>
<span class="k">print</span> <span class="n">line</span><span class="p">,</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span>
<span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">traceback</span><span class="o">.</span><span class="n">error</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span><span class="p">),</span> <span class="n">traceback</span><span class="o">.</span><span class="n">error</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="common-framework-integrations">
<h2>Common Framework Integrations<a class="headerlink" href="#common-framework-integrations" title="Permalink to this headline">¶</a></h2>
<p>The Mako distribution includes a little bit of helper code for
the purpose of using Mako in some popular web framework
scenarios. This is a brief description of what’s included.</p>
<div class="section" id="wsgi">
<h3>WSGI<a class="headerlink" href="#wsgi" title="Permalink to this headline">¶</a></h3>
<p>A sample WSGI application is included in the distribution in the
file <tt class="docutils literal"><span class="pre">examples/wsgi/run_wsgi.py</span></tt>. This runner is set up to pull
files from a <cite>templates</cite> as well as an <cite>htdocs</cite> directory and
includes a rudimental two-file layout. The WSGI runner acts as a
fully functional standalone web server, using <tt class="docutils literal"><span class="pre">wsgiutils</span></tt> to run
itself, and propagates GET and POST arguments from the request
into the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a>, can serve images, CSS files and other kinds
of files, and also displays errors using Mako’s included
exception-handling utilities.</p>
</div>
<div class="section" id="pygments">
<h3>Pygments<a class="headerlink" href="#pygments" title="Permalink to this headline">¶</a></h3>
<p>A <a class="reference external" href="http://pygments.pocoo.org">Pygments</a>-compatible syntax
highlighting module is included under <tt class="xref py py-mod docutils literal"><span class="pre">mako.ext.pygmentplugin</span></tt>.
This module is used in the generation of Mako documentation and
also contains various <cite>setuptools</cite> entry points under the heading
<tt class="docutils literal"><span class="pre">pygments.lexers</span></tt>, including <tt class="docutils literal"><span class="pre">mako</span></tt>, <tt class="docutils literal"><span class="pre">html+mako</span></tt>, <tt class="docutils literal"><span class="pre">xml+mako</span></tt>
(see the <tt class="docutils literal"><span class="pre">setup.py</span></tt> file for all the entry points).</p>
</div>
<div class="section" id="babel">
<h3>Babel<a class="headerlink" href="#babel" title="Permalink to this headline">¶</a></h3>
<p>Mako provides support for extracting <cite>gettext</cite> messages from
templates via a <a class="reference external" href="http://babel.edgewall.org/">Babel</a> extractor
entry point under <tt class="docutils literal"><span class="pre">mako.ext.babelplugin</span></tt>.</p>
<p><cite>Gettext</cite> messages are extracted from all Python code sections,
including those of control lines and expressions embedded
in tags.</p>
<p><a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/messages.html#comments-tags-and-translator-comments-explanation">Translator
comments</a>
may also be extracted from Mako templates when a comment tag is
specified to <a class="reference external" href="http://babel.edgewall.org/">Babel</a> (such as with
the <tt class="docutils literal"><span class="pre">-c</span></tt> option).</p>
<p>For example, a project <tt class="docutils literal"><span class="pre">"myproj"</span></tt> contains the following Mako
template at <tt class="docutils literal"><span class="pre">myproj/myproj/templates/name.html</span></tt>:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="x"><div id="name"></span>
<span class="x"> Name:</span>
<span class="x"> ## TRANSLATORS: This is a proper name. See the gettext</span>
<span class="x"> ## manual, section Names.</span>
<span class="x"> </span><span class="cp">${</span><span class="n">_</span><span class="p">(</span><span class="s">'Francois Pinard'</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
<span class="x"></div></span>
</pre></div>
</div>
<p>To extract gettext messages from this template the project needs
a Mako section in its <a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration">Babel Extraction Method Mapping
file</a>
(typically located at <tt class="docutils literal"><span class="pre">myproj/babel.cfg</span></tt>):</p>
<div class="highlight-cfg"><div class="highlight"><pre><span class="c1"># Extraction from Python source files</span>
<span class="k">[python: myproj/**.py]</span>
<span class="c1"># Extraction from Mako templates</span>
<span class="k">[mako: myproj/templates/**.html]</span>
<span class="na">input_encoding</span> <span class="o">=</span> <span class="s">utf-8</span>
</pre></div>
</div>
<p>The Mako extractor supports an optional <tt class="docutils literal"><span class="pre">input_encoding</span></tt>
parameter specifying the encoding of the templates (identical to
<a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>/<a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>‘s <tt class="docutils literal"><span class="pre">input_encoding</span></tt> parameter).</p>
<p>Invoking <a class="reference external" href="http://babel.edgewall.org/">Babel</a>‘s extractor at the
command line in the project’s root directory:</p>
<div class="highlight-sh"><div class="highlight"><pre>myproj<span class="nv">$ </span>pybabel extract -F babel.cfg -c <span class="s2">"TRANSLATORS:"</span> .
</pre></div>
</div>
<p>will output a <cite>gettext</cite> catalog to <cite>stdout</cite> including the following:</p>
<div class="highlight-pot"><div class="highlight"><pre><span class="c1">#. TRANSLATORS: This is a proper name. See the gettext</span>
<span class="c1">#. manual, section Names.</span>
<span class="kd">#: myproj/templates/name.html:5</span>
<span class="nv">msgid</span> <span class="s">"Francois Pinard"</span>
<span class="nv">msgstr</span> <span class="s">""</span>
</pre></div>
</div>
<p>This is only a basic example:
<a class="reference external" href="http://babel.edgewall.org/">Babel</a> can be invoked from <tt class="docutils literal"><span class="pre">setup.py</span></tt>
and its command line options specified in the accompanying
<tt class="docutils literal"><span class="pre">setup.cfg</span></tt> via <a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/setup.html">Babel Distutils/Setuptools
Integration</a>.</p>
<p>Comments must immediately precede a <cite>gettext</cite> message to be
extracted. In the following case the <tt class="docutils literal"><span class="pre">TRANSLATORS:</span></tt> comment would
not have been extracted:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="x"><div id="name"></span>
<span class="x"> ## TRANSLATORS: This is a proper name. See the gettext</span>
<span class="x"> ## manual, section Names.</span>
<span class="x"> Name: </span><span class="cp">${</span><span class="n">_</span><span class="p">(</span><span class="s">'Francois Pinard'</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
<span class="x"></div></span>
</pre></div>
</div>
<p>See the <a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/index.html">Babel User
Guide</a>
for more information.</p>
</div>
</div>
<div class="section" id="api-reference">
<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="mako.template.Template">
<em class="property">class </em><tt class="descclassname">mako.template.</tt><tt class="descname">Template</tt><big>(</big><em>text=None</em>, <em>filename=None</em>, <em>uri=None</em>, <em>format_exceptions=False</em>, <em>error_handler=None</em>, <em>lookup=None</em>, <em>output_encoding=None</em>, <em>encoding_errors='strict'</em>, <em>module_directory=None</em>, <em>cache_args=None</em>, <em>cache_impl='beaker'</em>, <em>cache_enabled=True</em>, <em>cache_type=None</em>, <em>cache_dir=None</em>, <em>cache_url=None</em>, <em>module_filename=None</em>, <em>input_encoding=None</em>, <em>disable_unicode=False</em>, <em>module_writer=None</em>, <em>bytestring_passthrough=False</em>, <em>default_filters=None</em>, <em>buffer_filters=()</em>, <em>strict_undefined=False</em>, <em>imports=None</em>, <em>future_imports=None</em>, <em>enable_loop=True</em>, <em>preprocessor=None</em>, <em>lexer_cls=None</em><big>)</big><a class="headerlink" href="#mako.template.Template" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
<p>Represents a compiled template.</p>
<p><a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> includes a reference to the original
template source (via the <a class="reference internal" href="#RichTraceback.source" title="RichTraceback.source"><tt class="xref py py-attr docutils literal"><span class="pre">source</span></tt></a> attribute)
as well as the source code of the
generated Python module (i.e. the <a class="reference internal" href="#mako.template.Template.code" title="mako.template.Template.code"><tt class="xref py py-attr docutils literal"><span class="pre">code</span></tt></a> attribute),
as well as a reference to an actual Python module.</p>
<p><a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> is constructed using either a literal string
representing the template text, or a filename representing a filesystem
path to a source file.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>text</strong> – textual template source. This argument is mutually
exclusive versus the <tt class="docutils literal"><span class="pre">filename</span></tt> parameter.</li>
<li><strong>filename</strong> – filename of the source template. This argument is
mutually exclusive versus the <tt class="docutils literal"><span class="pre">text</span></tt> parameter.</li>
<li><strong>buffer_filters</strong> – string list of filters to be applied
to the output of <tt class="docutils literal"><span class="pre">%def</span></tt>s which are buffered, cached, or otherwise
filtered, after all filters
defined with the <tt class="docutils literal"><span class="pre">%def</span></tt> itself have been applied. Allows the
creation of default expression filters that let the output
of return-valued <tt class="docutils literal"><span class="pre">%def</span></tt>s “opt out” of that filtering via
passing special attributes or objects.</li>
<li><strong>bytestring_passthrough</strong> – <p>When <tt class="docutils literal"><span class="pre">True</span></tt>, and <tt class="docutils literal"><span class="pre">output_encoding</span></tt> is
set to <tt class="docutils literal"><span class="pre">None</span></tt>, and <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">Template.render()</span></tt></a> is used to render,
the <cite>StringIO</cite> or <cite>cStringIO</cite> buffer will be used instead of the
default “fast” buffer. This allows raw bytestrings in the
output stream, such as in expressions, to pass straight
through to the buffer. This flag is forced
to <tt class="docutils literal"><span class="pre">True</span></tt> if <tt class="docutils literal"><span class="pre">disable_unicode</span></tt> is also configured.</p>
<div class="versionadded">
<p><span>New in version 0.4: </span>Added to provide the same behavior as that of the previous series.</p>
</div>
</li>
<li><strong>cache_args</strong> – Dictionary of cache configuration arguments that
will be passed to the <a class="reference internal" href="caching.html#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a>. See <a class="reference internal" href="caching.html"><em>Caching</em></a>.</li>
<li><strong>cache_dir</strong> – <div class="deprecated">
<p><span>Deprecated since version 0.6: </span>Use the <tt class="docutils literal"><span class="pre">'dir'</span></tt> argument in the <tt class="docutils literal"><span class="pre">cache_args</span></tt> dictionary.
See <a class="reference internal" href="caching.html"><em>Caching</em></a>.</p>
</div>
</li>
<li><strong>cache_enabled</strong> – Boolean flag which enables caching of this
template. See <a class="reference internal" href="caching.html"><em>Caching</em></a>.</li>
<li><strong>cache_impl</strong> – String name of a <a class="reference internal" href="caching.html#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> caching
implementation to use. Defaults to <tt class="docutils literal"><span class="pre">'beaker'</span></tt>.</li>
<li><strong>cache_type</strong> – <div class="deprecated">
<p><span>Deprecated since version 0.6: </span>Use the <tt class="docutils literal"><span class="pre">'type'</span></tt> argument in the <tt class="docutils literal"><span class="pre">cache_args</span></tt> dictionary.
See <a class="reference internal" href="caching.html"><em>Caching</em></a>.</p>
</div>
</li>
<li><strong>cache_url</strong> – <div class="deprecated">
<p><span>Deprecated since version 0.6: </span>Use the <tt class="docutils literal"><span class="pre">'url'</span></tt> argument in the <tt class="docutils literal"><span class="pre">cache_args</span></tt> dictionary.
See <a class="reference internal" href="caching.html"><em>Caching</em></a>.</p>
</div>
</li>
<li><strong>default_filters</strong> – List of string filter names that will
be applied to all expressions. See <a class="reference internal" href="filtering.html#filtering-default-filters"><em>The default_filters Argument</em></a>.</li>
<li><strong>disable_unicode</strong> – Disables all awareness of Python Unicode
objects. See <a class="reference internal" href="unicode.html#unicode-disabled"><em>Saying to Heck with It: Disabling the Usage of Unicode Entirely</em></a>.</li>
<li><strong>enable_loop</strong> – When <tt class="docutils literal"><span class="pre">True</span></tt>, enable the <tt class="docutils literal"><span class="pre">loop</span></tt> context variable.
This can be set to <tt class="docutils literal"><span class="pre">False</span></tt> to support templates that may
be making usage of the name “<tt class="docutils literal"><span class="pre">loop</span></tt>”. Individual templates can
re-enable the “loop” context by placing the directive
<tt class="docutils literal"><span class="pre">enable_loop="True"</span></tt> inside the <tt class="docutils literal"><span class="pre"><%page></span></tt> tag – see
<a class="reference internal" href="runtime.html#migrating-loop"><em>Migrating Legacy Templates that Use the Word “loop”</em></a>.</li>
<li><strong>encoding_errors</strong> – Error parameter passed to <tt class="docutils literal"><span class="pre">encode()</span></tt> when
string encoding is performed. See <a class="reference internal" href="#usage-unicode"><em>Using Unicode and Encoding</em></a>.</li>
<li><strong>error_handler</strong> – Python callable which is called whenever
compile or runtime exceptions occur. The callable is passed
the current context as well as the exception. If the
callable returns <tt class="docutils literal"><span class="pre">True</span></tt>, the exception is considered to
be handled, else it is re-raised after the function
completes. Is used to provide custom error-rendering
functions.</li>
<li><strong>format_exceptions</strong> – if <tt class="docutils literal"><span class="pre">True</span></tt>, exceptions which occur during
the render phase of this template will be caught and
formatted into an HTML error page, which then becomes the
rendered result of the <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> call. Otherwise,
runtime exceptions are propagated outwards.</li>
<li><strong>imports</strong> – String list of Python statements, typically individual
“import” lines, which will be placed into the module level
preamble of all generated Python modules. See the example
in <a class="reference internal" href="filtering.html#filtering-default-filters"><em>The default_filters Argument</em></a>.</li>
<li><strong>future_imports</strong> – String list of names to import from <cite>__future__</cite>.
These will be concatenated into a comma-separated string and inserted
into the beginning of the template, e.g. <tt class="docutils literal"><span class="pre">futures_imports=['FOO',</span>
<span class="pre">'BAR']</span></tt> results in <tt class="docutils literal"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">FOO,</span> <span class="pre">BAR</span></tt>. If you’re
interested in using features like the new division operator, you must
use future_imports to convey that to the renderer, as otherwise the
import will not appear as the first executed statement in the generated
code and will therefore not have the desired effect.</li>
<li><strong>input_encoding</strong> – Encoding of the template’s source code. Can
be used in lieu of the coding comment. See
<a class="reference internal" href="#usage-unicode"><em>Using Unicode and Encoding</em></a> as well as <a class="reference internal" href="unicode.html"><em>The Unicode Chapter</em></a> for
details on source encoding.</li>
<li><strong>lookup</strong> – a <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> instance that will be used
for all file lookups via the <tt class="docutils literal"><span class="pre"><%namespace></span></tt>,
<tt class="docutils literal"><span class="pre"><%include></span></tt>, and <tt class="docutils literal"><span class="pre"><%inherit></span></tt> tags. See
<a class="reference internal" href="#usage-templatelookup"><em>Using TemplateLookup</em></a>.</li>
<li><strong>module_directory</strong> – Filesystem location where generated
Python module files will be placed.</li>
<li><strong>module_filename</strong> – Overrides the filename of the generated
Python module file. For advanced usage only.</li>
<li><strong>module_writer</strong> – <p>A callable which overrides how the Python
module is written entirely. The callable is passed the
encoded source content of the module and the destination
path to be written to. The default behavior of module writing
uses a tempfile in conjunction with a file move in order
to make the operation atomic. So a user-defined module
writing function that mimics the default behavior would be:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">tempfile</span>
<span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">shutil</span>
<span class="k">def</span> <span class="nf">module_writer</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">outputpath</span><span class="p">):</span>
<span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span> <span class="o">=</span> \
<span class="n">tempfile</span><span class="o">.</span><span class="n">mkstemp</span><span class="p">(</span>
<span class="nb">dir</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">outputpath</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">source</span><span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">close</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
<span class="n">shutil</span><span class="o">.</span><span class="n">move</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">outputpath</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span>
<span class="n">filename</span><span class="o">=</span><span class="s">"index.html"</span><span class="p">,</span>
<span class="n">module_directory</span><span class="o">=</span><span class="s">"/path/to/modules"</span><span class="p">,</span>
<span class="n">module_writer</span><span class="o">=</span><span class="n">module_writer</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The function is provided for unusual configurations where
certain platform-specific permissions or other special
steps are needed.</p>
</li>
<li><strong>output_encoding</strong> – The encoding to use when <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a>
is called.
See <a class="reference internal" href="#usage-unicode"><em>Using Unicode and Encoding</em></a> as well as <a class="reference internal" href="unicode.html"><em>The Unicode Chapter</em></a>.</li>
<li><strong>preprocessor</strong> – Python callable which will be passed
the full template source before it is parsed. The return
result of the callable will be used as the template source
code.</li>
<li><strong>lexer_cls</strong> – <p>A <tt class="xref py py-class docutils literal"><span class="pre">Lexer</span></tt> class used to parse
the template. The <tt class="xref py py-class docutils literal"><span class="pre">Lexer</span></tt> class is used by
default.</p>
<div class="versionadded">
<p><span>New in version 0.7.4.</span></p>
</div>
</li>
<li><strong>strict_undefined</strong> – <p>Replaces the automatic usage of
<tt class="docutils literal"><span class="pre">UNDEFINED</span></tt> for any undeclared variables not located in
the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> with an immediate raise of
<tt class="docutils literal"><span class="pre">NameError</span></tt>. The advantage is immediate reporting of
missing variables which include the name.</p>
<div class="versionadded">
<p><span>New in version 0.3.6.</span></p>
</div>
</li>
<li><strong>uri</strong> – string URI or other identifier for this template.
If not provided, the <tt class="docutils literal"><span class="pre">uri</span></tt> is generated from the filesystem
path, or from the in-memory identity of a non-file-based
template. The primary usage of the <tt class="docutils literal"><span class="pre">uri</span></tt> is to provide a key
within <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>, as well as to generate the
file path of the generated Python module file, if
<tt class="docutils literal"><span class="pre">module_directory</span></tt> is specified.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="attribute">
<dt id="mako.template.Template.code">
<tt class="descname">code</tt><a class="headerlink" href="#mako.template.Template.code" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the module source code for this <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="mako.template.Template.get_def">
<tt class="descname">get_def</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#mako.template.Template.get_def" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a def of this template as a <a class="reference internal" href="#mako.template.DefTemplate" title="mako.template.DefTemplate"><tt class="xref py py-class docutils literal"><span class="pre">DefTemplate</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="mako.template.Template.render">
<tt class="descname">render</tt><big>(</big><em>*args</em>, <em>**data</em><big>)</big><a class="headerlink" href="#mako.template.Template.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Render the output of this template as a string.</p>
<p>If the template specifies an output encoding, the string
will be encoded accordingly, else the output is raw (raw
output uses <cite>cStringIO</cite> and can’t handle multibyte
characters). A <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> object is created corresponding
to the given data. Arguments that are explicitly declared
by this template’s internal rendering method are also
pulled from the given <tt class="docutils literal"><span class="pre">*args</span></tt>, <tt class="docutils literal"><span class="pre">**data</span></tt> members.</p>
</dd></dl>
<dl class="method">
<dt id="mako.template.Template.render_context">
<tt class="descname">render_context</tt><big>(</big><em>context</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mako.template.Template.render_context" title="Permalink to this definition">¶</a></dt>
<dd><p>Render this <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> with the given context.</p>
<p>The data is written to the context’s buffer.</p>
</dd></dl>
<dl class="method">
<dt id="mako.template.Template.render_unicode">
<tt class="descname">render_unicode</tt><big>(</big><em>*args</em>, <em>**data</em><big>)</big><a class="headerlink" href="#mako.template.Template.render_unicode" title="Permalink to this definition">¶</a></dt>
<dd><p>Render the output of this template as a unicode object.</p>
</dd></dl>
<dl class="attribute">
<dt id="mako.template.Template.source">
<tt class="descname">source</tt><a class="headerlink" href="#mako.template.Template.source" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the template source code for this <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="mako.template.DefTemplate">
<em class="property">class </em><tt class="descclassname">mako.template.</tt><tt class="descname">DefTemplate</tt><big>(</big><em>parent</em>, <em>callable_</em><big>)</big><a class="headerlink" href="#mako.template.DefTemplate" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">mako.template.Template</span></tt></a></p>
<p>A <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> which represents a callable def in a parent
template.</p>
</dd></dl>
<dl class="class">
<dt id="mako.lookup.TemplateCollection">
<em class="property">class </em><tt class="descclassname">mako.lookup.</tt><tt class="descname">TemplateCollection</tt><a class="headerlink" href="#mako.lookup.TemplateCollection" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
<p>Represent a collection of <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> objects,
identifiable via URI.</p>
<p>A <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></tt></a> is linked to the usage of
all template tags that address other templates, such
as <tt class="docutils literal"><span class="pre"><%include></span></tt>, <tt class="docutils literal"><span class="pre"><%namespace></span></tt>, and <tt class="docutils literal"><span class="pre"><%inherit></span></tt>.
The <tt class="docutils literal"><span class="pre">file</span></tt> attribute of each of those tags refers
to a string URI that is passed to that <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>
object’s <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></tt></a> for resolution.</p>
<p><a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></tt></a> is an abstract class,
with the usual default implementation being <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>.</p>
<dl class="method">
<dt id="mako.lookup.TemplateCollection.adjust_uri">
<tt class="descname">adjust_uri</tt><big>(</big><em>uri</em>, <em>filename</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateCollection.adjust_uri" title="Permalink to this definition">¶</a></dt>
<dd><p>Adjust the given <tt class="docutils literal"><span class="pre">uri</span></tt> based on the calling <tt class="docutils literal"><span class="pre">filename</span></tt>.</p>
<p>When this method is called from the runtime, the
<tt class="docutils literal"><span class="pre">filename</span></tt> parameter is taken directly to the <tt class="docutils literal"><span class="pre">filename</span></tt>
attribute of the calling template. Therefore a custom
<a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></tt></a> subclass can place any string
identifier desired in the <tt class="docutils literal"><span class="pre">filename</span></tt> parameter of the
<a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> objects it constructs and have them come back
here.</p>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateCollection.filename_to_uri">
<tt class="descname">filename_to_uri</tt><big>(</big><em>uri</em>, <em>filename</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateCollection.filename_to_uri" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert the given <tt class="docutils literal"><span class="pre">filename</span></tt> to a URI relative to
this <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateCollection.get_template">
<tt class="descname">get_template</tt><big>(</big><em>uri</em>, <em>relativeto=None</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateCollection.get_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object corresponding to the given
<tt class="docutils literal"><span class="pre">uri</span></tt>.</p>
<p>The default implementation raises
<tt class="xref py py-class docutils literal"><span class="pre">NotImplementedError</span></tt>. Implementations should
raise <tt class="xref py py-class docutils literal"><span class="pre">TemplateLookupException</span></tt> if the given <tt class="docutils literal"><span class="pre">uri</span></tt>
cannot be resolved.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>uri</strong> – String URI of the template to be resolved.</li>
<li><strong>relativeto</strong> – if present, the given <tt class="docutils literal"><span class="pre">uri</span></tt> is assumed to
be relative to this URI.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateCollection.has_template">
<tt class="descname">has_template</tt><big>(</big><em>uri</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateCollection.has_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <tt class="docutils literal"><span class="pre">True</span></tt> if this <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> is
capable of returning a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object for the
given <tt class="docutils literal"><span class="pre">uri</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>uri</strong> – String URI of the template to be resolved.</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="mako.lookup.TemplateLookup">
<em class="property">class </em><tt class="descclassname">mako.lookup.</tt><tt class="descname">TemplateLookup</tt><big>(</big><em>directories=None</em>, <em>module_directory=None</em>, <em>filesystem_checks=True</em>, <em>collection_size=-1</em>, <em>format_exceptions=False</em>, <em>error_handler=None</em>, <em>disable_unicode=False</em>, <em>bytestring_passthrough=False</em>, <em>output_encoding=None</em>, <em>encoding_errors='strict'</em>, <em>cache_args=None</em>, <em>cache_impl='beaker'</em>, <em>cache_enabled=True</em>, <em>cache_type=None</em>, <em>cache_dir=None</em>, <em>cache_url=None</em>, <em>modulename_callable=None</em>, <em>module_writer=None</em>, <em>default_filters=None</em>, <em>buffer_filters=()</em>, <em>strict_undefined=False</em>, <em>imports=None</em>, <em>future_imports=None</em>, <em>enable_loop=True</em>, <em>input_encoding=None</em>, <em>preprocessor=None</em>, <em>lexer_cls=None</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateLookup" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">mako.lookup.TemplateCollection</span></tt></a></p>
<p>Represent a collection of templates that locates template source files
from the local filesystem.</p>
<p>The primary argument is the <tt class="docutils literal"><span class="pre">directories</span></tt> argument, the list of
directories to search:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">([</span><span class="s">"/path/to/templates"</span><span class="p">])</span>
<span class="n">some_template</span> <span class="o">=</span> <span class="n">lookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s">"/index.html"</span><span class="p">)</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> can also be given <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> objects
programatically using <a class="reference internal" href="#mako.lookup.TemplateLookup.put_string" title="mako.lookup.TemplateLookup.put_string"><tt class="xref py py-meth docutils literal"><span class="pre">put_string()</span></tt></a> or <a class="reference internal" href="#mako.lookup.TemplateLookup.put_template" title="mako.lookup.TemplateLookup.put_template"><tt class="xref py py-meth docutils literal"><span class="pre">put_template()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">()</span>
<span class="n">lookup</span><span class="o">.</span><span class="n">put_string</span><span class="p">(</span><span class="s">"base.html"</span><span class="p">,</span> <span class="s">'''</span>
<span class="s"> <html><body>${self.next()}</body></html></span>
<span class="s">'''</span><span class="p">)</span>
<span class="n">lookup</span><span class="o">.</span><span class="n">put_string</span><span class="p">(</span><span class="s">"hello.html"</span><span class="p">,</span> <span class="s">'''</span>
<span class="s"> <</span><span class="si">%i</span><span class="s">nclude file='base.html'/></span>
<span class="s"> Hello, world !</span>
<span class="s">'''</span><span class="p">)</span>
</pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>directories</strong> – A list of directory names which will be
searched for a particular template URI. The URI is appended
to each directory and the filesystem checked.</li>
<li><strong>collection_size</strong> – Approximate size of the collection used
to store templates. If left at its default of <tt class="docutils literal"><span class="pre">-1</span></tt>, the size
is unbounded, and a plain Python dictionary is used to
relate URI strings to <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> instances.
Otherwise, a least-recently-used cache object is used which
will maintain the size of the collection approximately to
the number given.</li>
<li><strong>filesystem_checks</strong> – When at its default value of <tt class="docutils literal"><span class="pre">True</span></tt>,
each call to <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><tt class="xref py py-meth docutils literal"><span class="pre">TemplateLookup.get_template()</span></tt></a> will
compare the filesystem last modified time to the time in
which an existing <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object was created.
This allows the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> to regenerate a
new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> whenever the original source has
been updated. Set this to <tt class="docutils literal"><span class="pre">False</span></tt> for a very minor
performance increase.</li>
<li><strong>modulename_callable</strong> – A callable which, when present,
is passed the path of the source file as well as the
requested URI, and then returns the full path of the
generated Python module file. This is used to inject
alternate schemes for Python module location. If left at
its default of <tt class="docutils literal"><span class="pre">None</span></tt>, the built in system of generation
based on <tt class="docutils literal"><span class="pre">module_directory</span></tt> plus <tt class="docutils literal"><span class="pre">uri</span></tt> is used.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>All other keyword parameters available for
<a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> are mirrored here. When new
<a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> objects are created, the keywords
established with this <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> are passed on
to each new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>.</p>
<dl class="method">
<dt id="mako.lookup.TemplateLookup.adjust_uri">
<tt class="descname">adjust_uri</tt><big>(</big><em>uri</em>, <em>relativeto</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateLookup.adjust_uri" title="Permalink to this definition">¶</a></dt>
<dd><p>Adjust the given <tt class="docutils literal"><span class="pre">uri</span></tt> based on the given relative URI.</p>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateLookup.filename_to_uri">
<tt class="descname">filename_to_uri</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateLookup.filename_to_uri" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert the given <tt class="docutils literal"><span class="pre">filename</span></tt> to a URI relative to
this <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><tt class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateLookup.get_template">
<tt class="descname">get_template</tt><big>(</big><em>uri</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateLookup.get_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object corresponding to the given
<tt class="docutils literal"><span class="pre">uri</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">relativeto</span></tt> argument is not supported here at the moment.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateLookup.put_string">
<tt class="descname">put_string</tt><big>(</big><em>uri</em>, <em>text</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateLookup.put_string" title="Permalink to this definition">¶</a></dt>
<dd><p>Place a new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object into this
<a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>, based on the given string of
<tt class="docutils literal"><span class="pre">text</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="mako.lookup.TemplateLookup.put_template">
<tt class="descname">put_template</tt><big>(</big><em>uri</em>, <em>template</em><big>)</big><a class="headerlink" href="#mako.lookup.TemplateLookup.put_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Place a new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object into this
<a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>, based on the given
<a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="mako.exceptions.RichTraceback">
<em class="property">class </em><tt class="descclassname">mako.exceptions.</tt><tt class="descname">RichTraceback</tt><big>(</big><em>error=None</em>, <em>traceback=None</em><big>)</big><a class="headerlink" href="#mako.exceptions.RichTraceback" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
<p>Pull the current exception from the <tt class="docutils literal"><span class="pre">sys</span></tt> traceback and extracts
Mako-specific template information.</p>
<p>See the usage examples in <a class="reference internal" href="#handling-exceptions"><em>Handling Exceptions</em></a>.</p>
<dl class="attribute">
<dt id="RichTraceback.error">
<tt class="descname">error</tt><a class="headerlink" href="#RichTraceback.error" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception instance.</p>
</dd></dl>
<dl class="attribute">
<dt id="RichTraceback.message">
<tt class="descname">message</tt><a class="headerlink" href="#RichTraceback.message" title="Permalink to this definition">¶</a></dt>
<dd><p>the exception error message as unicode.</p>
</dd></dl>
<dl class="attribute">
<dt id="RichTraceback.source">
<tt class="descname">source</tt><a class="headerlink" href="#RichTraceback.source" title="Permalink to this definition">¶</a></dt>
<dd><p>source code of the file where the error occurred.
If the error occurred within a compiled template,
this is the template source.</p>
</dd></dl>
<dl class="attribute">
<dt id="RichTraceback.lineno">
<tt class="descname">lineno</tt><a class="headerlink" href="#RichTraceback.lineno" title="Permalink to this definition">¶</a></dt>
<dd><p>line number where the error occurred. If the error
occurred within a compiled template, the line number
is adjusted to that of the template source.</p>
</dd></dl>
<dl class="attribute">
<dt id="RichTraceback.records">
<tt class="descname">records</tt><a class="headerlink" href="#RichTraceback.records" title="Permalink to this definition">¶</a></dt>
<dd><p>a list of 8-tuples containing the original
python traceback elements, plus the
filename, line number, source line, and full template source
for the traceline mapped back to its originating source
template, if any for that traceline (else the fields are <tt class="docutils literal"><span class="pre">None</span></tt>).</p>
</dd></dl>
<dl class="attribute">
<dt id="RichTraceback.reverse_records">
<tt class="descname">reverse_records</tt><a class="headerlink" href="#RichTraceback.reverse_records" title="Permalink to this definition">¶</a></dt>
<dd><p>the list of records in reverse
traceback – a list of 4-tuples, in the same format as a regular
python traceback, with template-corresponding
traceback records replacing the originals.</p>
</dd></dl>
<dl class="attribute">
<dt id="RichTraceback.reverse_traceback">
<tt class="descname">reverse_traceback</tt><a class="headerlink" href="#RichTraceback.reverse_traceback" title="Permalink to this definition">¶</a></dt>
<dd><p>the traceback list in reverse.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="mako.exceptions.html_error_template">
<tt class="descclassname">mako.exceptions.</tt><tt class="descname">html_error_template</tt><big>(</big><big>)</big><a class="headerlink" href="#mako.exceptions.html_error_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides a template that renders a stack trace in an HTML format,
providing an excerpt of code as well as substituting source template
filenames, line numbers and code for that of the originating source
template, as applicable.</p>
<p>The template’s default <tt class="docutils literal"><span class="pre">encoding_errors</span></tt> value is <tt class="docutils literal"><span class="pre">'htmlentityreplace'</span></tt>. The
template has two options. With the <tt class="docutils literal"><span class="pre">full</span></tt> option disabled, only a section of
an HTML document is returned. With the <tt class="docutils literal"><span class="pre">css</span></tt> option disabled, the default
stylesheet won’t be included.</p>
</dd></dl>
<dl class="function">
<dt id="mako.exceptions.text_error_template">
<tt class="descclassname">mako.exceptions.</tt><tt class="descname">text_error_template</tt><big>(</big><em>lookup=None</em><big>)</big><a class="headerlink" href="#mako.exceptions.text_error_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides a template that renders a stack trace in a similar format to
the Python interpreter, substituting source template filenames, line
numbers and code for that of the originating source template, as
applicable.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="index.html" title="previous chapter">Table of Contents</a>
Next:
<a href="syntax.html" title="next chapter">Syntax</a>
<div id="docs-copyright">
© Copyright the Mako authors and contributors.
Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1
with Mako templates.
</div>
</div>
</div>
<div class="clearfix">
<hr/>
<div class="copyright">Website content copyright © by Michael Bayer.
All rights reserved. Mako and its documentation are licensed
under the MIT license. mike(&)zzzcomputing.com</div>
</div>
</div>
</body>
</html>
