| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071 |
- <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.8.1 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.8.1',
- 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.8.1 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.8.1 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.8.1</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.8.1 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="c"># Extraction from Python source files</span>
- <span class="k">[python: myproj/**.py]</span>
- <span class="c"># 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>
- <p class="versionadded">
- <span class="versionmodified">New in version 0.4: </span>Added to provide the same behavior as that of the previous series.</p>
- </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> – <p class="deprecated">
- <span class="versionmodified">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>
- </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> – <p class="deprecated">
- <span class="versionmodified">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>
- </li>
- <li><strong>cache_url</strong> – <p class="deprecated">
- <span class="versionmodified">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>
- </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>
- <p class="versionadded">
- <span class="versionmodified">New in version 0.7.4.</span></p>
- </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>
- <p class="versionadded">
- <span class="versionmodified">New in version 0.3.6.</span></p>
- </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.1.3
- 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>
|