caching.html 57 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779
  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. Caching
  7. &mdash;
  8. Mako 0.8.1 Documentation
  9. </title>
  10. <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  11. <link rel="stylesheet" href="_static/docs.css" type="text/css" />
  12. <script type="text/javascript">
  13. var DOCUMENTATION_OPTIONS = {
  14. URL_ROOT: '#',
  15. VERSION: '0.8.1',
  16. COLLAPSE_MODINDEX: false,
  17. FILE_SUFFIX: '.html'
  18. };
  19. </script>
  20. <script type="text/javascript" src="_static/jquery.js"></script>
  21. <script type="text/javascript" src="_static/underscore.js"></script>
  22. <script type="text/javascript" src="_static/doctools.js"></script>
  23. <link rel="index" title="Index" href="genindex.html" />
  24. <link rel="search" title="Search" href="search.html" />
  25. <link rel="top" title="Mako 0.8.1 Documentation" href="index.html" />
  26. <link rel="prev" title="The Unicode Chapter" href="unicode.html" />
  27. <link rel="stylesheet" href="_static/site.css"></link>
  28. </head>
  29. <body>
  30. <div id="wrap">
  31. <div class="rightbar">
  32. <div class="slogan">
  33. Hyperfast and lightweight templating for the Python platform.
  34. </div>
  35. </div>
  36. <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
  37. <hr/>
  38. <div id="docs-container">
  39. <div id="docs-header">
  40. <h1>Mako 0.8.1 Documentation</h1>
  41. <div id="docs-search">
  42. Search:
  43. <form class="search" action="search.html" method="get">
  44. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  45. <input type="hidden" name="check_keywords" value="yes" />
  46. <input type="hidden" name="area" value="default" />
  47. </form>
  48. </div>
  49. <div id="docs-version-header">
  50. Release: <span class="version-num">0.8.1</span>
  51. </div>
  52. </div>
  53. <div id="docs-top-navigation">
  54. <div id="docs-top-page-control" class="docs-navigation-links">
  55. <ul>
  56. <li>Prev:
  57. <a href="unicode.html" title="previous chapter">The Unicode Chapter</a>
  58. </li>
  59. <li>
  60. <a href="index.html">Table of Contents</a> |
  61. <a href="genindex.html">Index</a>
  62. | <a href="_sources/caching.txt">view source
  63. </li>
  64. </ul>
  65. </div>
  66. <div id="docs-navigation-banner">
  67. <a href="index.html">Mako 0.8.1 Documentation</a>
  68. »
  69. Caching
  70. <h2>
  71. Caching
  72. </h2>
  73. </div>
  74. </div>
  75. <div id="docs-body-container">
  76. <div id="docs-sidebar">
  77. <h3><a href="index.html">Table of Contents</a></h3>
  78. <ul>
  79. <li><a class="reference internal" href="#">Caching</a><ul>
  80. <li><a class="reference internal" href="#cache-arguments">Cache Arguments</a><ul>
  81. <li><a class="reference internal" href="#backend-specific-cache-arguments">Backend-Specific Cache Arguments</a></li>
  82. <li><a class="reference internal" href="#using-the-beaker-cache-backend">Using the Beaker Cache Backend</a></li>
  83. <li><a class="reference internal" href="#using-the-dogpile-cache-backend">Using the dogpile.cache Backend</a></li>
  84. </ul>
  85. </li>
  86. <li><a class="reference internal" href="#programmatic-cache-access">Programmatic Cache Access</a></li>
  87. <li><a class="reference internal" href="#cache-plugins">Cache Plugins</a><ul>
  88. <li><a class="reference internal" href="#guidelines-for-writing-cache-plugins">Guidelines for Writing Cache Plugins</a></li>
  89. </ul>
  90. </li>
  91. <li><a class="reference internal" href="#api-reference">API Reference</a></li>
  92. </ul>
  93. </li>
  94. </ul>
  95. <h4>Previous Topic</h4>
  96. <p>
  97. <a href="unicode.html" title="previous chapter">The Unicode Chapter</a>
  98. </p>
  99. <h4>Quick Search</h4>
  100. <p>
  101. <form class="search" action="search.html" method="get">
  102. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  103. <input type="hidden" name="check_keywords" value="yes" />
  104. <input type="hidden" name="area" value="default" />
  105. </form>
  106. </p>
  107. </div>
  108. <div id="docs-body" class="withsidebar" >
  109. <div class="section" id="caching">
  110. <span id="caching-toplevel"></span><h1>Caching<a class="headerlink" href="#caching" title="Permalink to this headline">¶</a></h1>
  111. <p>Any template or component can be cached using the <tt class="docutils literal"><span class="pre">cache</span></tt>
  112. argument to the <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> or <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt> directives:</p>
  113. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  114. <span class="x">template text</span>
  115. </pre></div>
  116. </div>
  117. <p>The above template, after being executed the first time, will
  118. store its content within a cache that by default is scoped
  119. within memory. Subsequent calls to the template&#8217;s <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a>
  120. method will return content directly from the cache. When the
  121. <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object itself falls out of scope, its corresponding
  122. cache is garbage collected along with the template.</p>
  123. <p>By default, caching requires that the <a class="reference external" href="http://beaker.readthedocs.org/">Beaker</a> package be installed on the
  124. system, however the mechanism of caching can be customized to use
  125. any third party or user defined system &#8211; see <a class="reference internal" href="#cache-plugins"><em>Cache Plugins</em></a>.</p>
  126. <p>In addition to being available on the <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> tag, the caching flag and all
  127. its options can be used with the <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> tag as well:</p>
  128. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;mycomp&quot;</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_timeout=</span><span class="s">&quot;60&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  129. <span class="x"> other text</span>
  130. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  131. </pre></div>
  132. </div>
  133. <p>... and equivalently with the <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt> tag, anonymous or named:</p>
  134. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_timeout=</span><span class="s">&quot;60&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  135. <span class="x"> other text</span>
  136. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  137. </pre></div>
  138. </div>
  139. <div class="section" id="cache-arguments">
  140. <h2>Cache Arguments<a class="headerlink" href="#cache-arguments" title="Permalink to this headline">¶</a></h2>
  141. <p>Mako has two cache arguments available on tags that are
  142. available in all cases. The rest of the arguments
  143. available are specific to a backend.</p>
  144. <p>The two generic tags arguments are:</p>
  145. <ul>
  146. <li><p class="first"><tt class="docutils literal"><span class="pre">cached=&quot;True&quot;</span></tt> - enable caching for this <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt>,
  147. <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt>, or <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt>.</p>
  148. </li>
  149. <li><p class="first"><tt class="docutils literal"><span class="pre">cache_key</span></tt> - the &#8220;key&#8221; used to uniquely identify this content
  150. in the cache. Usually, this key is chosen automatically
  151. based on the name of the rendering callable (i.e. <tt class="docutils literal"><span class="pre">body</span></tt>
  152. when used in <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt>, the name of the def when using <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt>,
  153. the explicit or internally-generated name when using <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt>).
  154. Using the <tt class="docutils literal"><span class="pre">cache_key</span></tt> parameter, the key can be overridden
  155. using a fixed or programmatically generated value.</p>
  156. <p>For example, here&#8217;s a page
  157. that caches any page which inherits from it, based on the
  158. filename of the calling template:</p>
  159. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_key=</span><span class="s">&quot;${self.filename}&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  160. <span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span>
  161. <span class="cp">## rest of template</span><span class="x"></span>
  162. </pre></div>
  163. </div>
  164. </li>
  165. </ul>
  166. <p>On a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>, the
  167. caching can be configured using these arguments:</p>
  168. <ul>
  169. <li><p class="first"><tt class="docutils literal"><span class="pre">cache_enabled</span></tt> - Setting this
  170. to <tt class="docutils literal"><span class="pre">False</span></tt> will disable all caching functionality
  171. when the template renders. Defaults to <tt class="docutils literal"><span class="pre">True</span></tt>.
  172. e.g.:</p>
  173. <div class="highlight-python"><div class="highlight"><pre><span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span>
  174. <span class="n">directories</span><span class="o">=</span><span class="s">&#39;/path/to/templates&#39;</span><span class="p">,</span>
  175. <span class="n">cache_enabled</span> <span class="o">=</span> <span class="bp">False</span>
  176. <span class="p">)</span>
  177. </pre></div>
  178. </div>
  179. </li>
  180. <li><p class="first"><tt class="docutils literal"><span class="pre">cache_impl</span></tt> - The string name of the cache backend
  181. to use. This defaults to <tt class="docutils literal"><span class="pre">'beaker'</span></tt>, which has historically
  182. been the only cache backend supported by Mako.</p>
  183. <p class="versionadded">
  184. <span class="versionmodified">New in version 0.6.0.</span></p>
  185. <p>For example, here&#8217;s how to use the upcoming
  186. <a class="reference external" href="http://dogpilecache.readthedocs.org">dogpile.cache</a>
  187. backend:</p>
  188. <div class="highlight-python"><div class="highlight"><pre><span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span>
  189. <span class="n">directories</span><span class="o">=</span><span class="s">&#39;/path/to/templates&#39;</span><span class="p">,</span>
  190. <span class="n">cache_impl</span> <span class="o">=</span> <span class="s">&#39;dogpile.cache&#39;</span><span class="p">,</span>
  191. <span class="n">cache_args</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;regions&#39;</span><span class="p">:</span><span class="n">my_dogpile_regions</span><span class="p">}</span>
  192. <span class="p">)</span>
  193. </pre></div>
  194. </div>
  195. </li>
  196. <li><p class="first"><tt class="docutils literal"><span class="pre">cache_args</span></tt> - A dictionary of cache parameters that
  197. will be consumed by the cache backend. See
  198. <a class="reference internal" href="#beaker-backend"><em>Using the Beaker Cache Backend</em></a> for examples.</p>
  199. <p class="versionadded">
  200. <span class="versionmodified">New in version 0.6.0.</span></p>
  201. </li>
  202. </ul>
  203. <div class="section" id="backend-specific-cache-arguments">
  204. <h3>Backend-Specific Cache Arguments<a class="headerlink" href="#backend-specific-cache-arguments" title="Permalink to this headline">¶</a></h3>
  205. <p>The <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt>, and <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt> tags
  206. accept any named argument that starts with the prefix <tt class="docutils literal"><span class="pre">&quot;cache_&quot;</span></tt>.
  207. Those arguments are then packaged up and passed along to the
  208. underlying caching implementation, minus the <tt class="docutils literal"><span class="pre">&quot;cache_&quot;</span></tt> prefix.</p>
  209. <p>The actual arguments understood are determined by the backend.</p>
  210. <ul class="simple">
  211. <li><a class="reference internal" href="#beaker-backend"><em>Using the Beaker Cache Backend</em></a> - Includes arguments understood by
  212. Beaker.</li>
  213. <li><a class="reference internal" href="#dogpile-cache-backend"><em>Using the dogpile.cache Backend</em></a> - Includes arguments understood by
  214. dogpile.cache.</li>
  215. </ul>
  216. </div>
  217. <div class="section" id="using-the-beaker-cache-backend">
  218. <span id="beaker-backend"></span><h3>Using the Beaker Cache Backend<a class="headerlink" href="#using-the-beaker-cache-backend" title="Permalink to this headline">¶</a></h3>
  219. <p>When using Beaker, new implementations will want to make usage
  220. of <strong>cache regions</strong> so that cache configurations can be maintained
  221. externally to templates. These configurations live under
  222. named &#8220;regions&#8221; that can be referred to within templates themselves.</p>
  223. <p class="versionadded">
  224. <span class="versionmodified">New in version 0.6.0: </span>Support for Beaker cache regions.</p>
  225. <p>For example, suppose we would like two regions. One is a &#8220;short term&#8221;
  226. region that will store content in a memory-based dictionary,
  227. expiring after 60 seconds. The other is a Memcached region,
  228. where values should expire in five minutes. To configure
  229. our <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>, first we get a handle to a
  230. <a class="reference external" href="http://beaker.readthedocs.org/en/latest/modules/cache.html#beaker.cache.CacheManager" title="(in Beaker v1.6)"><tt class="xref py py-class docutils literal"><span class="pre">beaker.cache.CacheManager</span></tt></a>:</p>
  231. <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">beaker.cache</span> <span class="kn">import</span> <span class="n">CacheManager</span>
  232. <span class="n">manager</span> <span class="o">=</span> <span class="n">CacheManager</span><span class="p">(</span><span class="n">cache_regions</span><span class="o">=</span><span class="p">{</span>
  233. <span class="s">&#39;short_term&#39;</span><span class="p">:{</span>
  234. <span class="s">&#39;type&#39;</span><span class="p">:</span> <span class="s">&#39;memory&#39;</span><span class="p">,</span>
  235. <span class="s">&#39;expire&#39;</span><span class="p">:</span> <span class="mi">60</span>
  236. <span class="p">},</span>
  237. <span class="s">&#39;long_term&#39;</span><span class="p">:{</span>
  238. <span class="s">&#39;type&#39;</span><span class="p">:</span> <span class="s">&#39;ext:memcached&#39;</span><span class="p">,</span>
  239. <span class="s">&#39;url&#39;</span><span class="p">:</span> <span class="s">&#39;127.0.0.1:11211&#39;</span><span class="p">,</span>
  240. <span class="s">&#39;expire&#39;</span><span class="p">:</span> <span class="mi">300</span>
  241. <span class="p">}</span>
  242. <span class="p">})</span>
  243. <span class="n">lookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span>
  244. <span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;/path/to/templates&#39;</span><span class="p">],</span>
  245. <span class="n">module_directory</span><span class="o">=</span><span class="s">&#39;/path/to/modules&#39;</span><span class="p">,</span>
  246. <span class="n">cache_impl</span><span class="o">=</span><span class="s">&#39;beaker&#39;</span><span class="p">,</span>
  247. <span class="n">cache_args</span><span class="o">=</span><span class="p">{</span>
  248. <span class="s">&#39;manager&#39;</span><span class="p">:</span><span class="n">manager</span>
  249. <span class="p">}</span>
  250. <span class="p">)</span>
  251. </pre></div>
  252. </div>
  253. <p>Our templates can then opt to cache data in one of either region,
  254. using the <tt class="docutils literal"><span class="pre">cache_region</span></tt> argument. Such as using <tt class="docutils literal"><span class="pre">short_term</span></tt>
  255. at the <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> level:</p>
  256. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_region=</span><span class="s">&quot;short_term&quot;</span><span class="cp">&gt;</span>
  257. <span class="cp">## ...</span><span class="x"></span>
  258. </pre></div>
  259. </div>
  260. <p>Or, <tt class="docutils literal"><span class="pre">long_term</span></tt> at the <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt> level:</p>
  261. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;header&quot;</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_region=</span><span class="s">&quot;long_term&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  262. <span class="x"> other text</span>
  263. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  264. </pre></div>
  265. </div>
  266. <p>The Beaker backend also works without regions. There are a
  267. variety of arguments that can be passed to the <tt class="docutils literal"><span class="pre">cache_args</span></tt>
  268. dictionary, which are also allowable in templates via the
  269. <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt>,
  270. and <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> tags specific to those sections. The values
  271. given override those specified at the <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>
  272. or <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> level.</p>
  273. <p>With the possible exception
  274. of <tt class="docutils literal"><span class="pre">cache_timeout</span></tt>, these arguments are probably better off
  275. staying at the template configuration level. Each argument
  276. specified as <tt class="docutils literal"><span class="pre">cache_XYZ</span></tt> in a template tag is specified
  277. without the <tt class="docutils literal"><span class="pre">cache_</span></tt> prefix in the <tt class="docutils literal"><span class="pre">cache_args</span></tt> dictionary:</p>
  278. <ul class="simple">
  279. <li><tt class="docutils literal"><span class="pre">cache_timeout</span></tt> - number of seconds in which to invalidate the
  280. cached data. After this timeout, the content is re-generated
  281. on the next call. Available as <tt class="docutils literal"><span class="pre">timeout</span></tt> in the <tt class="docutils literal"><span class="pre">cache_args</span></tt>
  282. dictionary.</li>
  283. <li><tt class="docutils literal"><span class="pre">cache_type</span></tt> - type of caching. <tt class="docutils literal"><span class="pre">'memory'</span></tt>, <tt class="docutils literal"><span class="pre">'file'</span></tt>, <tt class="docutils literal"><span class="pre">'dbm'</span></tt>, or
  284. <tt class="docutils literal"><span class="pre">'ext:memcached'</span></tt> (note that the string <tt class="docutils literal"><span class="pre">memcached</span></tt> is
  285. also accepted by the dogpile.cache Mako plugin, though not by Beaker itself).
  286. Available as <tt class="docutils literal"><span class="pre">type</span></tt> in the <tt class="docutils literal"><span class="pre">cache_args</span></tt> dictionary.</li>
  287. <li><tt class="docutils literal"><span class="pre">cache_url</span></tt> - (only used for <tt class="docutils literal"><span class="pre">memcached</span></tt> but required) a single
  288. IP address or a semi-colon separated list of IP address of
  289. memcache servers to use. Available as <tt class="docutils literal"><span class="pre">url</span></tt> in the <tt class="docutils literal"><span class="pre">cache_args</span></tt>
  290. dictionary.</li>
  291. <li><tt class="docutils literal"><span class="pre">cache_dir</span></tt> - in the case of the <tt class="docutils literal"><span class="pre">'file'</span></tt> and <tt class="docutils literal"><span class="pre">'dbm'</span></tt> cache types,
  292. this is the filesystem directory with which to store data
  293. files. If this option is not present, the value of
  294. <tt class="docutils literal"><span class="pre">module_directory</span></tt> is used (i.e. the directory where compiled
  295. template modules are stored). If neither option is available
  296. an exception is thrown. Available as <tt class="docutils literal"><span class="pre">dir</span></tt> in the
  297. <tt class="docutils literal"><span class="pre">cache_args</span></tt> dictionary.</li>
  298. </ul>
  299. </div>
  300. <div class="section" id="using-the-dogpile-cache-backend">
  301. <span id="dogpile-cache-backend"></span><h3>Using the dogpile.cache Backend<a class="headerlink" href="#using-the-dogpile-cache-backend" title="Permalink to this headline">¶</a></h3>
  302. <p><a class="reference external" href="http://dogpilecache.readthedocs.org">dogpile.cache</a> is a new replacement for Beaker. It provides
  303. a modernized, slimmed down interface and is generally easier to use
  304. than Beaker. As of this writing it has not yet been released. dogpile.cache
  305. includes its own Mako cache plugin &#8211; see <a class="reference external" href="http://dogpilecache.readthedocs.org/en/latest/api.html#dogpile.cache.plugins.mako_cache" title="(in dogpile.cache v0.4.4)"><tt class="xref py py-mod docutils literal"><span class="pre">dogpile.cache.plugins.mako_cache</span></tt></a> in the
  306. dogpile.cache documentation.</p>
  307. </div>
  308. </div>
  309. <div class="section" id="programmatic-cache-access">
  310. <h2>Programmatic Cache Access<a class="headerlink" href="#programmatic-cache-access" title="Permalink to this headline">¶</a></h2>
  311. <p>The <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>, as well as any template-derived <a class="reference internal" href="namespaces.html#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a>, has
  312. an accessor called <tt class="docutils literal"><span class="pre">cache</span></tt> which returns the <a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> object
  313. for that template. This object is a facade on top of the underlying
  314. <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> object, and provides some very rudimental
  315. capabilities, such as the ability to get and put arbitrary
  316. values:</p>
  317. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span>
  318. <span class="n">local</span><span class="o">.</span><span class="n">cache</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s">&quot;somekey&quot;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">&quot;memory&quot;</span><span class="p">,</span> <span class="s">&quot;somevalue&quot;</span><span class="p">)</span>
  319. <span class="cp">%&gt;</span><span class="x"></span>
  320. </pre></div>
  321. </div>
  322. <p>Above, the cache associated with the <tt class="docutils literal"><span class="pre">local</span></tt> namespace is
  323. accessed and a key is placed within a memory cache.</p>
  324. <p>More commonly, the <tt class="docutils literal"><span class="pre">cache</span></tt> object is used to invalidate cached
  325. sections programmatically:</p>
  326. <div class="highlight-python"><div class="highlight"><pre><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="s">&#39;/sometemplate.html&#39;</span><span class="p">)</span>
  327. <span class="c"># invalidate the &quot;body&quot; of the template</span>
  328. <span class="n">template</span><span class="o">.</span><span class="n">cache</span><span class="o">.</span><span class="n">invalidate_body</span><span class="p">()</span>
  329. <span class="c"># invalidate an individual def</span>
  330. <span class="n">template</span><span class="o">.</span><span class="n">cache</span><span class="o">.</span><span class="n">invalidate_def</span><span class="p">(</span><span class="s">&#39;somedef&#39;</span><span class="p">)</span>
  331. <span class="c"># invalidate an arbitrary key</span>
  332. <span class="n">template</span><span class="o">.</span><span class="n">cache</span><span class="o">.</span><span class="n">invalidate</span><span class="p">(</span><span class="s">&#39;somekey&#39;</span><span class="p">)</span>
  333. </pre></div>
  334. </div>
  335. <p>You can access any special method or attribute of the <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a>
  336. itself using the <a class="reference internal" href="#mako.cache.Cache.impl" title="mako.cache.Cache.impl"><tt class="xref py py-attr docutils literal"><span class="pre">impl</span></tt></a> attribute:</p>
  337. <div class="highlight-python"><div class="highlight"><pre><span class="n">template</span><span class="o">.</span><span class="n">cache</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">do_something_special</span><span class="p">()</span>
  338. </pre></div>
  339. </div>
  340. <p>Note that using implementation-specific methods will mean you can&#8217;t
  341. swap in a different kind of <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> implementation at a
  342. later time.</p>
  343. </div>
  344. <div class="section" id="cache-plugins">
  345. <span id="id1"></span><h2>Cache Plugins<a class="headerlink" href="#cache-plugins" title="Permalink to this headline">¶</a></h2>
  346. <p>The mechanism used by caching can be plugged in
  347. using a <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> subclass. This class implements
  348. the rudimental methods Mako needs to implement the caching
  349. API. Mako includes the <a class="reference internal" href="#mako.ext.beaker_cache.BeakerCacheImpl" title="mako.ext.beaker_cache.BeakerCacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">BeakerCacheImpl</span></tt></a> class to
  350. provide the default implementation. A <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> class
  351. is acquired by Mako using a <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> entrypoint, using
  352. the name given as the <tt class="docutils literal"><span class="pre">cache_impl</span></tt> argument to <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>
  353. or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a>. This entry point can be
  354. installed via the standard <cite>setuptools</cite>/<tt class="docutils literal"><span class="pre">setup()</span></tt> procedure, underneath
  355. the <cite>EntryPoint</cite> group named <tt class="docutils literal"><span class="pre">&quot;mako.cache&quot;</span></tt>. It can also be
  356. installed at runtime via a convenience installer <a class="reference internal" href="#mako.cache.register_plugin" title="mako.cache.register_plugin"><tt class="xref py py-func docutils literal"><span class="pre">register_plugin()</span></tt></a>
  357. which accomplishes essentially the same task.</p>
  358. <p>An example plugin that implements a local dictionary cache:</p>
  359. <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.cache</span> <span class="kn">import</span> <span class="n">Cacheimpl</span><span class="p">,</span> <span class="n">register_plugin</span>
  360. <span class="k">class</span> <span class="nc">SimpleCacheImpl</span><span class="p">(</span><span class="n">CacheImpl</span><span class="p">):</span>
  361. <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cache</span><span class="p">):</span>
  362. <span class="nb">super</span><span class="p">(</span><span class="n">SimpleCacheImpl</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
  363. <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span> <span class="o">=</span> <span class="p">{}</span>
  364. <span class="k">def</span> <span class="nf">get_or_create</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">creation_function</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
  365. <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">:</span>
  366. <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
  367. <span class="k">else</span><span class="p">:</span>
  368. <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span> <span class="o">=</span> <span class="n">creation_function</span><span class="p">()</span>
  369. <span class="k">return</span> <span class="n">value</span>
  370. <span class="k">def</span> <span class="nf">set</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
  371. <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
  372. <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
  373. <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
  374. <span class="k">def</span> <span class="nf">invalidate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
  375. <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
  376. <span class="c"># optional - register the class locally</span>
  377. <span class="n">register_plugin</span><span class="p">(</span><span class="s">&quot;simple&quot;</span><span class="p">,</span> <span class="n">__name__</span><span class="p">,</span> <span class="s">&quot;SimpleCacheImpl&quot;</span><span class="p">)</span>
  378. </pre></div>
  379. </div>
  380. <p>Enabling the above plugin in a template would look like:</p>
  381. <div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">&quot;mytemplate&quot;</span><span class="p">,</span>
  382. <span class="nb">file</span><span class="o">=</span><span class="s">&quot;mytemplate.html&quot;</span><span class="p">,</span>
  383. <span class="n">cache_impl</span><span class="o">=</span><span class="s">&#39;simple&#39;</span><span class="p">)</span>
  384. </pre></div>
  385. </div>
  386. <div class="section" id="guidelines-for-writing-cache-plugins">
  387. <h3>Guidelines for Writing Cache Plugins<a class="headerlink" href="#guidelines-for-writing-cache-plugins" title="Permalink to this headline">¶</a></h3>
  388. <ul class="simple">
  389. <li>The <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> is created on a per-<a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> basis. The
  390. class should ensure that only data for the parent <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> is
  391. persisted or returned by the cache methods. The actual <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>
  392. is available via the <tt class="docutils literal"><span class="pre">self.cache.template</span></tt> attribute. The <tt class="docutils literal"><span class="pre">self.cache.id</span></tt>
  393. attribute, which is essentially the unique modulename of the template, is
  394. a good value to use in order to represent a unique namespace of keys specific
  395. to the template.</li>
  396. <li>Templates only use the <a class="reference internal" href="#mako.cache.CacheImpl.get_or_create" title="mako.cache.CacheImpl.get_or_create"><tt class="xref py py-meth docutils literal"><span class="pre">CacheImpl.get_or_create()</span></tt></a> method
  397. in an implicit fashion. The <a class="reference internal" href="#mako.cache.CacheImpl.set" title="mako.cache.CacheImpl.set"><tt class="xref py py-meth docutils literal"><span class="pre">CacheImpl.set()</span></tt></a>,
  398. <a class="reference internal" href="#mako.cache.CacheImpl.get" title="mako.cache.CacheImpl.get"><tt class="xref py py-meth docutils literal"><span class="pre">CacheImpl.get()</span></tt></a>, and <a class="reference internal" href="#mako.cache.CacheImpl.invalidate" title="mako.cache.CacheImpl.invalidate"><tt class="xref py py-meth docutils literal"><span class="pre">CacheImpl.invalidate()</span></tt></a> methods are
  399. only used in response to direct programmatic access to the corresponding
  400. methods on the <a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> object.</li>
  401. <li><a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> will be accessed in a multithreaded fashion if the
  402. <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> itself is used multithreaded. Care should be taken
  403. to ensure caching implementations are threadsafe.</li>
  404. <li>A library like <a class="reference external" href="http://pypi.python.org/pypi/dogpile.core">Dogpile</a>, which
  405. is a minimal locking system derived from Beaker, can be used to help
  406. implement the <a class="reference internal" href="#mako.cache.CacheImpl.get_or_create" title="mako.cache.CacheImpl.get_or_create"><tt class="xref py py-meth docutils literal"><span class="pre">CacheImpl.get_or_create()</span></tt></a> method in a threadsafe
  407. way that can maximize effectiveness across multiple threads as well
  408. as processes. <a class="reference internal" href="#mako.cache.CacheImpl.get_or_create" title="mako.cache.CacheImpl.get_or_create"><tt class="xref py py-meth docutils literal"><span class="pre">CacheImpl.get_or_create()</span></tt></a> is the
  409. key method used by templates.</li>
  410. <li>All arguments passed to <tt class="docutils literal"><span class="pre">**kw</span></tt> come directly from the parameters
  411. inside the <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt>, or <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> tags directly,
  412. minus the <tt class="docutils literal"><span class="pre">&quot;cache_&quot;</span></tt> prefix, as strings, with the exception of
  413. the argument <tt class="docutils literal"><span class="pre">cache_timeout</span></tt>, which is passed to the plugin
  414. as the name <tt class="docutils literal"><span class="pre">timeout</span></tt> with the value converted to an integer.
  415. Arguments present in <tt class="docutils literal"><span class="pre">cache_args</span></tt> on <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or
  416. <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> are passed directly, but are superseded
  417. by those present in the most specific template tag.</li>
  418. <li>The directory where <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> places module files can
  419. be acquired using the accessor <tt class="docutils literal"><span class="pre">self.cache.template.module_directory</span></tt>.
  420. This directory can be a good place to throw cache-related work
  421. files, underneath a prefix like <tt class="docutils literal"><span class="pre">_my_cache_work</span></tt> so that name
  422. conflicts with generated modules don&#8217;t occur.</li>
  423. </ul>
  424. </div>
  425. </div>
  426. <div class="section" id="api-reference">
  427. <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
  428. <dl class="class">
  429. <dt id="mako.cache.Cache">
  430. <em class="property">class </em><tt class="descclassname">mako.cache.</tt><tt class="descname">Cache</tt><big>(</big><em>template</em>, <em>*args</em><big>)</big><a class="headerlink" href="#mako.cache.Cache" title="Permalink to this definition">¶</a></dt>
  431. <dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
  432. <p>Represents a data content cache made available to the module
  433. space of a specific <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object.</p>
  434. <p class="versionadded">
  435. <span class="versionmodified">New in version 0.6: </span><a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> by itself is mostly a
  436. container for a <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> object, which implements
  437. a fixed API to provide caching services; specific subclasses exist to
  438. implement different
  439. caching strategies. Mako includes a backend that works with
  440. the Beaker caching system. Beaker itself then supports
  441. a number of backends (i.e. file, memory, memcached, etc.)</p>
  442. <p>The construction of a <a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> is part of the mechanics
  443. of a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>, and programmatic access to this
  444. cache is typically via the <tt class="xref py py-attr docutils literal"><span class="pre">Template.cache</span></tt> attribute.</p>
  445. <dl class="method">
  446. <dt id="mako.cache.Cache.get">
  447. <tt class="descname">get</tt><big>(</big><em>key</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.get" title="Permalink to this definition">¶</a></dt>
  448. <dd><p>Retrieve a value from the cache.</p>
  449. <table class="docutils field-list" frame="void" rules="none">
  450. <col class="field-name" />
  451. <col class="field-body" />
  452. <tbody valign="top">
  453. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  454. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  455. <li><strong>**kw</strong> &#8211; cache configuration arguments. The
  456. backend is configured using these arguments upon first request.
  457. Subsequent requests that use the same series of configuration
  458. values will use that same backend.</li>
  459. </ul>
  460. </td>
  461. </tr>
  462. </tbody>
  463. </table>
  464. </dd></dl>
  465. <dl class="method">
  466. <dt id="mako.cache.Cache.get_or_create">
  467. <tt class="descname">get_or_create</tt><big>(</big><em>key</em>, <em>creation_function</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.get_or_create" title="Permalink to this definition">¶</a></dt>
  468. <dd><p>Retrieve a value from the cache, using the given creation function
  469. to generate a new value.</p>
  470. </dd></dl>
  471. <dl class="attribute">
  472. <dt id="mako.cache.Cache.id">
  473. <tt class="descname">id</tt><em class="property"> = None</em><a class="headerlink" href="#mako.cache.Cache.id" title="Permalink to this definition">¶</a></dt>
  474. <dd><p>Return the &#8216;id&#8217; that identifies this cache.</p>
  475. <p>This is a value that should be globally unique to the
  476. <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> associated with this cache, and can
  477. be used by a caching system to name a local container
  478. for data specific to this template.</p>
  479. </dd></dl>
  480. <dl class="attribute">
  481. <dt id="mako.cache.Cache.impl">
  482. <tt class="descname">impl</tt><em class="property"> = None</em><a class="headerlink" href="#mako.cache.Cache.impl" title="Permalink to this definition">¶</a></dt>
  483. <dd><p>Provide the <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> in use by this <a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a>.</p>
  484. <p>This accessor allows a <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> with additional
  485. methods beyond that of <a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a> to be used programmatically.</p>
  486. </dd></dl>
  487. <dl class="method">
  488. <dt id="mako.cache.Cache.invalidate">
  489. <tt class="descname">invalidate</tt><big>(</big><em>key</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.invalidate" title="Permalink to this definition">¶</a></dt>
  490. <dd><p>Invalidate a value in the cache.</p>
  491. <table class="docutils field-list" frame="void" rules="none">
  492. <col class="field-name" />
  493. <col class="field-body" />
  494. <tbody valign="top">
  495. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  496. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  497. <li><strong>**kw</strong> &#8211; cache configuration arguments. The
  498. backend is configured using these arguments upon first request.
  499. Subsequent requests that use the same series of configuration
  500. values will use that same backend.</li>
  501. </ul>
  502. </td>
  503. </tr>
  504. </tbody>
  505. </table>
  506. </dd></dl>
  507. <dl class="method">
  508. <dt id="mako.cache.Cache.invalidate_body">
  509. <tt class="descname">invalidate_body</tt><big>(</big><big>)</big><a class="headerlink" href="#mako.cache.Cache.invalidate_body" title="Permalink to this definition">¶</a></dt>
  510. <dd><p>Invalidate the cached content of the &#8220;body&#8221; method for this
  511. template.</p>
  512. </dd></dl>
  513. <dl class="method">
  514. <dt id="mako.cache.Cache.invalidate_closure">
  515. <tt class="descname">invalidate_closure</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.invalidate_closure" title="Permalink to this definition">¶</a></dt>
  516. <dd><p>Invalidate a nested <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> within this template.</p>
  517. <p>Caching of nested defs is a blunt tool as there is no
  518. management of scope &#8211; nested defs that use cache tags
  519. need to have names unique of all other nested defs in the
  520. template, else their content will be overwritten by
  521. each other.</p>
  522. </dd></dl>
  523. <dl class="method">
  524. <dt id="mako.cache.Cache.invalidate_def">
  525. <tt class="descname">invalidate_def</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.invalidate_def" title="Permalink to this definition">¶</a></dt>
  526. <dd><p>Invalidate the cached content of a particular <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt> within this
  527. template.</p>
  528. </dd></dl>
  529. <dl class="method">
  530. <dt id="mako.cache.Cache.put">
  531. <tt class="descname">put</tt><big>(</big><em>key</em>, <em>value</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.put" title="Permalink to this definition">¶</a></dt>
  532. <dd><p>A synonym for <a class="reference internal" href="#mako.cache.Cache.set" title="mako.cache.Cache.set"><tt class="xref py py-meth docutils literal"><span class="pre">Cache.set()</span></tt></a>.</p>
  533. <p>This is here for backwards compatibility.</p>
  534. </dd></dl>
  535. <dl class="method">
  536. <dt id="mako.cache.Cache.set">
  537. <tt class="descname">set</tt><big>(</big><em>key</em>, <em>value</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.Cache.set" title="Permalink to this definition">¶</a></dt>
  538. <dd><p>Place a value in the cache.</p>
  539. <table class="docutils field-list" frame="void" rules="none">
  540. <col class="field-name" />
  541. <col class="field-body" />
  542. <tbody valign="top">
  543. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  544. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  545. <li><strong>value</strong> &#8211; the value.</li>
  546. <li><strong>**kw</strong> &#8211; cache configuration arguments.</li>
  547. </ul>
  548. </td>
  549. </tr>
  550. </tbody>
  551. </table>
  552. </dd></dl>
  553. <dl class="attribute">
  554. <dt id="mako.cache.Cache.starttime">
  555. <tt class="descname">starttime</tt><em class="property"> = None</em><a class="headerlink" href="#mako.cache.Cache.starttime" title="Permalink to this definition">¶</a></dt>
  556. <dd><p>Epochal time value for when the owning <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> was
  557. first compiled.</p>
  558. <p>A cache implementation may wish to invalidate data earlier than
  559. this timestamp; this has the effect of the cache for a specific
  560. <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> starting clean any time the <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a>
  561. is recompiled, such as when the original template file changed on
  562. the filesystem.</p>
  563. </dd></dl>
  564. </dd></dl>
  565. <dl class="class">
  566. <dt id="mako.cache.CacheImpl">
  567. <em class="property">class </em><tt class="descclassname">mako.cache.</tt><tt class="descname">CacheImpl</tt><big>(</big><em>cache</em><big>)</big><a class="headerlink" href="#mako.cache.CacheImpl" title="Permalink to this definition">¶</a></dt>
  568. <dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
  569. <p>Provide a cache implementation for use by <a class="reference internal" href="#mako.cache.Cache" title="mako.cache.Cache"><tt class="xref py py-class docutils literal"><span class="pre">Cache</span></tt></a>.</p>
  570. <dl class="method">
  571. <dt id="mako.cache.CacheImpl.get">
  572. <tt class="descname">get</tt><big>(</big><em>key</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.CacheImpl.get" title="Permalink to this definition">¶</a></dt>
  573. <dd><p>Retrieve a value from the cache.</p>
  574. <table class="docutils field-list" frame="void" rules="none">
  575. <col class="field-name" />
  576. <col class="field-body" />
  577. <tbody valign="top">
  578. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  579. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  580. <li><strong>**kw</strong> &#8211; cache configuration arguments.</li>
  581. </ul>
  582. </td>
  583. </tr>
  584. </tbody>
  585. </table>
  586. </dd></dl>
  587. <dl class="method">
  588. <dt id="mako.cache.CacheImpl.get_or_create">
  589. <tt class="descname">get_or_create</tt><big>(</big><em>key</em>, <em>creation_function</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.CacheImpl.get_or_create" title="Permalink to this definition">¶</a></dt>
  590. <dd><p>Retrieve a value from the cache, using the given creation function
  591. to generate a new value.</p>
  592. <p>This function <em>must</em> return a value, either from
  593. the cache, or via the given creation function.
  594. If the creation function is called, the newly
  595. created value should be populated into the cache
  596. under the given key before being returned.</p>
  597. <table class="docutils field-list" frame="void" rules="none">
  598. <col class="field-name" />
  599. <col class="field-body" />
  600. <tbody valign="top">
  601. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  602. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  603. <li><strong>creation_function</strong> &#8211; function that when called generates
  604. a new value.</li>
  605. <li><strong>**kw</strong> &#8211; cache configuration arguments.</li>
  606. </ul>
  607. </td>
  608. </tr>
  609. </tbody>
  610. </table>
  611. </dd></dl>
  612. <dl class="method">
  613. <dt id="mako.cache.CacheImpl.invalidate">
  614. <tt class="descname">invalidate</tt><big>(</big><em>key</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.CacheImpl.invalidate" title="Permalink to this definition">¶</a></dt>
  615. <dd><p>Invalidate a value in the cache.</p>
  616. <table class="docutils field-list" frame="void" rules="none">
  617. <col class="field-name" />
  618. <col class="field-body" />
  619. <tbody valign="top">
  620. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  621. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  622. <li><strong>**kw</strong> &#8211; cache configuration arguments.</li>
  623. </ul>
  624. </td>
  625. </tr>
  626. </tbody>
  627. </table>
  628. </dd></dl>
  629. <dl class="attribute">
  630. <dt id="mako.cache.CacheImpl.pass_context">
  631. <tt class="descname">pass_context</tt><em class="property"> = False</em><a class="headerlink" href="#mako.cache.CacheImpl.pass_context" title="Permalink to this definition">¶</a></dt>
  632. <dd><p>If <tt class="docutils literal"><span class="pre">True</span></tt>, the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> will be passed to
  633. <a class="reference internal" href="#mako.cache.CacheImpl.get_or_create" title="mako.cache.CacheImpl.get_or_create"><tt class="xref py py-meth docutils literal"><span class="pre">get_or_create</span></tt></a> as the name <tt class="docutils literal"><span class="pre">'context'</span></tt>.</p>
  634. </dd></dl>
  635. <dl class="method">
  636. <dt id="mako.cache.CacheImpl.set">
  637. <tt class="descname">set</tt><big>(</big><em>key</em>, <em>value</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#mako.cache.CacheImpl.set" title="Permalink to this definition">¶</a></dt>
  638. <dd><p>Place a value in the cache.</p>
  639. <table class="docutils field-list" frame="void" rules="none">
  640. <col class="field-name" />
  641. <col class="field-body" />
  642. <tbody valign="top">
  643. <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
  644. <li><strong>key</strong> &#8211; the value&#8217;s key.</li>
  645. <li><strong>value</strong> &#8211; the value.</li>
  646. <li><strong>**kw</strong> &#8211; cache configuration arguments.</li>
  647. </ul>
  648. </td>
  649. </tr>
  650. </tbody>
  651. </table>
  652. </dd></dl>
  653. </dd></dl>
  654. <dl class="function">
  655. <dt id="mako.cache.register_plugin">
  656. <tt class="descclassname">mako.cache.</tt><tt class="descname">register_plugin</tt><big>(</big><em>self</em>, <em>name</em>, <em>modulepath</em>, <em>objname</em><big>)</big><a class="headerlink" href="#mako.cache.register_plugin" title="Permalink to this definition">¶</a></dt>
  657. <dd></dd></dl>
  658. <dl class="class">
  659. <dt id="mako.ext.beaker_cache.BeakerCacheImpl">
  660. <em class="property">class </em><tt class="descclassname">mako.ext.beaker_cache.</tt><tt class="descname">BeakerCacheImpl</tt><big>(</big><em>cache</em><big>)</big><a class="headerlink" href="#mako.ext.beaker_cache.BeakerCacheImpl" title="Permalink to this definition">¶</a></dt>
  661. <dd><p>Bases: <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">mako.cache.CacheImpl</span></tt></a></p>
  662. <p>A <a class="reference internal" href="#mako.cache.CacheImpl" title="mako.cache.CacheImpl"><tt class="xref py py-class docutils literal"><span class="pre">CacheImpl</span></tt></a> provided for the Beaker caching system.</p>
  663. <p>This plugin is used by default, based on the default
  664. value of <tt class="docutils literal"><span class="pre">'beaker'</span></tt> for the <tt class="docutils literal"><span class="pre">cache_impl</span></tt> parameter of the
  665. <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> classes.</p>
  666. </dd></dl>
  667. </div>
  668. </div>
  669. </div>
  670. </div>
  671. <div id="docs-bottom-navigation" class="docs-navigation-links">
  672. Previous:
  673. <a href="unicode.html" title="previous chapter">The Unicode Chapter</a>
  674. <div id="docs-copyright">
  675. &copy; Copyright the Mako authors and contributors.
  676. Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3
  677. with Mako templates.
  678. </div>
  679. </div>
  680. </div>
  681. <div class="clearfix">
  682. <hr/>
  683. <div class="copyright">Website content copyright &copy; by Michael Bayer.
  684. All rights reserved. Mako and its documentation are licensed
  685. under the MIT license. mike(&)zzzcomputing.com</div>
  686. </div>
  687. </div>
  688. </body>
  689. </html>