usage.html 100 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113
  1. <html xmlns="http://www.w3.org/1999/xhtml">
  2. <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  3. <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
  4. <head>
  5. <title>
  6. Usage
  7. &mdash;
  8. Mako 1.0.7 Documentation
  9. </title>
  10. <!-- begin iterate through sphinx environment css_files -->
  11. <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  12. <link rel="stylesheet" href="_static/docs.css" type="text/css" />
  13. <link rel="stylesheet" href="_static/site.css" type="text/css" />
  14. <link rel="stylesheet" href="_static/changelog.css" type="text/css" />
  15. <link rel="stylesheet" href="_static/sphinx_paramlinks.css" type="text/css" />
  16. <!-- end iterate through sphinx environment css_files -->
  17. <script type="text/javascript">
  18. var DOCUMENTATION_OPTIONS = {
  19. URL_ROOT: './',
  20. VERSION: '1.0.7',
  21. COLLAPSE_MODINDEX: false,
  22. FILE_SUFFIX: '.html'
  23. };
  24. </script>
  25. <script type="text/javascript" src="_static/jquery.js"></script>
  26. <script type="text/javascript" src="_static/underscore.js"></script>
  27. <script type="text/javascript" src="_static/doctools.js"></script>
  28. <link rel="index" title="Index" href="genindex.html" />
  29. <link rel="search" title="Search" href="search.html" />
  30. <link rel="top" title="Mako 1.0.7 Documentation" href="index.html" />
  31. <link rel="next" title="Syntax" href="syntax.html" />
  32. <link rel="prev" title="Table of Contents" href="index.html" />
  33. </head>
  34. <body>
  35. <div id="wrap">
  36. <div class="rightbar">
  37. <div class="slogan">
  38. Hyperfast and lightweight templating for the Python platform.
  39. </div>
  40. </div>
  41. <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
  42. <hr/>
  43. <div id="docs-container">
  44. <div id="docs-header">
  45. <h1>Mako 1.0.7 Documentation</h1>
  46. <div id="docs-search">
  47. Search:
  48. <form class="search" action="search.html" method="get">
  49. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  50. <input type="hidden" name="check_keywords" value="yes" />
  51. <input type="hidden" name="area" value="default" />
  52. </form>
  53. </div>
  54. <div id="docs-version-header">
  55. Release: <span class="version-num">1.0.7</span>
  56. </div>
  57. </div>
  58. <div id="docs-top-navigation">
  59. <div id="docs-top-page-control" class="docs-navigation-links">
  60. <ul>
  61. <li>Prev:
  62. <a href="index.html" title="previous chapter">Table of Contents</a>
  63. </li>
  64. <li>Next:
  65. <a href="syntax.html" title="next chapter">Syntax</a>
  66. </li>
  67. <li>
  68. <a href="index.html">Table of Contents</a> |
  69. <a href="genindex.html">Index</a>
  70. | <a href="_sources/usage.rst.txt">view source
  71. </li>
  72. </ul>
  73. </div>
  74. <div id="docs-navigation-banner">
  75. <a href="index.html">Mako 1.0.7 Documentation</a>
  76. »
  77. Usage
  78. <h2>
  79. Usage
  80. </h2>
  81. </div>
  82. </div>
  83. <div id="docs-body-container">
  84. <div id="docs-sidebar">
  85. <h3><a href="index.html">Table of Contents</a></h3>
  86. <ul>
  87. <li><a class="reference internal" href="#">Usage</a><ul>
  88. <li><a class="reference internal" href="#basic-usage">Basic Usage</a></li>
  89. <li><a class="reference internal" href="#using-file-based-templates">Using File-Based Templates</a></li>
  90. <li><a class="reference internal" href="#using-templatelookup">Using <code class="docutils literal"><span class="pre">TemplateLookup</span></code></a><ul>
  91. <li><a class="reference internal" href="#setting-the-collection-size">Setting the Collection Size</a></li>
  92. <li><a class="reference internal" href="#setting-filesystem-checks">Setting Filesystem Checks</a></li>
  93. </ul>
  94. </li>
  95. <li><a class="reference internal" href="#using-unicode-and-encoding">Using Unicode and Encoding</a></li>
  96. <li><a class="reference internal" href="#handling-exceptions">Handling Exceptions</a></li>
  97. <li><a class="reference internal" href="#common-framework-integrations">Common Framework Integrations</a><ul>
  98. <li><a class="reference internal" href="#wsgi">WSGI</a></li>
  99. <li><a class="reference internal" href="#pygments">Pygments</a></li>
  100. <li><a class="reference internal" href="#babel">Babel</a></li>
  101. </ul>
  102. </li>
  103. <li><a class="reference internal" href="#api-reference">API Reference</a></li>
  104. </ul>
  105. </li>
  106. </ul>
  107. <h4>Previous Topic</h4>
  108. <p>
  109. <a href="index.html" title="previous chapter">Table of Contents</a>
  110. </p>
  111. <h4>Next Topic</h4>
  112. <p>
  113. <a href="syntax.html" title="next chapter">Syntax</a>
  114. </p>
  115. <h4>Quick Search</h4>
  116. <p>
  117. <form class="search" action="search.html" method="get">
  118. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  119. <input type="hidden" name="check_keywords" value="yes" />
  120. <input type="hidden" name="area" value="default" />
  121. </form>
  122. </p>
  123. </div>
  124. <div id="docs-body" class="withsidebar" >
  125. <div class="section" id="usage">
  126. <span id="usage-toplevel"></span><h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
  127. <div class="section" id="basic-usage">
  128. <h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h2>
  129. <p>This section describes the Python API for Mako templates. If you
  130. are using Mako within a web framework such as Pylons, the work
  131. of integrating Mako&#8217;s API is already done for you, in which case
  132. you can skip to the next section, <a class="reference internal" href="syntax.html"><span class="std std-ref">Syntax</span></a>.</p>
  133. <p>The most basic way to create a template and render it is through
  134. the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> class:</p>
  135. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  136. <span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;hello world!&quot;</span><span class="p">)</span>
  137. <span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  138. </pre></div>
  139. </div>
  140. <p>Above, the text argument to <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> is <strong>compiled</strong> into a
  141. Python module representation. This module contains a function
  142. called <code class="docutils literal"><span class="pre">render_body()</span></code>, which produces the output of the
  143. template. When <code class="docutils literal"><span class="pre">mytemplate.render()</span></code> is called, Mako sets up a
  144. runtime environment for the template and calls the
  145. <code class="docutils literal"><span class="pre">render_body()</span></code> function, capturing the output into a buffer and
  146. returning its string contents.</p>
  147. <p>The code inside the <code class="docutils literal"><span class="pre">render_body()</span></code> function has access to a
  148. namespace of variables. You can specify these variables by
  149. sending them as additional keyword arguments to the <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a>
  150. method:</p>
  151. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  152. <span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;hello, ${name}!&quot;</span><span class="p">)</span>
  153. <span class="k">print</span><span class="p">(</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="s2">&quot;jack&quot;</span><span class="p">))</span>
  154. </pre></div>
  155. </div>
  156. <p>The <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> method calls upon Mako to create a
  157. <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object, which stores all the variable names accessible
  158. to the template and also stores a buffer used to capture output.
  159. You can create this <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> yourself and have the template
  160. render with it, using the <a class="reference internal" href="#mako.template.Template.render_context" title="mako.template.Template.render_context"><code class="xref py py-meth docutils literal"><span class="pre">render_context()</span></code></a> method:</p>
  161. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  162. <span class="kn">from</span> <span class="nn">mako.runtime</span> <span class="kn">import</span> <span class="n">Context</span>
  163. <span class="kn">from</span> <span class="nn">StringIO</span> <span class="kn">import</span> <span class="n">StringIO</span>
  164. <span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;hello, ${name}!&quot;</span><span class="p">)</span>
  165. <span class="n">buf</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">()</span>
  166. <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="s2">&quot;jack&quot;</span><span class="p">)</span>
  167. <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>
  168. <span class="k">print</span><span class="p">(</span><span class="n">buf</span><span class="o">.</span><span class="n">getvalue</span><span class="p">())</span>
  169. </pre></div>
  170. </div>
  171. </div>
  172. <div class="section" id="using-file-based-templates">
  173. <h2>Using File-Based Templates<a class="headerlink" href="#using-file-based-templates" title="Permalink to this headline">¶</a></h2>
  174. <p>A <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> can also load its template source code from a file,
  175. using the <code class="docutils literal"><span class="pre">filename</span></code> keyword argument:</p>
  176. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  177. <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="s1">&#39;/docs/mytmpl.txt&#39;</span><span class="p">)</span>
  178. <span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  179. </pre></div>
  180. </div>
  181. <p>For improved performance, a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> which is loaded from a
  182. file can also cache the source code to its generated module on
  183. the filesystem as a regular Python module file (i.e. a <code class="docutils literal"><span class="pre">.py</span></code>
  184. file). To do this, just add the <code class="docutils literal"><span class="pre">module_directory</span></code> argument to
  185. the template:</p>
  186. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  187. <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="s1">&#39;/docs/mytmpl.txt&#39;</span><span class="p">,</span> <span class="n">module_directory</span><span class="o">=</span><span class="s1">&#39;/tmp/mako_modules&#39;</span><span class="p">)</span>
  188. <span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  189. </pre></div>
  190. </div>
  191. <p>When the above code is rendered, a file
  192. <code class="docutils literal"><span class="pre">/tmp/mako_modules/docs/mytmpl.txt.py</span></code> is created containing the
  193. source code for the module. The next time a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> with the
  194. same arguments is created, this module file will be
  195. automatically re-used.</p>
  196. </div>
  197. <div class="section" id="using-templatelookup">
  198. <span id="usage-templatelookup"></span><h2>Using <code class="docutils literal"><span class="pre">TemplateLookup</span></code><a class="headerlink" href="#using-templatelookup" title="Permalink to this headline">¶</a></h2>
  199. <p>All of the examples thus far have dealt with the usage of a
  200. single <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object. If the code within those templates
  201. tries to locate another template resource, it will need some way
  202. to find them, using simple URI strings. For this need, the
  203. resolution of other templates from within a template is
  204. accomplished by the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> class. This class is
  205. constructed given a list of directories in which to search for
  206. templates, as well as keyword arguments that will be passed to
  207. the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> objects it creates:</p>
  208. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  209. <span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>
  210. <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="s1">&#39;/docs&#39;</span><span class="p">])</span>
  211. <span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;&quot;&quot;&lt;</span><span class="si">%i</span><span class="s2">nclude file=&quot;header.txt&quot;/&gt; hello world!&quot;&quot;&quot;</span><span class="p">,</span> <span class="n">lookup</span><span class="o">=</span><span class="n">mylookup</span><span class="p">)</span>
  212. </pre></div>
  213. </div>
  214. <p>Above, we created a textual template which includes the file
  215. <code class="docutils literal"><span class="pre">&quot;header.txt&quot;</span></code>. In order for it to have somewhere to look for
  216. <code class="docutils literal"><span class="pre">&quot;header.txt&quot;</span></code>, we passed a <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> object to it, which
  217. will search in the directory <code class="docutils literal"><span class="pre">/docs</span></code> for the file <code class="docutils literal"><span class="pre">&quot;header.txt&quot;</span></code>.</p>
  218. <p>Usually, an application will store most or all of its templates
  219. as text files on the filesystem. So far, all of our examples
  220. have been a little bit contrived in order to illustrate the
  221. basic concepts. But a real application would get most or all of
  222. its templates directly from the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>, using the
  223. aptly named <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><code class="xref py py-meth docutils literal"><span class="pre">get_template()</span></code></a> method, which accepts the URI of the
  224. desired template:</p>
  225. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  226. <span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>
  227. <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="s1">&#39;/docs&#39;</span><span class="p">],</span> <span class="n">module_directory</span><span class="o">=</span><span class="s1">&#39;/tmp/mako_modules&#39;</span><span class="p">)</span>
  228. <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>
  229. <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>
  230. <span class="k">print</span><span class="p">(</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>
  231. </pre></div>
  232. </div>
  233. <p>In the example above, we create a <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> which will
  234. look for templates in the <code class="docutils literal"><span class="pre">/docs</span></code> directory, and will store
  235. generated module files in the <code class="docutils literal"><span class="pre">/tmp/mako_modules</span></code> directory. The
  236. lookup locates templates by appending the given URI to each of
  237. its search directories; so if you gave it a URI of
  238. <code class="docutils literal"><span class="pre">/etc/beans/info.txt</span></code>, it would search for the file
  239. <code class="docutils literal"><span class="pre">/docs/etc/beans/info.txt</span></code>, else raise a <code class="xref py py-class docutils literal"><span class="pre">TopLevelNotFound</span></code>
  240. exception, which is a custom Mako exception.</p>
  241. <p>When the lookup locates templates, it will also assign a <code class="docutils literal"><span class="pre">uri</span></code>
  242. property to the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> which is the URI passed to the
  243. <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><code class="xref py py-meth docutils literal"><span class="pre">get_template()</span></code></a> call. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> uses this URI to calculate the
  244. name of its module file. So in the above example, a
  245. <code class="docutils literal"><span class="pre">templatename</span></code> argument of <code class="docutils literal"><span class="pre">/etc/beans/info.txt</span></code> will create a
  246. module file <code class="docutils literal"><span class="pre">/tmp/mako_modules/etc/beans/info.txt.py</span></code>.</p>
  247. <div class="section" id="setting-the-collection-size">
  248. <h3>Setting the Collection Size<a class="headerlink" href="#setting-the-collection-size" title="Permalink to this headline">¶</a></h3>
  249. <p>The <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> also serves the important need of caching a
  250. fixed set of templates in memory at a given time, so that
  251. successive URI lookups do not result in full template
  252. compilations and/or module reloads on each request. By default,
  253. the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> size is unbounded. You can specify a fixed
  254. size using the <code class="docutils literal"><span class="pre">collection_size</span></code> argument:</p>
  255. <div class="highlight-python"><div class="highlight"><pre><span></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="s1">&#39;/docs&#39;</span><span class="p">],</span>
  256. <span class="n">module_directory</span><span class="o">=</span><span class="s1">&#39;/tmp/mako_modules&#39;</span><span class="p">,</span> <span class="n">collection_size</span><span class="o">=</span><span class="mi">500</span><span class="p">)</span>
  257. </pre></div>
  258. </div>
  259. <p>The above lookup will continue to load templates into memory
  260. until it reaches a count of around 500. At that point, it will
  261. clean out a certain percentage of templates using a least
  262. recently used scheme.</p>
  263. </div>
  264. <div class="section" id="setting-filesystem-checks">
  265. <h3>Setting Filesystem Checks<a class="headerlink" href="#setting-filesystem-checks" title="Permalink to this headline">¶</a></h3>
  266. <p>Another important flag on <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> is
  267. <code class="docutils literal"><span class="pre">filesystem_checks</span></code>. This defaults to <code class="docutils literal"><span class="pre">True</span></code>, and says that each
  268. time a template is returned by the <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><code class="xref py py-meth docutils literal"><span class="pre">get_template()</span></code></a> method, the
  269. revision time of the original template file is checked against
  270. the last time the template was loaded, and if the file is newer
  271. will reload its contents and recompile the template. On a
  272. production system, setting <code class="docutils literal"><span class="pre">filesystem_checks</span></code> to <code class="docutils literal"><span class="pre">False</span></code> can
  273. afford a small to moderate performance increase (depending on
  274. the type of filesystem used).</p>
  275. </div>
  276. </div>
  277. <div class="section" id="using-unicode-and-encoding">
  278. <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>
  279. <p>Both <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> and <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> accept <code class="docutils literal"><span class="pre">output_encoding</span></code>
  280. and <code class="docutils literal"><span class="pre">encoding_errors</span></code> parameters which can be used to encode the
  281. output in any Python supported codec:</p>
  282. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  283. <span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>
  284. <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="s1">&#39;/docs&#39;</span><span class="p">],</span> <span class="n">output_encoding</span><span class="o">=</span><span class="s1">&#39;utf-8&#39;</span><span class="p">,</span> <span class="n">encoding_errors</span><span class="o">=</span><span class="s1">&#39;replace&#39;</span><span class="p">)</span>
  285. <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="s2">&quot;foo.txt&quot;</span><span class="p">)</span>
  286. <span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  287. </pre></div>
  288. </div>
  289. <p>When using Python 3, the <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> method will return a <code class="docutils literal"><span class="pre">bytes</span></code>
  290. object, <strong>if</strong> <code class="docutils literal"><span class="pre">output_encoding</span></code> is set. Otherwise it returns a
  291. <code class="docutils literal"><span class="pre">string</span></code>.</p>
  292. <p>Additionally, the <a class="reference internal" href="#mako.template.Template.render_unicode" title="mako.template.Template.render_unicode"><code class="xref py py-meth docutils literal"><span class="pre">render_unicode()</span></code></a> method exists which will
  293. return the template output as a Python <code class="docutils literal"><span class="pre">unicode</span></code> object, or in
  294. Python 3 a <code class="docutils literal"><span class="pre">string</span></code>:</p>
  295. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">print</span><span class="p">(</span><span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">())</span>
  296. </pre></div>
  297. </div>
  298. <p>The above method disregards the output encoding keyword
  299. argument; you can encode yourself by saying:</p>
  300. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">print</span><span class="p">(</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="s1">&#39;utf-8&#39;</span><span class="p">,</span> <span class="s1">&#39;replace&#39;</span><span class="p">))</span>
  301. </pre></div>
  302. </div>
  303. <p>Note that Mako&#8217;s ability to return data in any encoding and/or
  304. <code class="docutils literal"><span class="pre">unicode</span></code> implies that the underlying output stream of the
  305. template is a Python unicode object. This behavior is described
  306. fully in <a class="reference internal" href="unicode.html"><span class="std std-ref">The Unicode Chapter</span></a>.</p>
  307. </div>
  308. <div class="section" id="handling-exceptions">
  309. <span id="id1"></span><h2>Handling Exceptions<a class="headerlink" href="#handling-exceptions" title="Permalink to this headline">¶</a></h2>
  310. <p>Template exceptions can occur in two distinct places. One is
  311. when you <strong>lookup, parse and compile</strong> the template, the other
  312. is when you <strong>run</strong> the template. Within the running of a
  313. template, exceptions are thrown normally from whatever Python
  314. code originated the issue. Mako has its own set of exception
  315. classes which mostly apply to the lookup and lexer/compiler
  316. stages of template construction. Mako provides some library
  317. routines that can be used to help provide Mako-specific
  318. information about any exception&#8217;s stack trace, as well as
  319. formatting the exception within textual or HTML format. In all
  320. cases, the main value of these handlers is that of converting
  321. Python filenames, line numbers, and code samples into Mako
  322. template filenames, line numbers, and code samples. All lines
  323. within a stack trace which correspond to a Mako template module
  324. will be converted to be against the originating template file.</p>
  325. <p>To format exception traces, the <a class="reference internal" href="#mako.exceptions.text_error_template" title="mako.exceptions.text_error_template"><code class="xref py py-func docutils literal"><span class="pre">text_error_template()</span></code></a> and
  326. <a class="reference internal" href="#mako.exceptions.html_error_template" title="mako.exceptions.html_error_template"><code class="xref py py-func docutils literal"><span class="pre">html_error_template()</span></code></a> functions are provided. They make usage of
  327. <code class="docutils literal"><span class="pre">sys.exc_info()</span></code> to get at the most recently thrown exception.
  328. Usage of these handlers usually looks like:</p>
  329. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako</span> <span class="kn">import</span> <span class="n">exceptions</span>
  330. <span class="k">try</span><span class="p">:</span>
  331. <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>
  332. <span class="k">print</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  333. <span class="k">except</span><span class="p">:</span>
  334. <span class="k">print</span><span class="p">(</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>
  335. </pre></div>
  336. </div>
  337. <p>Or for the HTML render function:</p>
  338. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako</span> <span class="kn">import</span> <span class="n">exceptions</span>
  339. <span class="k">try</span><span class="p">:</span>
  340. <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>
  341. <span class="k">print</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  342. <span class="k">except</span><span class="p">:</span>
  343. <span class="k">print</span><span class="p">(</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>
  344. </pre></div>
  345. </div>
  346. <p>The <a class="reference internal" href="#mako.exceptions.html_error_template" title="mako.exceptions.html_error_template"><code class="xref py py-func docutils literal"><span class="pre">html_error_template()</span></code></a> template accepts two options:
  347. specifying <code class="docutils literal"><span class="pre">full=False</span></code> causes only a section of an HTML
  348. document to be rendered. Specifying <code class="docutils literal"><span class="pre">css=False</span></code> will disable the
  349. default stylesheet from being rendered.</p>
  350. <p>E.g.:</p>
  351. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">print</span><span class="p">(</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>
  352. </pre></div>
  353. </div>
  354. <p>The HTML render function is also available built-in to
  355. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> using the <code class="docutils literal"><span class="pre">format_exceptions</span></code> flag. In this case, any
  356. exceptions raised within the <strong>render</strong> stage of the template
  357. will result in the output being substituted with the output of
  358. <a class="reference internal" href="#mako.exceptions.html_error_template" title="mako.exceptions.html_error_template"><code class="xref py py-func docutils literal"><span class="pre">html_error_template()</span></code></a>:</p>
  359. <div class="highlight-python"><div class="highlight"><pre><span></span><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="s2">&quot;/foo/bar&quot;</span><span class="p">,</span> <span class="n">format_exceptions</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
  360. <span class="k">print</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  361. </pre></div>
  362. </div>
  363. <p>Note that the compile stage of the above template occurs when
  364. you construct the <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> itself, and no output stream is
  365. defined. Therefore exceptions which occur within the
  366. lookup/parse/compile stage will not be handled and will
  367. propagate normally. While the pre-render traceback usually will
  368. not include any Mako-specific lines anyway, it will mean that
  369. exceptions which occur previous to rendering and those which
  370. occur within rendering will be handled differently... so the
  371. <code class="docutils literal"><span class="pre">try</span></code>/<code class="docutils literal"><span class="pre">except</span></code> patterns described previously are probably of more
  372. general use.</p>
  373. <p>The underlying object used by the error template functions is
  374. the <a class="reference internal" href="#mako.exceptions.RichTraceback" title="mako.exceptions.RichTraceback"><code class="xref py py-class docutils literal"><span class="pre">RichTraceback</span></code></a> object. This object can also be used
  375. directly to provide custom error views. Here&#8217;s an example usage
  376. which describes its general API:</p>
  377. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.exceptions</span> <span class="kn">import</span> <span class="n">RichTraceback</span>
  378. <span class="k">try</span><span class="p">:</span>
  379. <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>
  380. <span class="k">print</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">())</span>
  381. <span class="k">except</span><span class="p">:</span>
  382. <span class="n">traceback</span> <span class="o">=</span> <span class="n">RichTraceback</span><span class="p">()</span>
  383. <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>
  384. <span class="k">print</span><span class="p">(</span><span class="s2">&quot;File </span><span class="si">%s</span><span class="s2">, line </span><span class="si">%s</span><span class="s2">, in </span><span class="si">%s</span><span class="s2">&quot;</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>
  385. <span class="k">print</span><span class="p">(</span><span class="n">line</span><span class="p">,</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
  386. <span class="k">print</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">%s</span><span class="s2">: </span><span class="si">%s</span><span class="s2">&quot;</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="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="p">),</span> <span class="n">traceback</span><span class="o">.</span><span class="n">error</span><span class="p">))</span>
  387. </pre></div>
  388. </div>
  389. </div>
  390. <div class="section" id="common-framework-integrations">
  391. <h2>Common Framework Integrations<a class="headerlink" href="#common-framework-integrations" title="Permalink to this headline">¶</a></h2>
  392. <p>The Mako distribution includes a little bit of helper code for
  393. the purpose of using Mako in some popular web framework
  394. scenarios. This is a brief description of what&#8217;s included.</p>
  395. <div class="section" id="wsgi">
  396. <h3>WSGI<a class="headerlink" href="#wsgi" title="Permalink to this headline">¶</a></h3>
  397. <p>A sample WSGI application is included in the distribution in the
  398. file <code class="docutils literal"><span class="pre">examples/wsgi/run_wsgi.py</span></code>. This runner is set up to pull
  399. files from a <cite>templates</cite> as well as an <cite>htdocs</cite> directory and
  400. includes a rudimental two-file layout. The WSGI runner acts as a
  401. fully functional standalone web server, using <code class="docutils literal"><span class="pre">wsgiutils</span></code> to run
  402. itself, and propagates GET and POST arguments from the request
  403. into the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>, can serve images, CSS files and other kinds
  404. of files, and also displays errors using Mako&#8217;s included
  405. exception-handling utilities.</p>
  406. </div>
  407. <div class="section" id="pygments">
  408. <h3>Pygments<a class="headerlink" href="#pygments" title="Permalink to this headline">¶</a></h3>
  409. <p>A <a class="reference external" href="http://pygments.pocoo.org">Pygments</a>-compatible syntax
  410. highlighting module is included under <code class="xref py py-mod docutils literal"><span class="pre">mako.ext.pygmentplugin</span></code>.
  411. This module is used in the generation of Mako documentation and
  412. also contains various <cite>setuptools</cite> entry points under the heading
  413. <code class="docutils literal"><span class="pre">pygments.lexers</span></code>, including <code class="docutils literal"><span class="pre">mako</span></code>, <code class="docutils literal"><span class="pre">html+mako</span></code>, <code class="docutils literal"><span class="pre">xml+mako</span></code>
  414. (see the <code class="docutils literal"><span class="pre">setup.py</span></code> file for all the entry points).</p>
  415. </div>
  416. <div class="section" id="babel">
  417. <h3>Babel<a class="headerlink" href="#babel" title="Permalink to this headline">¶</a></h3>
  418. <p>Mako provides support for extracting <cite>gettext</cite> messages from
  419. templates via a <a class="reference external" href="http://babel.edgewall.org/">Babel</a> extractor
  420. entry point under <code class="docutils literal"><span class="pre">mako.ext.babelplugin</span></code>.</p>
  421. <p><cite>Gettext</cite> messages are extracted from all Python code sections,
  422. including those of control lines and expressions embedded
  423. in tags.</p>
  424. <p><a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/messages.html#comments-tags-and-translator-comments-explanation">Translator
  425. comments</a>
  426. may also be extracted from Mako templates when a comment tag is
  427. specified to <a class="reference external" href="http://babel.edgewall.org/">Babel</a> (such as with
  428. the <code class="docutils literal"><span class="pre">-c</span></code> option).</p>
  429. <p>For example, a project <code class="docutils literal"><span class="pre">&quot;myproj&quot;</span></code> contains the following Mako
  430. template at <code class="docutils literal"><span class="pre">myproj/myproj/templates/name.html</span></code>:</p>
  431. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;div id=&quot;name&quot;&gt;</span>
  432. <span class="x"> Name:</span>
  433. <span class="x"> ## TRANSLATORS: This is a proper name. See the gettext</span>
  434. <span class="x"> ## manual, section Names.</span>
  435. <span class="x"> </span><span class="cp">${</span><span class="n">_</span><span class="p">(</span><span class="s1">&#39;Francois Pinard&#39;</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  436. <span class="x">&lt;/div&gt;</span>
  437. </pre></div>
  438. </div>
  439. <p>To extract gettext messages from this template the project needs
  440. 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
  441. file</a>
  442. (typically located at <code class="docutils literal"><span class="pre">myproj/babel.cfg</span></code>):</p>
  443. <div class="highlight-cfg"><div class="highlight"><pre><span></span><span class="c1"># Extraction from Python source files</span>
  444. <span class="k">[python: myproj/**.py]</span>
  445. <span class="c1"># Extraction from Mako templates</span>
  446. <span class="k">[mako: myproj/templates/**.html]</span>
  447. <span class="na">input_encoding</span> <span class="o">=</span> <span class="s">utf-8</span>
  448. </pre></div>
  449. </div>
  450. <p>The Mako extractor supports an optional <code class="docutils literal"><span class="pre">input_encoding</span></code>
  451. parameter specifying the encoding of the templates (identical to
  452. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>/<a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>&#8216;s <code class="docutils literal"><span class="pre">input_encoding</span></code> parameter).</p>
  453. <p>Invoking <a class="reference external" href="http://babel.edgewall.org/">Babel</a>&#8216;s extractor at the
  454. command line in the project&#8217;s root directory:</p>
  455. <div class="highlight-sh"><div class="highlight"><pre><span></span>myproj$ pybabel extract -F babel.cfg -c <span class="s2">&quot;TRANSLATORS:&quot;</span> .
  456. </pre></div>
  457. </div>
  458. <p>will output a <cite>gettext</cite> catalog to <cite>stdout</cite> including the following:</p>
  459. <div class="highlight-pot"><div class="highlight"><pre><span></span><span class="c1">#. TRANSLATORS: This is a proper name. See the gettext</span>
  460. <span class="c1">#. manual, section Names.</span>
  461. <span class="kd">#: myproj/templates/name.html:5</span>
  462. <span class="nv">msgid</span> <span class="s">&quot;Francois Pinard&quot;</span>
  463. <span class="nv">msgstr</span> <span class="s">&quot;&quot;</span>
  464. </pre></div>
  465. </div>
  466. <p>This is only a basic example:
  467. <a class="reference external" href="http://babel.edgewall.org/">Babel</a> can be invoked from <code class="docutils literal"><span class="pre">setup.py</span></code>
  468. and its command line options specified in the accompanying
  469. <code class="docutils literal"><span class="pre">setup.cfg</span></code> via <a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/setup.html">Babel Distutils/Setuptools
  470. Integration</a>.</p>
  471. <p>Comments must immediately precede a <cite>gettext</cite> message to be
  472. extracted. In the following case the <code class="docutils literal"><span class="pre">TRANSLATORS:</span></code> comment would
  473. not have been extracted:</p>
  474. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;div id=&quot;name&quot;&gt;</span>
  475. <span class="x"> ## TRANSLATORS: This is a proper name. See the gettext</span>
  476. <span class="x"> ## manual, section Names.</span>
  477. <span class="x"> Name: </span><span class="cp">${</span><span class="n">_</span><span class="p">(</span><span class="s1">&#39;Francois Pinard&#39;</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  478. <span class="x">&lt;/div&gt;</span>
  479. </pre></div>
  480. </div>
  481. <p>See the <a class="reference external" href="http://babel.edgewall.org/wiki/Documentation/index.html">Babel User
  482. Guide</a>
  483. for more information.</p>
  484. </div>
  485. </div>
  486. <div class="section" id="api-reference">
  487. <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
  488. <dl class="class">
  489. <dt id="mako.template.Template">
  490. <em class="property">class </em><code class="descclassname">mako.template.</code><code class="descname">Template</code><span class="sig-paren">(</span><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>, <em>include_error_handler=None</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.Template" title="Permalink to this definition">¶</a></dt>
  491. <dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
  492. <p>Represents a compiled template.</p>
  493. <p><a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> includes a reference to the original
  494. template source (via the <a class="reference internal" href="#RichTraceback.source" title="RichTraceback.source"><code class="xref py py-attr docutils literal"><span class="pre">source</span></code></a> attribute)
  495. as well as the source code of the
  496. generated Python module (i.e. the <a class="reference internal" href="#mako.template.Template.code" title="mako.template.Template.code"><code class="xref py py-attr docutils literal"><span class="pre">code</span></code></a> attribute),
  497. as well as a reference to an actual Python module.</p>
  498. <p><a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> is constructed using either a literal string
  499. representing the template text, or a filename representing a filesystem
  500. path to a source file.</p>
  501. <table class="docutils field-list" frame="void" rules="none">
  502. <col class="field-name" />
  503. <col class="field-body" />
  504. <tbody valign="top">
  505. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  506. <li><span class="target" id="mako.template.Template.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.text">¶</a> &#8211; textual template source. This argument is mutually
  507. exclusive versus the <code class="docutils literal"><span class="pre">filename</span></code> parameter.</li>
  508. <li><span class="target" id="mako.template.Template.params.filename"></span><strong>filename</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.filename">¶</a> &#8211; filename of the source template. This argument is
  509. mutually exclusive versus the <code class="docutils literal"><span class="pre">text</span></code> parameter.</li>
  510. <li><span class="target" id="mako.template.Template.params.buffer_filters"></span><strong>buffer_filters</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.buffer_filters">¶</a> &#8211; string list of filters to be applied
  511. to the output of <code class="docutils literal"><span class="pre">%def</span></code>s which are buffered, cached, or otherwise
  512. filtered, after all filters
  513. defined with the <code class="docutils literal"><span class="pre">%def</span></code> itself have been applied. Allows the
  514. creation of default expression filters that let the output
  515. of return-valued <code class="docutils literal"><span class="pre">%def</span></code>s &#8220;opt out&#8221; of that filtering via
  516. passing special attributes or objects.</li>
  517. <li><span class="target" id="mako.template.Template.params.bytestring_passthrough"></span><strong>bytestring_passthrough</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.bytestring_passthrough">¶</a> &#8211; <p>When <code class="docutils literal"><span class="pre">True</span></code>, and <code class="docutils literal"><span class="pre">output_encoding</span></code> is
  518. set to <code class="docutils literal"><span class="pre">None</span></code>, and <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">Template.render()</span></code></a> is used to render,
  519. the <cite>StringIO</cite> or <cite>cStringIO</cite> buffer will be used instead of the
  520. default &#8220;fast&#8221; buffer. This allows raw bytestrings in the
  521. output stream, such as in expressions, to pass straight
  522. through to the buffer. This flag is forced
  523. to <code class="docutils literal"><span class="pre">True</span></code> if <code class="docutils literal"><span class="pre">disable_unicode</span></code> is also configured.</p>
  524. <div class="versionadded">
  525. <p><span class="versionmodified">New in version 0.4: </span>Added to provide the same behavior as that of the previous series.</p>
  526. </div>
  527. </li>
  528. <li><span class="target" id="mako.template.Template.params.cache_args"></span><strong>cache_args</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.cache_args">¶</a> &#8211; Dictionary of cache configuration arguments that
  529. will be passed to the <a class="reference internal" href="caching.html#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><code class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></code></a>. See <a class="reference internal" href="caching.html"><span class="std std-ref">Caching</span></a>.</li>
  530. <li><span class="target" id="mako.template.Template.params.cache_dir"></span><strong>cache_dir</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.cache_dir">¶</a> &#8211; <div class="deprecated">
  531. <p><span class="versionmodified">Deprecated since version 0.6: </span>Use the <code class="docutils literal"><span class="pre">'dir'</span></code> argument in the <code class="docutils literal"><span class="pre">cache_args</span></code> dictionary.
  532. See <a class="reference internal" href="caching.html"><span class="std std-ref">Caching</span></a>.</p>
  533. </div>
  534. </li>
  535. <li><span class="target" id="mako.template.Template.params.cache_enabled"></span><strong>cache_enabled</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.cache_enabled">¶</a> &#8211; Boolean flag which enables caching of this
  536. template. See <a class="reference internal" href="caching.html"><span class="std std-ref">Caching</span></a>.</li>
  537. <li><span class="target" id="mako.template.Template.params.cache_impl"></span><strong>cache_impl</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.cache_impl">¶</a> &#8211; String name of a <a class="reference internal" href="caching.html#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><code class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></code></a> caching
  538. implementation to use. Defaults to <code class="docutils literal"><span class="pre">'beaker'</span></code>.</li>
  539. <li><span class="target" id="mako.template.Template.params.cache_type"></span><strong>cache_type</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.cache_type">¶</a> &#8211; <div class="deprecated">
  540. <p><span class="versionmodified">Deprecated since version 0.6: </span>Use the <code class="docutils literal"><span class="pre">'type'</span></code> argument in the <code class="docutils literal"><span class="pre">cache_args</span></code> dictionary.
  541. See <a class="reference internal" href="caching.html"><span class="std std-ref">Caching</span></a>.</p>
  542. </div>
  543. </li>
  544. <li><span class="target" id="mako.template.Template.params.cache_url"></span><strong>cache_url</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.cache_url">¶</a> &#8211; <div class="deprecated">
  545. <p><span class="versionmodified">Deprecated since version 0.6: </span>Use the <code class="docutils literal"><span class="pre">'url'</span></code> argument in the <code class="docutils literal"><span class="pre">cache_args</span></code> dictionary.
  546. See <a class="reference internal" href="caching.html"><span class="std std-ref">Caching</span></a>.</p>
  547. </div>
  548. </li>
  549. <li><span class="target" id="mako.template.Template.params.default_filters"></span><strong>default_filters</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.default_filters">¶</a> &#8211; List of string filter names that will
  550. be applied to all expressions. See <a class="reference internal" href="filtering.html#filtering-default-filters"><span class="std std-ref">The default_filters Argument</span></a>.</li>
  551. <li><span class="target" id="mako.template.Template.params.disable_unicode"></span><strong>disable_unicode</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.disable_unicode">¶</a> &#8211; Disables all awareness of Python Unicode
  552. objects. See <a class="reference internal" href="unicode.html#unicode-disabled"><span class="std std-ref">Saying to Heck with It: Disabling the Usage of Unicode Entirely</span></a>.</li>
  553. <li><span class="target" id="mako.template.Template.params.enable_loop"></span><strong>enable_loop</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.enable_loop">¶</a> &#8211; When <code class="docutils literal"><span class="pre">True</span></code>, enable the <code class="docutils literal"><span class="pre">loop</span></code> context variable.
  554. This can be set to <code class="docutils literal"><span class="pre">False</span></code> to support templates that may
  555. be making usage of the name &#8220;<code class="docutils literal"><span class="pre">loop</span></code>&#8221;. Individual templates can
  556. re-enable the &#8220;loop&#8221; context by placing the directive
  557. <code class="docutils literal"><span class="pre">enable_loop=&quot;True&quot;</span></code> inside the <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag &#8211; see
  558. <a class="reference internal" href="runtime.html#migrating-loop"><span class="std std-ref">Migrating Legacy Templates that Use the Word &#8220;loop&#8221;</span></a>.</li>
  559. <li><span class="target" id="mako.template.Template.params.encoding_errors"></span><strong>encoding_errors</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.encoding_errors">¶</a> &#8211; Error parameter passed to <code class="docutils literal"><span class="pre">encode()</span></code> when
  560. string encoding is performed. See <a class="reference internal" href="#usage-unicode"><span class="std std-ref">Using Unicode and Encoding</span></a>.</li>
  561. <li><span class="target" id="mako.template.Template.params.error_handler"></span><strong>error_handler</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.error_handler">¶</a> &#8211; <p>Python callable which is called whenever
  562. compile or runtime exceptions occur. The callable is passed
  563. the current context as well as the exception. If the
  564. callable returns <code class="docutils literal"><span class="pre">True</span></code>, the exception is considered to
  565. be handled, else it is re-raised after the function
  566. completes. Is used to provide custom error-rendering
  567. functions.</p>
  568. <div class="admonition seealso">
  569. <p class="first admonition-title">See also</p>
  570. <p class="last"><a class="reference internal" href="#mako.template.Template.params.include_error_handler" title="mako.template.Template"><code class="xref py py-paramref docutils literal"><span class="pre">Template.include_error_handler</span></code></a> - include-specific
  571. error handler function</p>
  572. </div>
  573. </li>
  574. <li><span class="target" id="mako.template.Template.params.format_exceptions"></span><strong>format_exceptions</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.format_exceptions">¶</a> &#8211; if <code class="docutils literal"><span class="pre">True</span></code>, exceptions which occur during
  575. the render phase of this template will be caught and
  576. formatted into an HTML error page, which then becomes the
  577. rendered result of the <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> call. Otherwise,
  578. runtime exceptions are propagated outwards.</li>
  579. <li><span class="target" id="mako.template.Template.params.imports"></span><strong>imports</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.imports">¶</a> &#8211; String list of Python statements, typically individual
  580. &#8220;import&#8221; lines, which will be placed into the module level
  581. preamble of all generated Python modules. See the example
  582. in <a class="reference internal" href="filtering.html#filtering-default-filters"><span class="std std-ref">The default_filters Argument</span></a>.</li>
  583. <li><span class="target" id="mako.template.Template.params.future_imports"></span><strong>future_imports</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.future_imports">¶</a> &#8211; String list of names to import from <cite>__future__</cite>.
  584. These will be concatenated into a comma-separated string and inserted
  585. into the beginning of the template, e.g. <code class="docutils literal"><span class="pre">futures_imports=['FOO',</span>
  586. <span class="pre">'BAR']</span></code> results in <code 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></code>. If you&#8217;re
  587. interested in using features like the new division operator, you must
  588. use future_imports to convey that to the renderer, as otherwise the
  589. import will not appear as the first executed statement in the generated
  590. code and will therefore not have the desired effect.</li>
  591. <li><span class="target" id="mako.template.Template.params.include_error_handler"></span><strong>include_error_handler</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.include_error_handler">¶</a> &#8211; <p>An error handler that runs when this template
  592. is included within another one via the <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> tag, and raises an
  593. error. Compare to the <a class="reference internal" href="#mako.template.Template.params.error_handler" title="mako.template.Template"><code class="xref py py-paramref docutils literal"><span class="pre">Template.error_handler</span></code></a> option.</p>
  594. <div class="versionadded">
  595. <p><span class="versionmodified">New in version 1.0.6.</span></p>
  596. </div>
  597. <div class="admonition seealso">
  598. <p class="first admonition-title">See also</p>
  599. <p class="last"><a class="reference internal" href="#mako.template.Template.params.error_handler" title="mako.template.Template"><code class="xref py py-paramref docutils literal"><span class="pre">Template.error_handler</span></code></a> - top-level error handler function</p>
  600. </div>
  601. </li>
  602. <li><span class="target" id="mako.template.Template.params.input_encoding"></span><strong>input_encoding</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.input_encoding">¶</a> &#8211; Encoding of the template&#8217;s source code. Can
  603. be used in lieu of the coding comment. See
  604. <a class="reference internal" href="#usage-unicode"><span class="std std-ref">Using Unicode and Encoding</span></a> as well as <a class="reference internal" href="unicode.html"><span class="std std-ref">The Unicode Chapter</span></a> for
  605. details on source encoding.</li>
  606. <li><span class="target" id="mako.template.Template.params.lookup"></span><strong>lookup</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.lookup">¶</a> &#8211; a <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> instance that will be used
  607. for all file lookups via the <code class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></code>,
  608. <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code>, and <code class="docutils literal"><span class="pre">&lt;%inherit&gt;</span></code> tags. See
  609. <a class="reference internal" href="#usage-templatelookup"><span class="std std-ref">Using TemplateLookup</span></a>.</li>
  610. <li><span class="target" id="mako.template.Template.params.module_directory"></span><strong>module_directory</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.module_directory">¶</a> &#8211; Filesystem location where generated
  611. Python module files will be placed.</li>
  612. <li><span class="target" id="mako.template.Template.params.module_filename"></span><strong>module_filename</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.module_filename">¶</a> &#8211; Overrides the filename of the generated
  613. Python module file. For advanced usage only.</li>
  614. <li><span class="target" id="mako.template.Template.params.module_writer"></span><strong>module_writer</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.module_writer">¶</a> &#8211; <p>A callable which overrides how the Python
  615. module is written entirely. The callable is passed the
  616. encoded source content of the module and the destination
  617. path to be written to. The default behavior of module writing
  618. uses a tempfile in conjunction with a file move in order
  619. to make the operation atomic. So a user-defined module
  620. writing function that mimics the default behavior would be:</p>
  621. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tempfile</span>
  622. <span class="kn">import</span> <span class="nn">os</span>
  623. <span class="kn">import</span> <span class="nn">shutil</span>
  624. <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>
  625. <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> \\
  626. <span class="n">tempfile</span><span class="o">.</span><span class="n">mkstemp</span><span class="p">(</span>
  627. <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>
  628. <span class="p">)</span>
  629. <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>
  630. <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>
  631. <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>
  632. <span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  633. <span class="n">mytemplate</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span>
  634. <span class="n">filename</span><span class="o">=</span><span class="s2">&quot;index.html&quot;</span><span class="p">,</span>
  635. <span class="n">module_directory</span><span class="o">=</span><span class="s2">&quot;/path/to/modules&quot;</span><span class="p">,</span>
  636. <span class="n">module_writer</span><span class="o">=</span><span class="n">module_writer</span>
  637. <span class="p">)</span>
  638. </pre></div>
  639. </div>
  640. <p>The function is provided for unusual configurations where
  641. certain platform-specific permissions or other special
  642. steps are needed.</p>
  643. </li>
  644. <li><span class="target" id="mako.template.Template.params.output_encoding"></span><strong>output_encoding</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.output_encoding">¶</a> &#8211; The encoding to use when <a class="reference internal" href="#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a>
  645. is called.
  646. See <a class="reference internal" href="#usage-unicode"><span class="std std-ref">Using Unicode and Encoding</span></a> as well as <a class="reference internal" href="unicode.html"><span class="std std-ref">The Unicode Chapter</span></a>.</li>
  647. <li><span class="target" id="mako.template.Template.params.preprocessor"></span><strong>preprocessor</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.preprocessor">¶</a> &#8211; Python callable which will be passed
  648. the full template source before it is parsed. The return
  649. result of the callable will be used as the template source
  650. code.</li>
  651. <li><span class="target" id="mako.template.Template.params.lexer_cls"></span><strong>lexer_cls</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.lexer_cls">¶</a> &#8211; <p>A <code class="xref py py-class docutils literal"><span class="pre">Lexer</span></code> class used to parse
  652. the template. The <code class="xref py py-class docutils literal"><span class="pre">Lexer</span></code> class is used by
  653. default.</p>
  654. <div class="versionadded">
  655. <p><span class="versionmodified">New in version 0.7.4.</span></p>
  656. </div>
  657. </li>
  658. <li><span class="target" id="mako.template.Template.params.strict_undefined"></span><strong>strict_undefined</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.strict_undefined">¶</a> &#8211; <p>Replaces the automatic usage of
  659. <code class="docutils literal"><span class="pre">UNDEFINED</span></code> for any undeclared variables not located in
  660. the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> with an immediate raise of
  661. <code class="docutils literal"><span class="pre">NameError</span></code>. The advantage is immediate reporting of
  662. missing variables which include the name.</p>
  663. <div class="versionadded">
  664. <p><span class="versionmodified">New in version 0.3.6.</span></p>
  665. </div>
  666. </li>
  667. <li><span class="target" id="mako.template.Template.params.uri"></span><strong>uri</strong><a class="paramlink headerlink reference internal" href="#mako.template.Template.params.uri">¶</a> &#8211; string URI or other identifier for this template.
  668. If not provided, the <code class="docutils literal"><span class="pre">uri</span></code> is generated from the filesystem
  669. path, or from the in-memory identity of a non-file-based
  670. template. The primary usage of the <code class="docutils literal"><span class="pre">uri</span></code> is to provide a key
  671. within <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>, as well as to generate the
  672. file path of the generated Python module file, if
  673. <code class="docutils literal"><span class="pre">module_directory</span></code> is specified.</li>
  674. </ul>
  675. </td>
  676. </tr>
  677. </tbody>
  678. </table>
  679. <dl class="attribute">
  680. <dt id="mako.template.Template.code">
  681. <code class="descname">code</code><a class="headerlink" href="#mako.template.Template.code" title="Permalink to this definition">¶</a></dt>
  682. <dd><p>Return the module source code for this <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>.</p>
  683. </dd></dl>
  684. <dl class="method">
  685. <dt id="mako.template.Template.get_def">
  686. <code class="descname">get_def</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.Template.get_def" title="Permalink to this definition">¶</a></dt>
  687. <dd><p>Return a def of this template as a <a class="reference internal" href="#mako.template.DefTemplate" title="mako.template.DefTemplate"><code class="xref py py-class docutils literal"><span class="pre">DefTemplate</span></code></a>.</p>
  688. </dd></dl>
  689. <dl class="method">
  690. <dt id="mako.template.Template.list_defs">
  691. <code class="descname">list_defs</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.Template.list_defs" title="Permalink to this definition">¶</a></dt>
  692. <dd><p>return a list of defs in the template.</p>
  693. <div class="versionadded">
  694. <p><span class="versionmodified">New in version 1.0.4.</span></p>
  695. </div>
  696. </dd></dl>
  697. <dl class="method">
  698. <dt id="mako.template.Template.render">
  699. <code class="descname">render</code><span class="sig-paren">(</span><em>*args</em>, <em>**data</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.Template.render" title="Permalink to this definition">¶</a></dt>
  700. <dd><p>Render the output of this template as a string.</p>
  701. <p>If the template specifies an output encoding, the string
  702. will be encoded accordingly, else the output is raw (raw
  703. output uses <cite>cStringIO</cite> and can&#8217;t handle multibyte
  704. characters). A <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object is created corresponding
  705. to the given data. Arguments that are explicitly declared
  706. by this template&#8217;s internal rendering method are also
  707. pulled from the given <code class="docutils literal"><span class="pre">*args</span></code>, <code class="docutils literal"><span class="pre">**data</span></code> members.</p>
  708. </dd></dl>
  709. <dl class="method">
  710. <dt id="mako.template.Template.render_context">
  711. <code class="descname">render_context</code><span class="sig-paren">(</span><em>context</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.Template.render_context" title="Permalink to this definition">¶</a></dt>
  712. <dd><p>Render this <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> with the given context.</p>
  713. <p>The data is written to the context&#8217;s buffer.</p>
  714. </dd></dl>
  715. <dl class="method">
  716. <dt id="mako.template.Template.render_unicode">
  717. <code class="descname">render_unicode</code><span class="sig-paren">(</span><em>*args</em>, <em>**data</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.Template.render_unicode" title="Permalink to this definition">¶</a></dt>
  718. <dd><p>Render the output of this template as a unicode object.</p>
  719. </dd></dl>
  720. <dl class="attribute">
  721. <dt id="mako.template.Template.source">
  722. <code class="descname">source</code><a class="headerlink" href="#mako.template.Template.source" title="Permalink to this definition">¶</a></dt>
  723. <dd><p>Return the template source code for this <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>.</p>
  724. </dd></dl>
  725. </dd></dl>
  726. <dl class="class">
  727. <dt id="mako.template.DefTemplate">
  728. <em class="property">class </em><code class="descclassname">mako.template.</code><code class="descname">DefTemplate</code><span class="sig-paren">(</span><em>parent</em>, <em>callable_</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.template.DefTemplate" title="Permalink to this definition">¶</a></dt>
  729. <dd><p>Bases: <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">mako.template.Template</span></code></a></p>
  730. <p>A <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> which represents a callable def in a parent
  731. template.</p>
  732. </dd></dl>
  733. <dl class="class">
  734. <dt id="mako.lookup.TemplateCollection">
  735. <em class="property">class </em><code class="descclassname">mako.lookup.</code><code class="descname">TemplateCollection</code><a class="headerlink" href="#mako.lookup.TemplateCollection" title="Permalink to this definition">¶</a></dt>
  736. <dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
  737. <p>Represent a collection of <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> objects,
  738. identifiable via URI.</p>
  739. <p>A <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></code></a> is linked to the usage of
  740. all template tags that address other templates, such
  741. as <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code>, <code class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></code>, and <code class="docutils literal"><span class="pre">&lt;%inherit&gt;</span></code>.
  742. The <code class="docutils literal"><span class="pre">file</span></code> attribute of each of those tags refers
  743. to a string URI that is passed to that <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>
  744. object&#8217;s <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></code></a> for resolution.</p>
  745. <p><a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></code></a> is an abstract class,
  746. with the usual default implementation being <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>.</p>
  747. <dl class="method">
  748. <dt id="mako.lookup.TemplateCollection.adjust_uri">
  749. <code class="descname">adjust_uri</code><span class="sig-paren">(</span><em>uri</em>, <em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateCollection.adjust_uri" title="Permalink to this definition">¶</a></dt>
  750. <dd><p>Adjust the given <code class="docutils literal"><span class="pre">uri</span></code> based on the calling <code class="docutils literal"><span class="pre">filename</span></code>.</p>
  751. <p>When this method is called from the runtime, the
  752. <code class="docutils literal"><span class="pre">filename</span></code> parameter is taken directly to the <code class="docutils literal"><span class="pre">filename</span></code>
  753. attribute of the calling template. Therefore a custom
  754. <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></code></a> subclass can place any string
  755. identifier desired in the <code class="docutils literal"><span class="pre">filename</span></code> parameter of the
  756. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> objects it constructs and have them come back
  757. here.</p>
  758. </dd></dl>
  759. <dl class="method">
  760. <dt id="mako.lookup.TemplateCollection.filename_to_uri">
  761. <code class="descname">filename_to_uri</code><span class="sig-paren">(</span><em>uri</em>, <em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateCollection.filename_to_uri" title="Permalink to this definition">¶</a></dt>
  762. <dd><p>Convert the given <code class="docutils literal"><span class="pre">filename</span></code> to a URI relative to
  763. this <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></code></a>.</p>
  764. </dd></dl>
  765. <dl class="method">
  766. <dt id="mako.lookup.TemplateCollection.get_template">
  767. <code class="descname">get_template</code><span class="sig-paren">(</span><em>uri</em>, <em>relativeto=None</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateCollection.get_template" title="Permalink to this definition">¶</a></dt>
  768. <dd><p>Return a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object corresponding to the given
  769. <code class="docutils literal"><span class="pre">uri</span></code>.</p>
  770. <p>The default implementation raises
  771. <code class="xref py py-class docutils literal"><span class="pre">NotImplementedError</span></code>. Implementations should
  772. raise <code class="xref py py-class docutils literal"><span class="pre">TemplateLookupException</span></code> if the given <code class="docutils literal"><span class="pre">uri</span></code>
  773. cannot be resolved.</p>
  774. <table class="docutils field-list" frame="void" rules="none">
  775. <col class="field-name" />
  776. <col class="field-body" />
  777. <tbody valign="top">
  778. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  779. <li><span class="target" id="mako.lookup.TemplateCollection.get_template.params.uri"></span><strong>uri</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateCollection.get_template.params.uri">¶</a> &#8211; String URI of the template to be resolved.</li>
  780. <li><span class="target" id="mako.lookup.TemplateCollection.get_template.params.relativeto"></span><strong>relativeto</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateCollection.get_template.params.relativeto">¶</a> &#8211; if present, the given <code class="docutils literal"><span class="pre">uri</span></code> is assumed to
  781. be relative to this URI.</li>
  782. </ul>
  783. </td>
  784. </tr>
  785. </tbody>
  786. </table>
  787. </dd></dl>
  788. <dl class="method">
  789. <dt id="mako.lookup.TemplateCollection.has_template">
  790. <code class="descname">has_template</code><span class="sig-paren">(</span><em>uri</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateCollection.has_template" title="Permalink to this definition">¶</a></dt>
  791. <dd><p>Return <code class="docutils literal"><span class="pre">True</span></code> if this <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> is
  792. capable of returning a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object for the
  793. given <code class="docutils literal"><span class="pre">uri</span></code>.</p>
  794. <table class="docutils field-list" frame="void" rules="none">
  795. <col class="field-name" />
  796. <col class="field-body" />
  797. <tbody valign="top">
  798. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="mako.lookup.TemplateCollection.has_template.params.uri"></span><strong>uri</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateCollection.has_template.params.uri">¶</a> &#8211; String URI of the template to be resolved.</td>
  799. </tr>
  800. </tbody>
  801. </table>
  802. </dd></dl>
  803. </dd></dl>
  804. <dl class="class">
  805. <dt id="mako.lookup.TemplateLookup">
  806. <em class="property">class </em><code class="descclassname">mako.lookup.</code><code class="descname">TemplateLookup</code><span class="sig-paren">(</span><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>, <em>include_error_handler=None</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateLookup" title="Permalink to this definition">¶</a></dt>
  807. <dd><p>Bases: <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">mako.lookup.TemplateCollection</span></code></a></p>
  808. <p>Represent a collection of templates that locates template source files
  809. from the local filesystem.</p>
  810. <p>The primary argument is the <code class="docutils literal"><span class="pre">directories</span></code> argument, the list of
  811. directories to search:</p>
  812. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">([</span><span class="s2">&quot;/path/to/templates&quot;</span><span class="p">])</span>
  813. <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="s2">&quot;/index.html&quot;</span><span class="p">)</span>
  814. </pre></div>
  815. </div>
  816. <p>The <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> can also be given <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> objects
  817. programatically using <a class="reference internal" href="#mako.lookup.TemplateLookup.put_string" title="mako.lookup.TemplateLookup.put_string"><code class="xref py py-meth docutils literal"><span class="pre">put_string()</span></code></a> or <a class="reference internal" href="#mako.lookup.TemplateLookup.put_template" title="mako.lookup.TemplateLookup.put_template"><code class="xref py py-meth docutils literal"><span class="pre">put_template()</span></code></a>:</p>
  818. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">()</span>
  819. <span class="n">lookup</span><span class="o">.</span><span class="n">put_string</span><span class="p">(</span><span class="s2">&quot;base.html&quot;</span><span class="p">,</span> <span class="s1">&#39;&#39;&#39;</span>
  820. <span class="s1"> &lt;html&gt;&lt;body&gt;${self.next()}&lt;/body&gt;&lt;/html&gt;</span>
  821. <span class="s1">&#39;&#39;&#39;</span><span class="p">)</span>
  822. <span class="n">lookup</span><span class="o">.</span><span class="n">put_string</span><span class="p">(</span><span class="s2">&quot;hello.html&quot;</span><span class="p">,</span> <span class="s1">&#39;&#39;&#39;</span>
  823. <span class="s1"> &lt;</span><span class="si">%i</span><span class="s1">nclude file=&#39;base.html&#39;/&gt;</span>
  824. <span class="s1"> Hello, world !</span>
  825. <span class="s1">&#39;&#39;&#39;</span><span class="p">)</span>
  826. </pre></div>
  827. </div>
  828. <table class="docutils field-list" frame="void" rules="none">
  829. <col class="field-name" />
  830. <col class="field-body" />
  831. <tbody valign="top">
  832. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  833. <li><span class="target" id="mako.lookup.TemplateLookup.params.directories"></span><strong>directories</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateLookup.params.directories">¶</a> &#8211; A list of directory names which will be
  834. searched for a particular template URI. The URI is appended
  835. to each directory and the filesystem checked.</li>
  836. <li><span class="target" id="mako.lookup.TemplateLookup.params.collection_size"></span><strong>collection_size</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateLookup.params.collection_size">¶</a> &#8211; Approximate size of the collection used
  837. to store templates. If left at its default of <code class="docutils literal"><span class="pre">-1</span></code>, the size
  838. is unbounded, and a plain Python dictionary is used to
  839. relate URI strings to <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> instances.
  840. Otherwise, a least-recently-used cache object is used which
  841. will maintain the size of the collection approximately to
  842. the number given.</li>
  843. <li><span class="target" id="mako.lookup.TemplateLookup.params.filesystem_checks"></span><strong>filesystem_checks</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateLookup.params.filesystem_checks">¶</a> &#8211; When at its default value of <code class="docutils literal"><span class="pre">True</span></code>,
  844. each call to <a class="reference internal" href="#mako.lookup.TemplateLookup.get_template" title="mako.lookup.TemplateLookup.get_template"><code class="xref py py-meth docutils literal"><span class="pre">TemplateLookup.get_template()</span></code></a> will
  845. compare the filesystem last modified time to the time in
  846. which an existing <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object was created.
  847. This allows the <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> to regenerate a
  848. new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> whenever the original source has
  849. been updated. Set this to <code class="docutils literal"><span class="pre">False</span></code> for a very minor
  850. performance increase.</li>
  851. <li><span class="target" id="mako.lookup.TemplateLookup.params.modulename_callable"></span><strong>modulename_callable</strong><a class="paramlink headerlink reference internal" href="#mako.lookup.TemplateLookup.params.modulename_callable">¶</a> &#8211; A callable which, when present,
  852. is passed the path of the source file as well as the
  853. requested URI, and then returns the full path of the
  854. generated Python module file. This is used to inject
  855. alternate schemes for Python module location. If left at
  856. its default of <code class="docutils literal"><span class="pre">None</span></code>, the built in system of generation
  857. based on <code class="docutils literal"><span class="pre">module_directory</span></code> plus <code class="docutils literal"><span class="pre">uri</span></code> is used.</li>
  858. </ul>
  859. </td>
  860. </tr>
  861. </tbody>
  862. </table>
  863. <p>All other keyword parameters available for
  864. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> are mirrored here. When new
  865. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> objects are created, the keywords
  866. established with this <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> are passed on
  867. to each new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>.</p>
  868. <dl class="method">
  869. <dt id="mako.lookup.TemplateLookup.adjust_uri">
  870. <code class="descname">adjust_uri</code><span class="sig-paren">(</span><em>uri</em>, <em>relativeto</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateLookup.adjust_uri" title="Permalink to this definition">¶</a></dt>
  871. <dd><p>Adjust the given <code class="docutils literal"><span class="pre">uri</span></code> based on the given relative URI.</p>
  872. </dd></dl>
  873. <dl class="method">
  874. <dt id="mako.lookup.TemplateLookup.filename_to_uri">
  875. <code class="descname">filename_to_uri</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateLookup.filename_to_uri" title="Permalink to this definition">¶</a></dt>
  876. <dd><p>Convert the given <code class="docutils literal"><span class="pre">filename</span></code> to a URI relative to
  877. this <a class="reference internal" href="#mako.lookup.TemplateCollection" title="mako.lookup.TemplateCollection"><code class="xref py py-class docutils literal"><span class="pre">TemplateCollection</span></code></a>.</p>
  878. </dd></dl>
  879. <dl class="method">
  880. <dt id="mako.lookup.TemplateLookup.get_template">
  881. <code class="descname">get_template</code><span class="sig-paren">(</span><em>uri</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateLookup.get_template" title="Permalink to this definition">¶</a></dt>
  882. <dd><p>Return a <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object corresponding to the given
  883. <code class="docutils literal"><span class="pre">uri</span></code>.</p>
  884. <div class="admonition note">
  885. <p class="first admonition-title">Note</p>
  886. <p class="last">The <code class="docutils literal"><span class="pre">relativeto</span></code> argument is not supported here at
  887. the moment.</p>
  888. </div>
  889. </dd></dl>
  890. <dl class="method">
  891. <dt id="mako.lookup.TemplateLookup.put_string">
  892. <code class="descname">put_string</code><span class="sig-paren">(</span><em>uri</em>, <em>text</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateLookup.put_string" title="Permalink to this definition">¶</a></dt>
  893. <dd><p>Place a new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object into this
  894. <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>, based on the given string of
  895. <code class="docutils literal"><span class="pre">text</span></code>.</p>
  896. </dd></dl>
  897. <dl class="method">
  898. <dt id="mako.lookup.TemplateLookup.put_template">
  899. <code class="descname">put_template</code><span class="sig-paren">(</span><em>uri</em>, <em>template</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.lookup.TemplateLookup.put_template" title="Permalink to this definition">¶</a></dt>
  900. <dd><p>Place a new <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object into this
  901. <a class="reference internal" href="#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>, based on the given
  902. <a class="reference internal" href="#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object.</p>
  903. </dd></dl>
  904. </dd></dl>
  905. <dl class="class">
  906. <dt id="mako.exceptions.RichTraceback">
  907. <em class="property">class </em><code class="descclassname">mako.exceptions.</code><code class="descname">RichTraceback</code><span class="sig-paren">(</span><em>error=None</em>, <em>traceback=None</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.exceptions.RichTraceback" title="Permalink to this definition">¶</a></dt>
  908. <dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
  909. <p>Pull the current exception from the <code class="docutils literal"><span class="pre">sys</span></code> traceback and extracts
  910. Mako-specific template information.</p>
  911. <p>See the usage examples in <a class="reference internal" href="#handling-exceptions"><span class="std std-ref">Handling Exceptions</span></a>.</p>
  912. <dl class="attribute">
  913. <dt id="RichTraceback.error">
  914. <code class="descname">error</code><a class="headerlink" href="#RichTraceback.error" title="Permalink to this definition">¶</a></dt>
  915. <dd><p>the exception instance.</p>
  916. </dd></dl>
  917. <dl class="attribute">
  918. <dt id="RichTraceback.message">
  919. <code class="descname">message</code><a class="headerlink" href="#RichTraceback.message" title="Permalink to this definition">¶</a></dt>
  920. <dd><p>the exception error message as unicode.</p>
  921. </dd></dl>
  922. <dl class="attribute">
  923. <dt id="RichTraceback.source">
  924. <code class="descname">source</code><a class="headerlink" href="#RichTraceback.source" title="Permalink to this definition">¶</a></dt>
  925. <dd><p>source code of the file where the error occurred.
  926. If the error occurred within a compiled template,
  927. this is the template source.</p>
  928. </dd></dl>
  929. <dl class="attribute">
  930. <dt id="RichTraceback.lineno">
  931. <code class="descname">lineno</code><a class="headerlink" href="#RichTraceback.lineno" title="Permalink to this definition">¶</a></dt>
  932. <dd><p>line number where the error occurred. If the error
  933. occurred within a compiled template, the line number
  934. is adjusted to that of the template source.</p>
  935. </dd></dl>
  936. <dl class="attribute">
  937. <dt id="RichTraceback.records">
  938. <code class="descname">records</code><a class="headerlink" href="#RichTraceback.records" title="Permalink to this definition">¶</a></dt>
  939. <dd><p>a list of 8-tuples containing the original
  940. python traceback elements, plus the
  941. filename, line number, source line, and full template source
  942. for the traceline mapped back to its originating source
  943. template, if any for that traceline (else the fields are <code class="docutils literal"><span class="pre">None</span></code>).</p>
  944. </dd></dl>
  945. <dl class="attribute">
  946. <dt id="RichTraceback.reverse_records">
  947. <code class="descname">reverse_records</code><a class="headerlink" href="#RichTraceback.reverse_records" title="Permalink to this definition">¶</a></dt>
  948. <dd><p>the list of records in reverse
  949. traceback &#8211; a list of 4-tuples, in the same format as a regular
  950. python traceback, with template-corresponding
  951. traceback records replacing the originals.</p>
  952. </dd></dl>
  953. <dl class="attribute">
  954. <dt id="RichTraceback.reverse_traceback">
  955. <code class="descname">reverse_traceback</code><a class="headerlink" href="#RichTraceback.reverse_traceback" title="Permalink to this definition">¶</a></dt>
  956. <dd><p>the traceback list in reverse.</p>
  957. </dd></dl>
  958. </dd></dl>
  959. <dl class="function">
  960. <dt id="mako.exceptions.html_error_template">
  961. <code class="descclassname">mako.exceptions.</code><code class="descname">html_error_template</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mako.exceptions.html_error_template" title="Permalink to this definition">¶</a></dt>
  962. <dd><p>Provides a template that renders a stack trace in an HTML format,
  963. providing an excerpt of code as well as substituting source template
  964. filenames, line numbers and code for that of the originating source
  965. template, as applicable.</p>
  966. <p>The template&#8217;s default <code class="docutils literal"><span class="pre">encoding_errors</span></code> value is
  967. <code class="docutils literal"><span class="pre">'htmlentityreplace'</span></code>. The template has two options. With the
  968. <code class="docutils literal"><span class="pre">full</span></code> option disabled, only a section of an HTML document is
  969. returned. With the <code class="docutils literal"><span class="pre">css</span></code> option disabled, the default stylesheet
  970. won&#8217;t be included.</p>
  971. </dd></dl>
  972. <dl class="function">
  973. <dt id="mako.exceptions.text_error_template">
  974. <code class="descclassname">mako.exceptions.</code><code class="descname">text_error_template</code><span class="sig-paren">(</span><em>lookup=None</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.exceptions.text_error_template" title="Permalink to this definition">¶</a></dt>
  975. <dd><p>Provides a template that renders a stack trace in a similar format to
  976. the Python interpreter, substituting source template filenames, line
  977. numbers and code for that of the originating source template, as
  978. applicable.</p>
  979. </dd></dl>
  980. </div>
  981. </div>
  982. </div>
  983. </div>
  984. <div id="docs-bottom-navigation" class="docs-navigation-links">
  985. Previous:
  986. <a href="index.html" title="previous chapter">Table of Contents</a>
  987. Next:
  988. <a href="syntax.html" title="next chapter">Syntax</a>
  989. <div id="docs-copyright">
  990. &copy; Copyright the Mako authors and contributors.
  991. Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.5.3
  992. with Mako templates.
  993. </div>
  994. </div>
  995. </div>
  996. <div class="clearfix">
  997. <hr/>
  998. <div class="copyright">Website content copyright &copy; by Michael Bayer.
  999. All rights reserved. Mako and its documentation are licensed
  1000. under the MIT license. mike(&)zzzcomputing.com</div>
  1001. </div>
  1002. </div>
  1003. </body>
  1004. </html>