runtime.html 58 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728
  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. The Mako Runtime Environment
  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="Namespaces" href="namespaces.html" />
  32. <link rel="prev" title="Defs and Blocks" href="defs.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="defs.html" title="previous chapter">Defs and Blocks</a>
  63. </li>
  64. <li>Next:
  65. <a href="namespaces.html" title="next chapter">Namespaces</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/runtime.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. The Mako Runtime Environment
  78. <h2>
  79. The Mako Runtime Environment
  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="#">The Mako Runtime Environment</a><ul>
  88. <li><a class="reference internal" href="#context">Context</a><ul>
  89. <li><a class="reference internal" href="#the-buffer">The Buffer</a></li>
  90. <li><a class="reference internal" href="#context-variables">Context Variables</a></li>
  91. <li><a class="reference internal" href="#context-methods-and-accessors">Context Methods and Accessors</a></li>
  92. </ul>
  93. </li>
  94. <li><a class="reference internal" href="#the-loop-context">The Loop Context</a><ul>
  95. <li><a class="reference internal" href="#iterations">Iterations</a></li>
  96. <li><a class="reference internal" href="#cycling">Cycling</a></li>
  97. <li><a class="reference internal" href="#parent-loops">Parent Loops</a></li>
  98. <li><a class="reference internal" href="#migrating-legacy-templates-that-use-the-word-loop">Migrating Legacy Templates that Use the Word &#8220;loop&#8221;</a></li>
  99. </ul>
  100. </li>
  101. <li><a class="reference internal" href="#all-the-built-in-names">All the Built-in Names</a><ul>
  102. <li><a class="reference internal" href="#reserved-names">Reserved Names</a></li>
  103. </ul>
  104. </li>
  105. <li><a class="reference internal" href="#api-reference">API Reference</a></li>
  106. </ul>
  107. </li>
  108. </ul>
  109. <h4>Previous Topic</h4>
  110. <p>
  111. <a href="defs.html" title="previous chapter">Defs and Blocks</a>
  112. </p>
  113. <h4>Next Topic</h4>
  114. <p>
  115. <a href="namespaces.html" title="next chapter">Namespaces</a>
  116. </p>
  117. <h4>Quick Search</h4>
  118. <p>
  119. <form class="search" action="search.html" method="get">
  120. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  121. <input type="hidden" name="check_keywords" value="yes" />
  122. <input type="hidden" name="area" value="default" />
  123. </form>
  124. </p>
  125. </div>
  126. <div id="docs-body" class="withsidebar" >
  127. <div class="section" id="the-mako-runtime-environment">
  128. <span id="runtime-toplevel"></span><h1>The Mako Runtime Environment<a class="headerlink" href="#the-mako-runtime-environment" title="Permalink to this headline">¶</a></h1>
  129. <p>This section describes a little bit about the objects and
  130. built-in functions that are available in templates.</p>
  131. <div class="section" id="context">
  132. <span id="id1"></span><h2>Context<a class="headerlink" href="#context" title="Permalink to this headline">¶</a></h2>
  133. <p>The <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> is the central object that is created when
  134. a template is first executed, and is responsible for handling
  135. all communication with the outside world. Within the template
  136. environment, it is available via the <a class="reference internal" href="#reserved-names"><span class="std std-ref">reserved name</span></a>
  137. <code class="docutils literal"><span class="pre">context</span></code>. The <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> includes two
  138. major components, one of which is the output buffer, which is a
  139. file-like object such as Python&#8217;s <code class="docutils literal"><span class="pre">StringIO</span></code> or similar, and
  140. the other a dictionary of variables that can be freely
  141. referenced within a template; this dictionary is a combination
  142. of the arguments sent to the <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> function and
  143. some built-in variables provided by Mako&#8217;s runtime environment.</p>
  144. <div class="section" id="the-buffer">
  145. <h3>The Buffer<a class="headerlink" href="#the-buffer" title="Permalink to this headline">¶</a></h3>
  146. <p>The buffer is stored within the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>, and writing
  147. to it is achieved by calling the <a class="reference internal" href="#mako.runtime.Context.write" title="mako.runtime.Context.write"><code class="xref py py-meth docutils literal"><span class="pre">write()</span></code></a> method
  148. &#8211; in a template this looks like <code class="docutils literal"><span class="pre">context.write('some</span> <span class="pre">string')</span></code>.
  149. You usually don&#8217;t need to care about this, as all text within a template, as
  150. well as all expressions provided by <code class="docutils literal"><span class="pre">${}</span></code>, automatically send
  151. everything to this method. The cases you might want to be aware
  152. of its existence are if you are dealing with various
  153. filtering/buffering scenarios, which are described in
  154. <a class="reference internal" href="filtering.html"><span class="std std-ref">Filtering and Buffering</span></a>, or if you want to programmatically
  155. send content to the output stream, such as within a <code class="docutils literal"><span class="pre">&lt;%</span> <span class="pre">%&gt;</span></code>
  156. block.</p>
  157. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span>
  158. <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">&quot;some programmatic text&quot;</span><span class="p">)</span>
  159. <span class="cp">%&gt;</span><span class="x"></span>
  160. </pre></div>
  161. </div>
  162. <p>The actual buffer may or may not be the original buffer sent to
  163. the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object, as various filtering/caching
  164. scenarios may &#8220;push&#8221; a new buffer onto the context&#8217;s underlying
  165. buffer stack. For this reason, just stick with
  166. <code class="docutils literal"><span class="pre">context.write()</span></code> and content will always go to the topmost
  167. buffer.</p>
  168. </div>
  169. <div class="section" id="context-variables">
  170. <span id="context-vars"></span><h3>Context Variables<a class="headerlink" href="#context-variables" title="Permalink to this headline">¶</a></h3>
  171. <p>When your template is compiled into a Python module, the body
  172. content is enclosed within a Python function called
  173. <code class="docutils literal"><span class="pre">render_body</span></code>. Other top-level defs defined in the template are
  174. defined within their own function bodies which are named after
  175. the def&#8217;s name with the prefix <code class="docutils literal"><span class="pre">render_</span></code> (i.e. <code class="docutils literal"><span class="pre">render_mydef</span></code>).
  176. One of the first things that happens within these functions is
  177. that all variable names that are referenced within the function
  178. which are not defined in some other way (i.e. such as via
  179. assignment, module level imports, etc.) are pulled from the
  180. <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object&#8217;s dictionary of variables. This is how you&#8217;re
  181. able to freely reference variable names in a template which
  182. automatically correspond to what was passed into the current
  183. <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  184. <ul>
  185. <li><p class="first"><strong>What happens if I reference a variable name that is not in
  186. the current context?</strong> - The value you get back is a special
  187. value called <code class="docutils literal"><span class="pre">UNDEFINED</span></code>, or if the <code class="docutils literal"><span class="pre">strict_undefined=True</span></code> flag
  188. is used a <code class="docutils literal"><span class="pre">NameError</span></code> is raised. <code class="docutils literal"><span class="pre">UNDEFINED</span></code> is just a simple global
  189. variable with the class <a class="reference internal" href="#mako.runtime.Undefined" title="mako.runtime.Undefined"><code class="xref py py-class docutils literal"><span class="pre">mako.runtime.Undefined</span></code></a>. The
  190. <code class="docutils literal"><span class="pre">UNDEFINED</span></code> object throws an error when you call <code class="docutils literal"><span class="pre">str()</span></code> on
  191. it, which is what happens if you try to use it in an
  192. expression.</p>
  193. </li>
  194. <li><p class="first"><strong>UNDEFINED makes it hard for me to find what name is missing</strong> - An alternative
  195. is to specify the option <code class="docutils literal"><span class="pre">strict_undefined=True</span></code>
  196. to the <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>. This will cause
  197. any non-present variables to raise an immediate <code class="docutils literal"><span class="pre">NameError</span></code>
  198. which includes the name of the variable in its message
  199. when <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> is called &#8211; <code class="docutils literal"><span class="pre">UNDEFINED</span></code> is not used.</p>
  200. <div class="versionadded">
  201. <p><span class="versionmodified">New in version 0.3.6.</span></p>
  202. </div>
  203. </li>
  204. <li><p class="first"><strong>Why not just return None?</strong> Using <code class="docutils literal"><span class="pre">UNDEFINED</span></code>, or
  205. raising a <code class="docutils literal"><span class="pre">NameError</span></code> is more
  206. explicit and allows differentiation between a value of <code class="docutils literal"><span class="pre">None</span></code>
  207. that was explicitly passed to the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> and a value that
  208. wasn&#8217;t present at all.</p>
  209. </li>
  210. <li><p class="first"><strong>Why raise an exception when you call str() on it ? Why not
  211. just return a blank string?</strong> - Mako tries to stick to the
  212. Python philosophy of &#8220;explicit is better than implicit&#8221;. In
  213. this case, it&#8217;s decided that the template author should be made
  214. to specifically handle a missing value rather than
  215. experiencing what may be a silent failure. Since <code class="docutils literal"><span class="pre">UNDEFINED</span></code>
  216. is a singleton object just like Python&#8217;s <code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">False</span></code>,
  217. you can use the <code class="docutils literal"><span class="pre">is</span></code> operator to check for it:</p>
  218. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">%</span> <span class="k">if</span> <span class="n">someval</span> <span class="ow">is</span> <span class="n">UNDEFINED</span><span class="p">:</span><span class="x"></span>
  219. <span class="x"> someval is: no value</span>
  220. <span class="cp">%</span> <span class="k">else</span><span class="p">:</span><span class="x"></span>
  221. <span class="x"> someval is: </span><span class="cp">${</span><span class="n">someval</span><span class="cp">}</span>
  222. <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
  223. </pre></div>
  224. </div>
  225. </li>
  226. </ul>
  227. <p>Another facet of the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> is that its dictionary of
  228. variables is <strong>immutable</strong>. Whatever is set when
  229. <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> is called is what stays. Of course, since
  230. its Python, you can hack around this and change values in the
  231. context&#8217;s internal dictionary, but this will probably will not
  232. work as well as you&#8217;d think. The reason for this is that Mako in
  233. many cases creates copies of the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object, which
  234. get sent to various elements of the template and inheriting
  235. templates used in an execution. So changing the value in your
  236. local <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> will not necessarily make that value
  237. available in other parts of the template&#8217;s execution. Examples
  238. of where Mako creates copies of the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> include
  239. within top-level def calls from the main body of the template
  240. (the context is used to propagate locally assigned variables
  241. into the scope of defs; since in the template&#8217;s body they appear
  242. as inlined functions, Mako tries to make them act that way), and
  243. within an inheritance chain (each template in an inheritance
  244. chain has a different notion of <code class="docutils literal"><span class="pre">parent</span></code> and <code class="docutils literal"><span class="pre">next</span></code>, which
  245. are all stored in unique <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> instances).</p>
  246. <ul>
  247. <li><p class="first"><strong>So what if I want to set values that are global to everyone
  248. within a template request?</strong> - All you have to do is provide a
  249. dictionary to your <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> when the template first
  250. runs, and everyone can just get/set variables from that. Lets
  251. say its called <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
  252. <p>Running the template looks like:</p>
  253. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">output</span> <span class="o">=</span> <span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">attributes</span><span class="o">=</span><span class="p">{})</span>
  254. </pre></div>
  255. </div>
  256. <p>Within a template, just reference the dictionary:</p>
  257. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span>
  258. <span class="n">attributes</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;bar&#39;</span>
  259. <span class="cp">%&gt;</span><span class="x"></span>
  260. <span class="x">&#39;foo&#39; attribute is: </span><span class="cp">${</span><span class="n">attributes</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span><span class="cp">}</span><span class="x"></span>
  261. </pre></div>
  262. </div>
  263. </li>
  264. <li><p class="first"><strong>Why can&#8217;t &#8220;attributes&#8221; be a built-in feature of the
  265. Context?</strong> - This is an area where Mako is trying to make as
  266. few decisions about your application as it possibly can.
  267. Perhaps you don&#8217;t want your templates to use this technique of
  268. assigning and sharing data, or perhaps you have a different
  269. notion of the names and kinds of data structures that should
  270. be passed around. Once again Mako would rather ask the user to
  271. be explicit.</p>
  272. </li>
  273. </ul>
  274. </div>
  275. <div class="section" id="context-methods-and-accessors">
  276. <h3>Context Methods and Accessors<a class="headerlink" href="#context-methods-and-accessors" title="Permalink to this headline">¶</a></h3>
  277. <p>Significant members of <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> include:</p>
  278. <ul>
  279. <li><p class="first"><code class="docutils literal"><span class="pre">context[key]</span></code> / <code class="docutils literal"><span class="pre">context.get(key,</span> <span class="pre">default=None)</span></code> -
  280. dictionary-like accessors for the context. Normally, any
  281. variable you use in your template is automatically pulled from
  282. the context if it isn&#8217;t defined somewhere already. Use the
  283. dictionary accessor and/or <code class="docutils literal"><span class="pre">get</span></code> method when you want a
  284. variable that <em>is</em> already defined somewhere else, such as in
  285. the local arguments sent to a <code class="docutils literal"><span class="pre">%def</span></code> call. If a key is not
  286. present, like a dictionary it raises <code class="docutils literal"><span class="pre">KeyError</span></code>.</p>
  287. </li>
  288. <li><p class="first"><code class="docutils literal"><span class="pre">keys()</span></code> - all the names defined within this context.</p>
  289. </li>
  290. <li><p class="first"><code class="docutils literal"><span class="pre">kwargs</span></code> - this returns a <strong>copy</strong> of the context&#8217;s
  291. dictionary of variables. This is useful when you want to
  292. propagate the variables in the current context to a function
  293. as keyword arguments, i.e.:</p>
  294. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">(</span><span class="o">**</span><span class="n">context</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  295. </pre></div>
  296. </div>
  297. </li>
  298. <li><p class="first"><code class="docutils literal"><span class="pre">write(text)</span></code> - write some text to the current output
  299. stream.</p>
  300. </li>
  301. <li><p class="first"><code class="docutils literal"><span class="pre">lookup</span></code> - returns the <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> instance that is
  302. used for all file-lookups within the current execution (even
  303. though individual <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> instances can conceivably have
  304. different instances of a <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>, only the
  305. <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> of the originally-called <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> gets
  306. used in a particular execution).</p>
  307. </li>
  308. </ul>
  309. </div>
  310. </div>
  311. <div class="section" id="the-loop-context">
  312. <span id="loop-context"></span><h2>The Loop Context<a class="headerlink" href="#the-loop-context" title="Permalink to this headline">¶</a></h2>
  313. <p>Within <code class="docutils literal"><span class="pre">%</span> <span class="pre">for</span></code> blocks, the <a class="reference internal" href="#reserved-names"><span class="std std-ref">reserved name</span></a> <code class="docutils literal"><span class="pre">loop</span></code>
  314. is available. <code class="docutils literal"><span class="pre">loop</span></code> tracks the progress of
  315. the <code class="docutils literal"><span class="pre">for</span></code> loop and makes it easy to use the iteration state to control
  316. template behavior:</p>
  317. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;ul&gt;</span>
  318. <span class="cp">%</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="p">(</span><span class="s2">&quot;one&quot;</span><span class="p">,</span> <span class="s2">&quot;two&quot;</span><span class="p">,</span> <span class="s2">&quot;three&quot;</span><span class="p">):</span><span class="x"></span>
  319. <span class="x"> &lt;li&gt;Item </span><span class="cp">${</span><span class="n">loop</span><span class="o">.</span><span class="n">index</span><span class="cp">}</span><span class="x">: </span><span class="cp">${</span><span class="n">a</span><span class="cp">}</span><span class="x">&lt;/li&gt;</span>
  320. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  321. <span class="x">&lt;/ul&gt;</span>
  322. </pre></div>
  323. </div>
  324. <div class="versionadded">
  325. <p><span class="versionmodified">New in version 0.7.</span></p>
  326. </div>
  327. <div class="section" id="iterations">
  328. <h3>Iterations<a class="headerlink" href="#iterations" title="Permalink to this headline">¶</a></h3>
  329. <p>Regardless of the type of iterable you&#8217;re looping over, <code class="docutils literal"><span class="pre">loop</span></code> always tracks
  330. the 0-indexed iteration count (available at <code class="docutils literal"><span class="pre">loop.index</span></code>), its parity
  331. (through the <code class="docutils literal"><span class="pre">loop.even</span></code> and <code class="docutils literal"><span class="pre">loop.odd</span></code> bools), and <code class="docutils literal"><span class="pre">loop.first</span></code>, a bool
  332. indicating whether the loop is on its first iteration. If your iterable
  333. provides a <code class="docutils literal"><span class="pre">__len__</span></code> method, <code class="docutils literal"><span class="pre">loop</span></code> also provides access to
  334. a count of iterations remaining at <code class="docutils literal"><span class="pre">loop.reverse_index</span></code> and <code class="docutils literal"><span class="pre">loop.last</span></code>,
  335. a bool indicating whether the loop is on its last iteration; accessing these
  336. without <code class="docutils literal"><span class="pre">__len__</span></code> will raise a <code class="docutils literal"><span class="pre">TypeError</span></code>.</p>
  337. </div>
  338. <div class="section" id="cycling">
  339. <h3>Cycling<a class="headerlink" href="#cycling" title="Permalink to this headline">¶</a></h3>
  340. <p>Cycling is available regardless of whether the iterable you&#8217;re using provides
  341. a <code class="docutils literal"><span class="pre">__len__</span></code> method. Prior to Mako 0.7, you might have generated a simple
  342. zebra striped list using <code class="docutils literal"><span class="pre">enumerate</span></code>:</p>
  343. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;ul&gt;</span>
  344. <span class="cp">%</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">item</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">((</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;ham&#39;</span><span class="p">,</span> <span class="s1">&#39;eggs&#39;</span><span class="p">)):</span><span class="x"></span>
  345. <span class="x"> &lt;li class=&quot;</span><span class="cp">${</span><span class="s1">&#39;odd&#39;</span> <span class="k">if</span> <span class="n">i</span> <span class="o">%</span> <span class="mi">2</span> <span class="k">else</span> <span class="s1">&#39;even&#39;</span><span class="cp">}</span><span class="x">&quot;&gt;</span><span class="cp">${</span><span class="n">item</span><span class="cp">}</span><span class="x">&lt;/li&gt;</span>
  346. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  347. <span class="x">&lt;/ul&gt;</span>
  348. </pre></div>
  349. </div>
  350. <p>With <code class="docutils literal"><span class="pre">loop.cycle</span></code>, you get the same results with cleaner code and less prep work:</p>
  351. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;ul&gt;</span>
  352. <span class="cp">%</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="p">(</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;ham&#39;</span><span class="p">,</span> <span class="s1">&#39;eggs&#39;</span><span class="p">):</span><span class="x"></span>
  353. <span class="x"> &lt;li class=&quot;</span><span class="cp">${</span><span class="n">loop</span><span class="o">.</span><span class="n">cycle</span><span class="p">(</span><span class="s1">&#39;even&#39;</span><span class="p">,</span> <span class="s1">&#39;odd&#39;</span><span class="p">)</span><span class="cp">}</span><span class="x">&quot;&gt;</span><span class="cp">${</span><span class="n">item</span><span class="cp">}</span><span class="x">&lt;/li&gt;</span>
  354. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  355. <span class="x">&lt;/ul&gt;</span>
  356. </pre></div>
  357. </div>
  358. <p>Both approaches produce output like the following:</p>
  359. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
  360. <span class="p">&lt;</span><span class="nt">li</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;even&quot;</span><span class="p">&gt;</span>spam<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  361. <span class="p">&lt;</span><span class="nt">li</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;odd&quot;</span><span class="p">&gt;</span>ham<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  362. <span class="p">&lt;</span><span class="nt">li</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;even&quot;</span><span class="p">&gt;</span>eggs<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  363. <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
  364. </pre></div>
  365. </div>
  366. </div>
  367. <div class="section" id="parent-loops">
  368. <h3>Parent Loops<a class="headerlink" href="#parent-loops" title="Permalink to this headline">¶</a></h3>
  369. <p>Loop contexts can also be transparently nested, and the Mako runtime will do
  370. the right thing and manage the scope for you. You can access the parent loop
  371. context through <code class="docutils literal"><span class="pre">loop.parent</span></code>.</p>
  372. <p>This allows you to reach all the way back up through the loop stack by
  373. chaining <code class="docutils literal"><span class="pre">parent</span></code> attribute accesses, i.e. <code class="docutils literal"><span class="pre">loop.parent.parent....</span></code> as
  374. long as the stack depth isn&#8217;t exceeded. For example, you can use the parent
  375. loop to make a checkered table:</p>
  376. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;table&gt;</span>
  377. <span class="cp">%</span> <span class="k">for</span> <span class="n">consonant</span> <span class="ow">in</span> <span class="s1">&#39;pbj&#39;</span><span class="p">:</span><span class="x"></span>
  378. <span class="x"> &lt;tr&gt;</span>
  379. <span class="cp">%</span> <span class="k">for</span> <span class="n">vowel</span> <span class="ow">in</span> <span class="s1">&#39;iou&#39;</span><span class="p">:</span><span class="x"></span>
  380. <span class="x"> &lt;td class=&quot;</span><span class="cp">${</span><span class="s1">&#39;black&#39;</span> <span class="k">if</span> <span class="p">(</span><span class="n">loop</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">even</span> <span class="o">==</span> <span class="n">loop</span><span class="o">.</span><span class="n">even</span><span class="p">)</span> <span class="k">else</span> <span class="s1">&#39;red&#39;</span><span class="cp">}</span><span class="x">&quot;&gt;</span>
  381. <span class="x"> </span><span class="cp">${</span><span class="n">consonant</span> <span class="o">+</span> <span class="n">vowel</span><span class="cp">}</span><span class="x">t</span>
  382. <span class="x"> &lt;/td&gt;</span>
  383. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  384. <span class="x"> &lt;/tr&gt;</span>
  385. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  386. <span class="x">&lt;/table&gt;</span>
  387. </pre></div>
  388. </div>
  389. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">table</span><span class="p">&gt;</span>
  390. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;</span>
  391. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;black&quot;</span><span class="p">&gt;</span>
  392. pit
  393. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  394. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;red&quot;</span><span class="p">&gt;</span>
  395. pot
  396. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  397. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;black&quot;</span><span class="p">&gt;</span>
  398. put
  399. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  400. <span class="p">&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  401. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;</span>
  402. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;red&quot;</span><span class="p">&gt;</span>
  403. bit
  404. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  405. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;black&quot;</span><span class="p">&gt;</span>
  406. bot
  407. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  408. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;red&quot;</span><span class="p">&gt;</span>
  409. but
  410. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  411. <span class="p">&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  412. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;</span>
  413. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;black&quot;</span><span class="p">&gt;</span>
  414. jit
  415. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  416. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;red&quot;</span><span class="p">&gt;</span>
  417. jot
  418. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  419. <span class="p">&lt;</span><span class="nt">td</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;black&quot;</span><span class="p">&gt;</span>
  420. jut
  421. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  422. <span class="p">&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  423. <span class="p">&lt;/</span><span class="nt">table</span><span class="p">&gt;</span>
  424. </pre></div>
  425. </div>
  426. </div>
  427. <div class="section" id="migrating-legacy-templates-that-use-the-word-loop">
  428. <span id="migrating-loop"></span><h3>Migrating Legacy Templates that Use the Word &#8220;loop&#8221;<a class="headerlink" href="#migrating-legacy-templates-that-use-the-word-loop" title="Permalink to this headline">¶</a></h3>
  429. <div class="versionchanged">
  430. <p><span class="versionmodified">Changed in version 0.7: </span>The <code class="docutils literal"><span class="pre">loop</span></code> name is now <a class="reference internal" href="#reserved-names"><span class="std std-ref">reserved</span></a> in Mako,
  431. which means a template that refers to a variable named <code class="docutils literal"><span class="pre">loop</span></code>
  432. won&#8217;t function correctly when used in Mako 0.7.</p>
  433. </div>
  434. <p>To ease the transition for such systems, the feature can be disabled across the board for
  435. all templates, then re-enabled on a per-template basis for those templates which wish
  436. to make use of the new system.</p>
  437. <p>First, the <code class="docutils literal"><span class="pre">enable_loop=False</span></code> flag is passed to either the <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a>
  438. or <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object in use:</p>
  439. <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="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">enable_loop</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
  440. </pre></div>
  441. </div>
  442. <p>or:</p>
  443. <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="s2">&quot;some template&quot;</span><span class="p">,</span> <span class="n">enable_loop</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
  444. </pre></div>
  445. </div>
  446. <p>An individual template can make usage of the feature when <code class="docutils literal"><span class="pre">enable_loop</span></code> is set to
  447. <code class="docutils literal"><span class="pre">False</span></code> by switching it back on within the <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag:</p>
  448. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">enable_loop=</span><span class="s">&quot;True&quot;</span><span class="cp">/&gt;</span>
  449. <span class="cp">%</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">collection</span><span class="p">:</span><span class="x"></span>
  450. <span class="x"> </span><span class="cp">${</span><span class="n">i</span><span class="cp">}</span><span class="x"> </span><span class="cp">${</span><span class="n">loop</span><span class="o">.</span><span class="n">index</span><span class="cp">}</span>
  451. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  452. </pre></div>
  453. </div>
  454. <p>Using the above scheme, it&#8217;s safe to pass the name <code class="docutils literal"><span class="pre">loop</span></code> to the <a class="reference internal" href="usage.html#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>
  455. method as well as to freely make usage of a variable named <code class="docutils literal"><span class="pre">loop</span></code> within a template, provided
  456. the <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag doesn&#8217;t override it. New templates that want to use the <code class="docutils literal"><span class="pre">loop</span></code> context
  457. can then set up <code class="docutils literal"><span class="pre">&lt;%page</span> <span class="pre">enable_loop=&quot;True&quot;/&gt;</span></code> to use the new feature without affecting
  458. old templates.</p>
  459. </div>
  460. </div>
  461. <div class="section" id="all-the-built-in-names">
  462. <h2>All the Built-in Names<a class="headerlink" href="#all-the-built-in-names" title="Permalink to this headline">¶</a></h2>
  463. <p>A one-stop shop for all the names Mako defines. Most of these
  464. names are instances of <a class="reference internal" href="namespaces.html#mako.runtime.Namespace" title="mako.runtime.Namespace"><code class="xref py py-class docutils literal"><span class="pre">Namespace</span></code></a>, which are described
  465. in the next section, <a class="reference internal" href="namespaces.html"><span class="std std-ref">Namespaces</span></a>. Also, most of
  466. these names other than <code class="docutils literal"><span class="pre">context</span></code>, <code class="docutils literal"><span class="pre">UNDEFINED</span></code>, and <code class="docutils literal"><span class="pre">loop</span></code> are
  467. also present <em>within</em> the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> itself. The names
  468. <code class="docutils literal"><span class="pre">context</span></code>, <code class="docutils literal"><span class="pre">loop</span></code> and <code class="docutils literal"><span class="pre">UNDEFINED</span></code> themselves can&#8217;t be passed
  469. to the context and can&#8217;t be substituted &#8211; see the section <a class="reference internal" href="#reserved-names"><span class="std std-ref">Reserved Names</span></a>.</p>
  470. <ul class="simple">
  471. <li><code class="docutils literal"><span class="pre">context</span></code> - this is the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object, introduced
  472. at <a class="reference internal" href="#context"><span class="std std-ref">Context</span></a>.</li>
  473. <li><code class="docutils literal"><span class="pre">local</span></code> - the namespace of the current template, described
  474. in <a class="reference internal" href="namespaces.html#namespaces-builtin"><span class="std std-ref">Built-in Namespaces</span></a>.</li>
  475. <li><code class="docutils literal"><span class="pre">self</span></code> - the namespace of the topmost template in an
  476. inheritance chain (if any, otherwise the same as <code class="docutils literal"><span class="pre">local</span></code>),
  477. mostly described in <a class="reference internal" href="inheritance.html"><span class="std std-ref">Inheritance</span></a>.</li>
  478. <li><code class="docutils literal"><span class="pre">parent</span></code> - the namespace of the parent template in an
  479. inheritance chain (otherwise undefined); see
  480. <a class="reference internal" href="inheritance.html"><span class="std std-ref">Inheritance</span></a>.</li>
  481. <li><code class="docutils literal"><span class="pre">next</span></code> - the namespace of the next template in an
  482. inheritance chain (otherwise undefined); see
  483. <a class="reference internal" href="inheritance.html"><span class="std std-ref">Inheritance</span></a>.</li>
  484. <li><code class="docutils literal"><span class="pre">caller</span></code> - a &#8220;mini&#8221; namespace created when using the
  485. <code class="docutils literal"><span class="pre">&lt;%call&gt;</span></code> tag to define a &#8220;def call with content&#8221;; described
  486. in <a class="reference internal" href="defs.html#defs-with-content"><span class="std std-ref">Calling a Def with Embedded Content and/or Other Defs</span></a>.</li>
  487. <li><code class="docutils literal"><span class="pre">loop</span></code> - this provides access to <a class="reference internal" href="#mako.runtime.LoopContext" title="mako.runtime.LoopContext"><code class="xref py py-class docutils literal"><span class="pre">LoopContext</span></code></a> objects when
  488. they are requested within <code class="docutils literal"><span class="pre">%</span> <span class="pre">for</span></code> loops, introduced at <a class="reference internal" href="#loop-context"><span class="std std-ref">The Loop Context</span></a>.</li>
  489. <li><code class="docutils literal"><span class="pre">capture</span></code> - a function that calls a given def and captures
  490. its resulting content into a string, which is returned. Usage
  491. is described in <a class="reference internal" href="filtering.html"><span class="std std-ref">Filtering and Buffering</span></a>.</li>
  492. <li><code class="docutils literal"><span class="pre">UNDEFINED</span></code> - a global singleton that is applied to all
  493. otherwise uninitialized template variables that were not
  494. located within the <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> when rendering began,
  495. unless the <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> flag <code class="docutils literal"><span class="pre">strict_undefined</span></code>
  496. is set to <code class="docutils literal"><span class="pre">True</span></code>. <code class="docutils literal"><span class="pre">UNDEFINED</span></code> is
  497. an instance of <a class="reference internal" href="#mako.runtime.Undefined" title="mako.runtime.Undefined"><code class="xref py py-class docutils literal"><span class="pre">Undefined</span></code></a>, and raises an
  498. exception when its <code class="docutils literal"><span class="pre">__str__()</span></code> method is called.</li>
  499. <li><code class="docutils literal"><span class="pre">pageargs</span></code> - this is a dictionary which is present in a
  500. template which does not define any <code class="docutils literal"><span class="pre">**kwargs</span></code> section in its
  501. <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag. All keyword arguments sent to the <code class="docutils literal"><span class="pre">body()</span></code>
  502. function of a template (when used via namespaces) go here by
  503. default unless otherwise defined as a page argument. If this
  504. makes no sense, it shouldn&#8217;t; read the section
  505. <a class="reference internal" href="namespaces.html#namespaces-body"><span class="std std-ref">The body() Method</span></a>.</li>
  506. </ul>
  507. <div class="section" id="reserved-names">
  508. <span id="id2"></span><h3>Reserved Names<a class="headerlink" href="#reserved-names" title="Permalink to this headline">¶</a></h3>
  509. <p>Mako has a few names that are considered to be &#8220;reserved&#8221; and can&#8217;t be used
  510. as variable names.</p>
  511. <div class="versionchanged">
  512. <p><span class="versionmodified">Changed in version 0.7: </span>Mako raises an error if these words are found passed to the template
  513. as context arguments, whereas in previous versions they&#8217;d be silently
  514. ignored or lead to other error messages.</p>
  515. </div>
  516. <ul class="simple">
  517. <li><code class="docutils literal"><span class="pre">context</span></code> - see <a class="reference internal" href="#context"><span class="std std-ref">Context</span></a>.</li>
  518. <li><code class="docutils literal"><span class="pre">UNDEFINED</span></code> - see <a class="reference internal" href="#context-vars"><span class="std std-ref">Context Variables</span></a>.</li>
  519. <li><code class="docutils literal"><span class="pre">loop</span></code> - see <a class="reference internal" href="#loop-context"><span class="std std-ref">The Loop Context</span></a>. Note this can be disabled for legacy templates
  520. via the <code class="docutils literal"><span class="pre">enable_loop=False</span></code> argument; see <a class="reference internal" href="#migrating-loop"><span class="std std-ref">Migrating Legacy Templates that Use the Word &#8220;loop&#8221;</span></a>.</li>
  521. </ul>
  522. </div>
  523. </div>
  524. <div class="section" id="api-reference">
  525. <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
  526. <dl class="class">
  527. <dt id="mako.runtime.Context">
  528. <em class="property">class </em><code class="descclassname">mako.runtime.</code><code class="descname">Context</code><span class="sig-paren">(</span><em>buffer</em>, <em>**data</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context" title="Permalink to this definition">¶</a></dt>
  529. <dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
  530. <p>Provides runtime namespace, output buffer, and various
  531. callstacks for templates.</p>
  532. <p>See <a class="reference internal" href="#"><span class="std std-ref">The Mako Runtime Environment</span></a> for detail on the usage of
  533. <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  534. <dl class="method">
  535. <dt id="mako.runtime.Context.get">
  536. <code class="descname">get</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context.get" title="Permalink to this definition">¶</a></dt>
  537. <dd><p>Return a value from this <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  538. </dd></dl>
  539. <dl class="method">
  540. <dt id="mako.runtime.Context.keys">
  541. <code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context.keys" title="Permalink to this definition">¶</a></dt>
  542. <dd><p>Return a list of all names established in this <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  543. </dd></dl>
  544. <dl class="attribute">
  545. <dt id="mako.runtime.Context.kwargs">
  546. <code class="descname">kwargs</code><a class="headerlink" href="#mako.runtime.Context.kwargs" title="Permalink to this definition">¶</a></dt>
  547. <dd><p>Return the dictionary of top level keyword arguments associated
  548. with this <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  549. <p>This dictionary only includes the top-level arguments passed to
  550. <a class="reference internal" href="usage.html#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>. It does not include names produced within
  551. the template execution such as local variable names or special names
  552. such as <code class="docutils literal"><span class="pre">self</span></code>, <code class="docutils literal"><span class="pre">next</span></code>, etc.</p>
  553. <p>The purpose of this dictionary is primarily for the case that
  554. a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> accepts arguments via its <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag,
  555. which are normally expected to be passed via <a class="reference internal" href="usage.html#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>,
  556. except the template is being called in an inheritance context,
  557. using the <code class="docutils literal"><span class="pre">body()</span></code> method. <a class="reference internal" href="#mako.runtime.Context.kwargs" title="mako.runtime.Context.kwargs"><code class="xref py py-attr docutils literal"><span class="pre">Context.kwargs</span></code></a> can then be
  558. used to propagate these arguments to the inheriting template:</p>
  559. <div class="highlight-default"><div class="highlight"><pre><span></span>${next.body(**context.kwargs)}
  560. </pre></div>
  561. </div>
  562. </dd></dl>
  563. <dl class="attribute">
  564. <dt id="mako.runtime.Context.lookup">
  565. <code class="descname">lookup</code><a class="headerlink" href="#mako.runtime.Context.lookup" title="Permalink to this definition">¶</a></dt>
  566. <dd><p>Return the <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><code class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></code></a> associated
  567. with this <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  568. </dd></dl>
  569. <dl class="method">
  570. <dt id="mako.runtime.Context.pop_caller">
  571. <code class="descname">pop_caller</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context.pop_caller" title="Permalink to this definition">¶</a></dt>
  572. <dd><p>Pop a <code class="docutils literal"><span class="pre">caller</span></code> callable onto the callstack for this
  573. <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  574. </dd></dl>
  575. <dl class="method">
  576. <dt id="mako.runtime.Context.push_caller">
  577. <code class="descname">push_caller</code><span class="sig-paren">(</span><em>caller</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context.push_caller" title="Permalink to this definition">¶</a></dt>
  578. <dd><p>Push a <code class="docutils literal"><span class="pre">caller</span></code> callable onto the callstack for
  579. this <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
  580. </dd></dl>
  581. <dl class="method">
  582. <dt id="mako.runtime.Context.write">
  583. <code class="descname">write</code><span class="sig-paren">(</span><em>string</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context.write" title="Permalink to this definition">¶</a></dt>
  584. <dd><p>Write a string to this <a class="reference internal" href="#mako.runtime.Context" title="mako.runtime.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> object&#8217;s
  585. underlying output buffer.</p>
  586. </dd></dl>
  587. <dl class="method">
  588. <dt id="mako.runtime.Context.writer">
  589. <code class="descname">writer</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.Context.writer" title="Permalink to this definition">¶</a></dt>
  590. <dd><p>Return the current writer function.</p>
  591. </dd></dl>
  592. </dd></dl>
  593. <dl class="class">
  594. <dt id="mako.runtime.LoopContext">
  595. <em class="property">class </em><code class="descclassname">mako.runtime.</code><code class="descname">LoopContext</code><span class="sig-paren">(</span><em>iterable</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.LoopContext" title="Permalink to this definition">¶</a></dt>
  596. <dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
  597. <p>A magic loop variable.
  598. Automatically accessible in any <code class="docutils literal"><span class="pre">%</span> <span class="pre">for</span></code> block.</p>
  599. <p>See the section <a class="reference internal" href="#loop-context"><span class="std std-ref">The Loop Context</span></a> for usage
  600. notes.</p>
  601. <dl class="docutils">
  602. <dt><code class="xref py py-attr docutils literal"><span class="pre">parent</span></code> -&gt; <a class="reference internal" href="#mako.runtime.LoopContext" title="mako.runtime.LoopContext"><code class="xref py py-class docutils literal"><span class="pre">LoopContext</span></code></a> or <code class="docutils literal"><span class="pre">None</span></code></dt>
  603. <dd>The parent loop, if one exists.</dd>
  604. <dt><code class="xref py py-attr docutils literal"><span class="pre">index</span></code> -&gt; <cite>int</cite></dt>
  605. <dd>The 0-based iteration count.</dd>
  606. <dt><code class="xref py py-attr docutils literal"><span class="pre">reverse_index</span></code> -&gt; <cite>int</cite></dt>
  607. <dd>The number of iterations remaining.</dd>
  608. <dt><code class="xref py py-attr docutils literal"><span class="pre">first</span></code> -&gt; <cite>bool</cite></dt>
  609. <dd><code class="docutils literal"><span class="pre">True</span></code> on the first iteration, <code class="docutils literal"><span class="pre">False</span></code> otherwise.</dd>
  610. <dt><code class="xref py py-attr docutils literal"><span class="pre">last</span></code> -&gt; <cite>bool</cite></dt>
  611. <dd><code class="docutils literal"><span class="pre">True</span></code> on the last iteration, <code class="docutils literal"><span class="pre">False</span></code> otherwise.</dd>
  612. <dt><code class="xref py py-attr docutils literal"><span class="pre">even</span></code> -&gt; <cite>bool</cite></dt>
  613. <dd><code class="docutils literal"><span class="pre">True</span></code> when <code class="docutils literal"><span class="pre">index</span></code> is even.</dd>
  614. <dt><code class="xref py py-attr docutils literal"><span class="pre">odd</span></code> -&gt; <cite>bool</cite></dt>
  615. <dd><code class="docutils literal"><span class="pre">True</span></code> when <code class="docutils literal"><span class="pre">index</span></code> is odd.</dd>
  616. </dl>
  617. <dl class="method">
  618. <dt id="mako.runtime.LoopContext.cycle">
  619. <code class="descname">cycle</code><span class="sig-paren">(</span><em>*values</em><span class="sig-paren">)</span><a class="headerlink" href="#mako.runtime.LoopContext.cycle" title="Permalink to this definition">¶</a></dt>
  620. <dd><p>Cycle through values as the loop progresses.</p>
  621. </dd></dl>
  622. </dd></dl>
  623. <dl class="class">
  624. <dt id="mako.runtime.Undefined">
  625. <em class="property">class </em><code class="descclassname">mako.runtime.</code><code class="descname">Undefined</code><a class="headerlink" href="#mako.runtime.Undefined" title="Permalink to this definition">¶</a></dt>
  626. <dd><p>Bases: <code class="xref py py-class docutils literal"><span class="pre">object</span></code></p>
  627. <p>Represents an undefined value in a template.</p>
  628. <p>All template modules have a constant value
  629. <code class="docutils literal"><span class="pre">UNDEFINED</span></code> present which is an instance of this
  630. object.</p>
  631. </dd></dl>
  632. </div>
  633. </div>
  634. </div>
  635. </div>
  636. <div id="docs-bottom-navigation" class="docs-navigation-links">
  637. Previous:
  638. <a href="defs.html" title="previous chapter">Defs and Blocks</a>
  639. Next:
  640. <a href="namespaces.html" title="next chapter">Namespaces</a>
  641. <div id="docs-copyright">
  642. &copy; Copyright the Mako authors and contributors.
  643. Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.5.3
  644. with Mako templates.
  645. </div>
  646. </div>
  647. </div>
  648. <div class="clearfix">
  649. <hr/>
  650. <div class="copyright">Website content copyright &copy; by Michael Bayer.
  651. All rights reserved. Mako and its documentation are licensed
  652. under the MIT license. mike(&)zzzcomputing.com</div>
  653. </div>
  654. </div>
  655. </body>
  656. </html>