<?xml version="1.0" encoding="ascii"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>genshi.template.loader.TemplateLoader</title> <link rel="stylesheet" href="epydoc.css" type="text/css" /> <script type="text/javascript" src="epydoc.js"></script> </head> <body bgcolor="white" text="black" link="blue" vlink="#204080" alink="#204080"> <!-- ==================== NAVIGATION BAR ==================== --> <table class="navbar" border="0" width="100%" cellpadding="0" bgcolor="#a0c0ff" cellspacing="0"> <tr valign="middle"> <!-- Home link --> <th> <a href="genshi-module.html">Home</a> </th> <!-- Tree link --> <th> <a href="module-tree.html">Trees</a> </th> <!-- Index link --> <th> <a href="identifier-index.html">Indices</a> </th> <!-- Help link --> <th> <a href="help.html">Help</a> </th> <!-- Project homepage --> <th class="navbar" align="right" width="100%"> <table border="0" cellpadding="0" cellspacing="0"> <tr><th class="navbar" align="center" ><a class="navbar" target="_top" href="../index.html">Documentation Index</a></th> </tr></table></th> </tr> </table> <table width="100%" cellpadding="0" cellspacing="0"> <tr valign="top"> <td width="100%"> <span class="breadcrumbs"> <a href="genshi-module.html">Package genshi</a> :: <a href="genshi.template-module.html">Package template</a> :: <a href="genshi.template.loader-module.html">Module loader</a> :: Class TemplateLoader </span> </td> <td> <table cellpadding="0" cellspacing="0"> <!-- hide/show private --> </table> </td> </tr> </table> <!-- ==================== CLASS DESCRIPTION ==================== --> <h1 class="epydoc">Class TemplateLoader</h1><p class="nomargin-top"></p> <pre class="base-tree"> object --+ | <strong class="uidshort">TemplateLoader</strong> </pre> <hr /> <p>Responsible for loading templates from files on the specified search path.</p> <pre class="py-doctest"> <span class="py-prompt">>>> </span><span class="py-keyword">import</span> tempfile <span class="py-prompt">>>> </span>fd, path = tempfile.mkstemp(suffix=<span class="py-string">'.html'</span>, prefix=<span class="py-string">'template'</span>) <span class="py-prompt">>>> </span>os.write(fd, <span class="py-string">'<p>$var</p>'</span>) <span class="py-output">11</span> <span class="py-output"></span><span class="py-prompt">>>> </span>os.close(fd)</pre> <p>The template loader accepts a list of directory paths that are then used when searching for template files, in the given order:</p> <pre class="py-doctest"> <span class="py-prompt">>>> </span>loader = TemplateLoader([os.path.dirname(path)])</pre> <p>The <a href="genshi.template.loader.TemplateLoader-class.html#load" class="link">load()</a> method first checks the template cache whether the requested template has already been loaded. If not, it attempts to locate the template file, and returns the corresponding <a href="genshi.template.base.Template-class.html" class="link">Template</a> object:</p> <pre class="py-doctest"> <span class="py-prompt">>>> </span><span class="py-keyword">from</span> genshi.template <span class="py-keyword">import</span> MarkupTemplate <span class="py-prompt">>>> </span>template = loader.load(os.path.basename(path)) <span class="py-prompt">>>> </span>isinstance(template, MarkupTemplate) <span class="py-output">True</span></pre> <p>Template instances are cached: requesting a template with the same name results in the same instance being returned:</p> <pre class="py-doctest"> <span class="py-prompt">>>> </span>loader.load(os.path.basename(path)) <span class="py-keyword">is</span> template <span class="py-output">True</span></pre> <p>The <a href="genshi.template.loader.TemplateLoader-class.html#auto_reload" class="link">auto_reload</a> option can be used to control whether a template should be automatically reloaded when the file it was loaded from has been changed. Disable this automatic reloading to improve performance.</p> <pre class="py-doctest"> <span class="py-prompt">>>> </span>os.remove(path)</pre> <!-- ==================== INSTANCE METHODS ==================== --> <a name="section-InstanceMethods"></a> <table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr bgcolor="#70b0f0" class="table-header"> <td align="left" colspan="2" class="table-header"> <span class="table-header">Instance Methods</span></td> </tr> <tr> <td width="15%" align="right" valign="top" class="summary"> <span class="summary-type"> </span> </td><td class="summary"> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td><span class="summary-sig"><a href="genshi.template.loader.TemplateLoader-class.html#__init__" class="summary-sig-name">__init__</a>(<span class="summary-sig-arg">self</span>, <span class="summary-sig-arg">search_path</span>=<span class="summary-sig-default">None</span>, <span class="summary-sig-arg">auto_reload</span>=<span class="summary-sig-default">False</span>, <span class="summary-sig-arg">default_encoding</span>=<span class="summary-sig-default">None</span>, <span class="summary-sig-arg">max_cache_size</span>=<span class="summary-sig-default">25</span>, <span class="summary-sig-arg">default_class</span>=<span class="summary-sig-default">None</span>, <span class="summary-sig-arg">variable_lookup</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string">strict</code><code class="variable-quote">'</code></span>, <span class="summary-sig-arg">allow_exec</span>=<span class="summary-sig-default">True</span>, <span class="summary-sig-arg">callback</span>=<span class="summary-sig-default">None</span>)</span><br /> Create the template laoder.</td> <td align="right" valign="top"> </td> </tr> </table> </td> </tr> <tr> <td width="15%" align="right" valign="top" class="summary"> <span class="summary-type"> </span> </td><td class="summary"> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td><span class="summary-sig"><a href="genshi.template.loader.TemplateLoader-class.html#load" class="summary-sig-name">load</a>(<span class="summary-sig-arg">self</span>, <span class="summary-sig-arg">filename</span>, <span class="summary-sig-arg">relative_to</span>=<span class="summary-sig-default">None</span>, <span class="summary-sig-arg">cls</span>=<span class="summary-sig-default">None</span>, <span class="summary-sig-arg">encoding</span>=<span class="summary-sig-default">None</span>)</span><br /> Load the template with the given name.</td> <td align="right" valign="top"> </td> </tr> </table> </td> </tr> <tr> <td colspan="2" class="summary"> <p class="indent-wrapped-lines"><b>Inherited from <code>object</code></b>: <code>__delattr__</code>, <code>__getattribute__</code>, <code>__hash__</code>, <code>__new__</code>, <code>__reduce__</code>, <code>__reduce_ex__</code>, <code>__repr__</code>, <code>__setattr__</code>, <code>__str__</code> </p> </td> </tr> </table> <!-- ==================== STATIC METHODS ==================== --> <a name="section-StaticMethods"></a> <table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr bgcolor="#70b0f0" class="table-header"> <td align="left" colspan="2" class="table-header"> <span class="table-header">Static Methods</span></td> </tr> <tr> <td width="15%" align="right" valign="top" class="summary"> <span class="summary-type"><tt class="rst-docutils literal"><span class="pre">function</span></tt></span> </td><td class="summary"> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td><span class="summary-sig"><a href="genshi.template.loader.TemplateLoader-class.html#directory" class="summary-sig-name">directory</a>(<span class="summary-sig-arg">path</span>)</span><br /> Loader factory for loading templates from a local directory.</td> <td align="right" valign="top"> </td> </tr> </table> </td> </tr> <tr> <td width="15%" align="right" valign="top" class="summary"> <span class="summary-type"><tt class="rst-docutils literal"><span class="pre">function</span></tt></span> </td><td class="summary"> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td><span class="summary-sig"><a href="genshi.template.loader.TemplateLoader-class.html#package" class="summary-sig-name">package</a>(<span class="summary-sig-arg">name</span>, <span class="summary-sig-arg">path</span>)</span><br /> Loader factory for loading templates from egg package data.</td> <td align="right" valign="top"> </td> </tr> </table> </td> </tr> <tr> <td width="15%" align="right" valign="top" class="summary"> <span class="summary-type"><tt class="rst-docutils literal"><span class="pre">function</span></tt></span> </td><td class="summary"> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td><span class="summary-sig"><a href="genshi.template.loader.TemplateLoader-class.html#prefixed" class="summary-sig-name">prefixed</a>(<span class="summary-sig-arg">**delegates</span>)</span><br /> Factory for a load function that delegates to other loaders depending on the prefix of the requested template path.</td> <td align="right" valign="top"> </td> </tr> </table> </td> </tr> </table> <!-- ==================== INSTANCE VARIABLES ==================== --> <a name="section-InstanceVariables"></a> <table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr bgcolor="#70b0f0" class="table-header"> <td align="left" colspan="2" class="table-header"> <span class="table-header">Instance Variables</span></td> </tr> <tr> <td width="15%" align="right" valign="top" class="summary"> <span class="summary-type"> </span> </td><td class="summary"> <a name="auto_reload"></a><span class="summary-name">auto_reload</span><br /> Whether templates should be reloaded when the underlying file is changed </td> </tr> </table> <!-- ==================== PROPERTIES ==================== --> <a name="section-Properties"></a> <table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr bgcolor="#70b0f0" class="table-header"> <td align="left" colspan="2" class="table-header"> <span class="table-header">Properties</span></td> </tr> <tr> <td colspan="2" class="summary"> <p class="indent-wrapped-lines"><b>Inherited from <code>object</code></b>: <code>__class__</code> </p> </td> </tr> </table> <!-- ==================== METHOD DETAILS ==================== --> <a name="section-MethodDetails"></a> <table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr bgcolor="#70b0f0" class="table-header"> <td align="left" colspan="2" class="table-header"> <span class="table-header">Method Details</span></td> </tr> </table> <a name="__init__"></a> <div> <table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr><td> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr valign="top"><td> <h3 class="epydoc"><span class="sig"><span class="sig-name">__init__</span>(<span class="sig-arg">self</span>, <span class="sig-arg">search_path</span>=<span class="sig-default">None</span>, <span class="sig-arg">auto_reload</span>=<span class="sig-default">False</span>, <span class="sig-arg">default_encoding</span>=<span class="sig-default">None</span>, <span class="sig-arg">max_cache_size</span>=<span class="sig-default">25</span>, <span class="sig-arg">default_class</span>=<span class="sig-default">None</span>, <span class="sig-arg">variable_lookup</span>=<span class="sig-default"><code class="variable-quote">'</code><code class="variable-string">strict</code><code class="variable-quote">'</code></span>, <span class="sig-arg">allow_exec</span>=<span class="sig-default">True</span>, <span class="sig-arg">callback</span>=<span class="sig-default">None</span>)</span> <br /><em class="fname">(Constructor)</em> </h3> </td><td align="right" valign="top" > </td> </tr></table> Create the template laoder. <dl class="fields"> <dt>Parameters:</dt> <dd><ul class="nomargin-top"> <li><strong class="pname"><code>search_path</code></strong> - a list of absolute path names that should be searched for template files, or a string containing a single absolute path; alternatively, any item on the list may be a ''load function'' that is passed a filename and returns a file-like object and some metadata</li> <li><strong class="pname"><code>auto_reload</code></strong> - whether to check the last modification time of template files, and reload them if they have changed</li> <li><strong class="pname"><code>default_encoding</code></strong> - the default encoding to assume when loading templates; defaults to UTF-8</li> <li><strong class="pname"><code>max_cache_size</code></strong> - the maximum number of templates to keep in the cache</li> <li><strong class="pname"><code>default_class</code></strong> - the default <a href="genshi.template.base.Template-class.html" class="link">Template</a> subclass to use when instantiating templates</li> <li><strong class="pname"><code>variable_lookup</code></strong> - the variable lookup mechanism; either "strict" (the default), "lenient", or a custom lookup class</li> <li><strong class="pname"><code>allow_exec</code></strong> - whether to allow Python code blocks in templates</li> <li><strong class="pname"><code>callback</code></strong> - (optional) a callback function that is invoked after a template was initialized by this loader; the function is passed the template object as only argument. This callback can be used for example to add any desired filters to the template</li> </ul></dd> <dt>Overrides: object.__init__ </dt> </dl> <div class="fields"> <p><strong>See Also:</strong> <a href="genshi.template.eval.LenientLookup-class.html" class="link">LenientLookup</a>, <a href="genshi.template.eval.StrictLookup-class.html" class="link">StrictLookup</a> </p> <p><strong>Note:</strong> Changed in 0.5: Added the <code class="link">allow_exec</code> argument </p> </div></td></tr></table> </div> <a name="load"></a> <div> <table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr><td> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr valign="top"><td> <h3 class="epydoc"><span class="sig"><span class="sig-name">load</span>(<span class="sig-arg">self</span>, <span class="sig-arg">filename</span>, <span class="sig-arg">relative_to</span>=<span class="sig-default">None</span>, <span class="sig-arg">cls</span>=<span class="sig-default">None</span>, <span class="sig-arg">encoding</span>=<span class="sig-default">None</span>)</span> </h3> </td><td align="right" valign="top" > </td> </tr></table> <p>Load the template with the given name.</p> <p>If the <code class="link">filename</code> parameter is relative, this method searches the search path trying to locate a template matching the given name. If the file name is an absolute path, the search path is ignored.</p> <p>If the requested template is not found, a <a href="genshi.template.loader.TemplateNotFound-class.html" class="link">TemplateNotFound</a> exception is raised. Otherwise, a <a href="genshi.template.base.Template-class.html" class="link">Template</a> object is returned that represents the parsed template.</p> <p>Template instances are cached to avoid having to parse the same template file more than once. Thus, subsequent calls of this method with the same template file name will return the same <a href="genshi.template.base.Template-class.html" class="link">Template</a> object (unless the <tt class="rst-docutils literal"><span class="pre">auto_reload</span></tt> option is enabled and the file was changed since the last parse.)</p> <p>If the <code class="link">relative_to</code> parameter is provided, the <code class="link">filename</code> is interpreted as being relative to that path.</p> <dl class="fields"> <dt>Parameters:</dt> <dd><ul class="nomargin-top"> <li><strong class="pname"><code>filename</code></strong> - the relative path of the template file to load</li> <li><strong class="pname"><code>relative_to</code></strong> - the filename of the template from which the new template is being loaded, or <tt class="rst-docutils literal"><span class="pre">None</span></tt> if the template is being loaded directly</li> <li><strong class="pname"><code>cls</code></strong> - the class of the template object to instantiate</li> <li><strong class="pname"><code>encoding</code></strong> - the encoding of the template to load; defaults to the <tt class="rst-docutils literal"><span class="pre">default_encoding</span></tt> of the loader instance</li> </ul></dd> <dt>Returns:</dt> <dd>the loaded <a href="genshi.template.base.Template-class.html" class="link">Template</a> instance</dd> <dt>Raises:</dt> <dd><ul class="nomargin-top"> <li><code><strong class='fraise'><a href="genshi.template.loader.TemplateNotFound-class.html">TemplateNotFound</a></strong></code> - if a template with the given name could not be found</li> </ul></dd> </dl> </td></tr></table> </div> <a name="directory"></a> <div> <table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr><td> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr valign="top"><td> <h3 class="epydoc"><span class="sig"><span class="sig-name">directory</span>(<span class="sig-arg">path</span>)</span> <br /><em class="fname">Static Method</em> </h3> </td><td align="right" valign="top" > </td> </tr></table> Loader factory for loading templates from a local directory. <dl class="fields"> <dt>Parameters:</dt> <dd><ul class="nomargin-top"> <li><strong class="pname"><code>path</code></strong> - the path to the local directory containing the templates</li> </ul></dd> <dt>Returns: <tt class="rst-rst-docutils literal rst-docutils literal"><span class="pre">function</span></tt></dt> <dd>the loader function to load templates from the given directory</dd> </dl> </td></tr></table> </div> <a name="package"></a> <div> <table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr><td> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr valign="top"><td> <h3 class="epydoc"><span class="sig"><span class="sig-name">package</span>(<span class="sig-arg">name</span>, <span class="sig-arg">path</span>)</span> <br /><em class="fname">Static Method</em> </h3> </td><td align="right" valign="top" > </td> </tr></table> Loader factory for loading templates from egg package data. <dl class="fields"> <dt>Parameters:</dt> <dd><ul class="nomargin-top"> <li><strong class="pname"><code>name</code></strong> - the name of the package containing the resources</li> <li><strong class="pname"><code>path</code></strong> - the path inside the package data</li> </ul></dd> <dt>Returns: <tt class="rst-rst-docutils literal rst-docutils literal"><span class="pre">function</span></tt></dt> <dd>the loader function to load templates from the given package</dd> </dl> </td></tr></table> </div> <a name="prefixed"></a> <div> <table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white"> <tr><td> <table width="100%" cellpadding="0" cellspacing="0" border="0"> <tr valign="top"><td> <h3 class="epydoc"><span class="sig"><span class="sig-name">prefixed</span>(<span class="sig-arg">**delegates</span>)</span> <br /><em class="fname">Static Method</em> </h3> </td><td align="right" valign="top" > </td> </tr></table> <p>Factory for a load function that delegates to other loaders depending on the prefix of the requested template path.</p> <p>The prefix is stripped from the filename when passing on the load request to the delegate.</p> <pre class="py-doctest"> <span class="py-prompt">>>> </span>load = prefixed( <span class="py-more">... </span> app1 = <span class="py-keyword">lambda</span> filename: (<span class="py-string">'app1'</span>, filename, None, None), <span class="py-more">... </span> app2 = <span class="py-keyword">lambda</span> filename: (<span class="py-string">'app2'</span>, filename, None, None) <span class="py-more">... </span>) <span class="py-prompt">>>> </span><span class="py-keyword">print</span> load(<span class="py-string">'app1/foo.html'</span>) <span class="py-output">('app1', 'app1/foo.html', None, None)</span> <span class="py-output"></span><span class="py-prompt">>>> </span><span class="py-keyword">print</span> load(<span class="py-string">'app2/bar.html'</span>) <span class="py-output">('app2', 'app2/bar.html', None, None)</span></pre> <dl class="fields"> <dt>Parameters:</dt> <dd><ul class="nomargin-top"> <li><strong class="pname"><code>delegates</code></strong> - mapping of path prefixes to loader functions</li> </ul></dd> <dt>Returns: <tt class="rst-rst-docutils literal rst-docutils literal"><span class="pre">function</span></tt></dt> <dd>the loader function</dd> </dl> </td></tr></table> </div> <br /> <!-- ==================== NAVIGATION BAR ==================== --> <table class="navbar" border="0" width="100%" cellpadding="0" bgcolor="#a0c0ff" cellspacing="0"> <tr valign="middle"> <!-- Home link --> <th> <a href="genshi-module.html">Home</a> </th> <!-- Tree link --> <th> <a href="module-tree.html">Trees</a> </th> <!-- Index link --> <th> <a href="identifier-index.html">Indices</a> </th> <!-- Help link --> <th> <a href="help.html">Help</a> </th> <!-- Project homepage --> <th class="navbar" align="right" width="100%"> <table border="0" cellpadding="0" cellspacing="0"> <tr><th class="navbar" align="center" ><a class="navbar" target="_top" href="../index.html">Documentation Index</a></th> </tr></table></th> </tr> </table> <table border="0" cellpadding="0" cellspacing="0" width="100%%"> <tr> <td align="left" class="footer"> Generated by Epydoc 3.0.1 on Wed Jul 9 18:16:21 2008 </td> <td align="right" class="footer"> <a target="mainFrame" href="http://epydoc.sourceforge.net" >http://epydoc.sourceforge.net</a> </td> </tr> </table> <script type="text/javascript"> <!-- // Private objects are initially displayed (because if // javascript is turned off then we want them to be // visible); but by default, we want to hide them. So hide // them unless we have a cookie that says to show them. checkCookie(); // --> </script> </body> </html>