<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Library Documentation — Chameleon 2.10 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.10',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Chameleon 2.10 documentation" href="index.html" />
<link rel="next" title="Language Reference" href="reference.html" />
<link rel="prev" title="Chameleon" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="reference.html" title="Language Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Chameleon"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Chameleon 2.10 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="library-documentation">
<h1>Library Documentation<a class="headerlink" href="#library-documentation" title="Permalink to this headline">¶</a></h1>
<p>This section documents the package as a Python library. To learn about
the page template language, consult the <a class="reference internal" href="reference.html#language-reference"><em>language reference</em></a>.</p>
<div class="section" id="getting-started">
<span id="getting-started-with-cpt"></span><h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>There are several template constructor classes available, one for each
of the combinations <em>text</em> or <em>xml</em>, and <em>string</em> or <em>file</em>.</p>
<p>The file-based constructor requires an absolute path. To set up a
templates directory <em>once</em>, use the template loader class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>
<span class="n">path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">__file__</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">chameleon</span> <span class="kn">import</span> <span class="n">PageTemplateLoader</span>
<span class="n">templates</span> <span class="o">=</span> <span class="n">PageTemplateLoader</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s">"templates"</span><span class="p">))</span>
</pre></div>
</div>
<p>Then, to load a template relative to the provided path, use dictionary
syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">template</span> <span class="o">=</span> <span class="n">templates</span><span class="p">[</span><span class="s">'hello.pt'</span><span class="p">]</span>
</pre></div>
</div>
<p>Alternatively, use the appropriate template class directly. Let’s try
with a string input:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">chameleon</span> <span class="kn">import</span> <span class="n">PageTemplate</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">PageTemplate</span><span class="p">(</span><span class="s">"<div>Hello, ${name}.</div>"</span><span class="p">)</span>
</pre></div>
</div>
<p>All template instances are callable. Provide variables by keyword
argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">template</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'John'</span><span class="p">)</span>
<span class="go">'<div>Hello, John.</div>'</span>
</pre></div>
</div>
</div>
<div class="section" id="performance">
<span id="fast"></span><h2>Performance<a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h2>
<p>The template engine compiles (or <em>translates</em>) template source code
into Python byte-code. In simple templates this yields an increase in
performance of about 7 times in comparison to the reference
implementation.</p>
<p>In benchmarks for the content management system <a class="reference external" href="http://www.plone.org">Plone</a>, switching to Chameleon yields a request to
response improvement of 20-50%.</p>
</div>
<div class="section" id="extension">
<h2>Extension<a class="headerlink" href="#extension" title="Permalink to this headline">¶</a></h2>
<p>You can extend the language through the expression engine by writing
your own expression compiler.</p>
<p>Let’s try and write an expression compiler for an expression type that
will simply uppercase the supplied value. We’ll call it <tt class="docutils literal"><span class="pre">upper</span></tt>.</p>
<p>You can write such a compiler as a closure:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">ast</span>
<span class="k">def</span> <span class="nf">uppercase_expression</span><span class="p">(</span><span class="n">string</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">compiler</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">engine</span><span class="p">):</span>
<span class="n">uppercased</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">string</span><span class="o">.</span><span class="n">uppercase</span><span class="p">()</span>
<span class="n">value</span> <span class="o">=</span> <span class="n">ast</span><span class="o">.</span><span class="n">Str</span><span class="p">(</span><span class="n">uppercased</span><span class="p">)</span>
<span class="k">return</span> <span class="p">[</span><span class="n">ast</span><span class="o">.</span><span class="n">Assign</span><span class="p">(</span><span class="n">targets</span><span class="o">=</span><span class="p">[</span><span class="n">target</span><span class="p">],</span> <span class="n">value</span><span class="o">=</span><span class="n">value</span><span class="p">)]</span>
<span class="k">return</span> <span class="n">compiler</span>
</pre></div>
</div>
<p>To make it available under a certain prefix, we’ll add it to the
expression types dictionary.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">chameleon</span> <span class="kn">import</span> <span class="n">PageTemplate</span>
<span class="n">PageTemplate</span><span class="o">.</span><span class="n">expression_types</span><span class="p">[</span><span class="s">'upper'</span><span class="p">]</span> <span class="o">=</span> <span class="n">uppercase_expression</span>
</pre></div>
</div>
<p>Alternatively, you could subclass the template class and set the
attribute <tt class="docutils literal"><span class="pre">expression_types</span></tt> to a dictionary that includes your
expression:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">chameleon</span> <span class="kn">import</span> <span class="n">PageTemplateFile</span>
<span class="kn">from</span> <span class="nn">chameleon.tales</span> <span class="kn">import</span> <span class="n">PythonExpr</span>
<span class="k">class</span> <span class="nc">MyPageTemplateFile</span><span class="p">(</span><span class="n">PageTemplateFile</span><span class="p">):</span>
<span class="n">expression_types</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'python'</span><span class="p">:</span> <span class="n">PythonExpr</span><span class="p">,</span>
<span class="s">'upper'</span><span class="p">:</span> <span class="n">uppercase_expression</span>
<span class="p">}</span>
</pre></div>
</div>
<p>You can now uppercase strings <em>natively</em> in your templates:</p>
<div class="highlight-python"><pre><div tal:content="upper: hello, world" /></pre>
</div>
<p>It’s probably best to stick with a Python expression:</p>
<div class="highlight-python"><pre><div tal:content="'hello, world'.upper()" /></pre>
</div>
</div>
<div class="section" id="changes-between-1-x-and-2-x">
<span id="whats-new"></span><h2>Changes between 1.x and 2.x<a class="headerlink" href="#changes-between-1-x-and-2-x" title="Permalink to this headline">¶</a></h2>
<p>This sections describes new features, improvements and changes from
1.x to 2.x.</p>
<div class="section" id="new-parser">
<h3>New parser<a class="headerlink" href="#new-parser" title="Permalink to this headline">¶</a></h3>
<p>This series features a new, custom-built parser, implemented in pure
Python. It parses both HTML and XML inputs (the previous parser relied
on the expat system library and was more strict about its input).</p>
<p>The main benefit of the new parser is that the compiler is now able to
point to the source location of parse- and compilation errors much
more accurately. This should be a great aid in debugging these errors.</p>
</div>
<div class="section" id="compatible-output">
<h3>Compatible output<a class="headerlink" href="#compatible-output" title="Permalink to this headline">¶</a></h3>
<p>The 2.x engine matches the output of the reference implementation more
closely (usually exactly). There are less differences altogether; for
instance, the method of escaping TALES expression (usually a
semicolon) has been changed to match that of the reference
implementation.</p>
</div>
<div class="section" id="new-language-features">
<h3>New language features<a class="headerlink" href="#new-language-features" title="Permalink to this headline">¶</a></h3>
<p>This series also introduces a number of new language features:</p>
<ol class="arabic simple">
<li>Support for the <tt class="docutils literal"><span class="pre">tal:on-error</span></tt> from the reference specification
has been added.</li>
<li>Two new attributes <tt class="docutils literal"><span class="pre">tal:switch</span></tt> and <tt class="docutils literal"><span class="pre">tal:case</span></tt> have been added
to make element conditions more flexible.</li>
</ol>
</div>
<div class="section" id="code-improvements">
<h3>Code improvements<a class="headerlink" href="#code-improvements" title="Permalink to this headline">¶</a></h3>
<p>The template classes have been refactored and simplified allowing
better reuse of code and more intuitive APIs on the lower levels.</p>
</div>
<div class="section" id="expression-engine">
<h3>Expression engine<a class="headerlink" href="#expression-engine" title="Permalink to this headline">¶</a></h3>
<p>The expression engine has been redesigned to make it easier to
understand and extend. The new engine is based on the <tt class="docutils literal"><span class="pre">ast</span></tt> module
(available since Python 2.6; backports included for Python 2.5). This
means that expression compilers now need to return a valid list of AST
statements that include an assignment to the target node.</p>
</div>
<div class="section" id="compiler">
<h3>Compiler<a class="headerlink" href="#compiler" title="Permalink to this headline">¶</a></h3>
<p>The new compiler has been optimized for complex templates. As a
result, in the benchmark suite included with the package, this
compiler scores about half of the 1.x series. For most real world
applications, the engine should still perform as well as the 1.x
series.</p>
</div>
</div>
<div class="section" id="api-reference">
<h2>API reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<p>This section describes the documented API of the library.</p>
<div class="section" id="template-classes">
<h3>Template classes<a class="headerlink" href="#template-classes" title="Permalink to this headline">¶</a></h3>
<p>Use the <tt class="docutils literal"><span class="pre">PageTemplate*</span></tt> template classes to define a template from a
string or file input:</p>
<span class="target" id="module-chameleon"></span><dl class="class">
<dt id="chameleon.PageTemplate">
<em class="property">class </em><tt class="descclassname">chameleon.</tt><tt class="descname">PageTemplate</tt><big>(</big><em>body</em>, <em>**config</em><big>)</big><a class="headerlink" href="#chameleon.PageTemplate" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructor for the page template language.</p>
<p>Takes a string input as the only positional argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">template</span> <span class="o">=</span> <span class="n">PageTemplate</span><span class="p">(</span><span class="s">"<div>Hello, ${name}.</div>"</span><span class="p">)</span>
</pre></div>
</div>
<p>Configuration (keyword arguments):</p>
<blockquote>
<div><p><tt class="docutils literal"><span class="pre">default_expression</span></tt></p>
<blockquote>
<div>Set the default expression type. The default setting is
<tt class="docutils literal"><span class="pre">python</span></tt>.</div></blockquote>
<p><tt class="docutils literal"><span class="pre">encoding</span></tt></p>
<blockquote>
<div><p>The default text substitution value is a unicode string on
Python 2 or simply string on Python 3.</p>
<p>Pass an encoding to allow encoded byte string input
(e.g. UTF-8).</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">literal_false</span></tt></p>
<blockquote>
<div><p>Attributes are not dropped for a value of <tt class="docutils literal"><span class="pre">False</span></tt>. Instead,
the value is coerced to a string.</p>
<p>This setting exists to provide compatibility with the
reference implementation.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">boolean_attributes</span></tt></p>
<blockquote>
<div><p>Attributes included in this set are treated as booleans: if a
true value is provided, the attribute value is the attribute
name, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">boolean_attributes</span> <span class="o">=</span> <span class="p">{</span><span class="s">"selected"</span><span class="p">}</span>
</pre></div>
</div>
<p>If we insert an attribute with the name “selected” and
provide a true value, the attribute will be rendered:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">selected</span><span class="o">=</span><span class="s">"selected"</span>
</pre></div>
</div>
<p>If a false attribute is provided (including the empty string),
the attribute is dropped.</p>
<p>The special return value <tt class="docutils literal"><span class="pre">default</span></tt> drops or inserts the
attribute based on the value element attribute value.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">translate</span></tt></p>
<blockquote>
<div><p>Use this option to set a translation function.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">translate</span><span class="p">(</span><span class="n">msgid</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">mapping</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">context</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="o">...</span>
<span class="k">return</span> <span class="n">translation</span>
</pre></div>
</div>
<p>Note that if <tt class="docutils literal"><span class="pre">target_language</span></tt> is provided at render time,
the translation function must support this argument.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">implicit_i18n_translate</span></tt></p>
<blockquote>
<div><p>Enables implicit translation for text appearing inside
elements. Default setting is <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p>While implicit translation does work for text that includes
expression interpolation, each expression must be simply a
variable name (e.g. <tt class="docutils literal"><span class="pre">${foo}</span></tt>); otherwise, the text will not
be marked for translation.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">implicit_i18n_attributes</span></tt></p>
<blockquote>
<div><p>Any attribute contained in this set will be marked for
implicit translation. Each entry must be a lowercase string.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">implicit_i18n_attributes</span> <span class="o">=</span> <span class="nb">set</span><span class="p">([</span><span class="s">'alt'</span><span class="p">,</span> <span class="s">'title'</span><span class="p">])</span>
</pre></div>
</div>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">strict</span></tt></p>
<blockquote>
<div><p>Enabled by default. If disabled, expressions are only required
to be valid at evaluation time.</p>
<p>This setting exists to provide compatibility with the
reference implementation which compiles expressions at
evaluation time.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">trim_attribute_space</span></tt></p>
<blockquote>
<div>If set, additional attribute whitespace will be stripped.</div></blockquote>
</div></blockquote>
<p>Output is unicode on Python 2 and string on Python 3.</p>
<p>Note: The remaining classes take the same general configuration
arguments.</p>
<dl class="method">
<dt id="chameleon.PageTemplate.render">
<tt class="descname">render</tt><big>(</big><em>encoding=None</em>, <em>translate=None</em>, <em>**vars</em><big>)</big><a class="headerlink" href="#chameleon.PageTemplate.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Render template to string.</p>
<p>The <tt class="docutils literal"><span class="pre">encoding</span></tt> and <tt class="docutils literal"><span class="pre">translate</span></tt> arguments are documented in
the template class constructor. If passed to this method, they
are used instead of the class defaults.</p>
<p>Additional arguments:</p>
<blockquote>
<div><p><tt class="docutils literal"><span class="pre">target_language</span></tt></p>
<blockquote>
<div><p>This argument will be partially applied to the translation
function.</p>
<p>An alternative is thus to simply provide a custom
translation function which includes this information or
relies on a different mechanism.</p>
</div></blockquote>
</div></blockquote>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="chameleon.PageTemplateFile">
<em class="property">class </em><tt class="descclassname">chameleon.</tt><tt class="descname">PageTemplateFile</tt><big>(</big><em>filename</em>, <em>**config</em><big>)</big><a class="headerlink" href="#chameleon.PageTemplateFile" title="Permalink to this definition">¶</a></dt>
<dd><p>File-based constructor.</p>
<p>Takes a string input as the only positional argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">template</span> <span class="o">=</span> <span class="n">PageTemplateFile</span><span class="p">(</span><span class="n">absolute_path</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that the file-based template class comes with the expression
type <tt class="docutils literal"><span class="pre">load</span></tt> which loads templates relative to the provided
filename.</p>
<p>Below are listed the configuration arguments specific to
file-based templates; see the string-based template class for
general options and documentation:</p>
<p>Configuration (keyword arguments):</p>
<blockquote>
<div><p><tt class="docutils literal"><span class="pre">loader_class</span></tt></p>
<blockquote>
<div><p>The provided class will be used to create the template loader
object. The default implementation supports relative and
absolute path specs.</p>
<p>The class must accept keyword arguments <tt class="docutils literal"><span class="pre">search_path</span></tt>
(sequence of paths to search for relative a path spec) and
<tt class="docutils literal"><span class="pre">default_extension</span></tt> (if provided, this should be added to
any path spec).</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">prepend_relative_search_path</span></tt></p>
<blockquote>
<div><p>Inserts the path relative to the provided template file path
into the template search path.</p>
<p>The default setting is <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">search_path</span></tt></p>
<blockquote>
<div>If provided, this is used as the search path for the <tt class="docutils literal"><span class="pre">load:</span></tt>
expression. It must be a string or an iterable yielding a
sequence of strings.</div></blockquote>
</div></blockquote>
</dd></dl>
<dl class="class">
<dt id="chameleon.PageTextTemplate">
<em class="property">class </em><tt class="descclassname">chameleon.</tt><tt class="descname">PageTextTemplate</tt><big>(</big><em>body</em>, <em>**config</em><big>)</big><a class="headerlink" href="#chameleon.PageTextTemplate" title="Permalink to this definition">¶</a></dt>
<dd><p>Text-based template class.</p>
<p>Takes a non-XML input:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">template</span> <span class="o">=</span> <span class="n">PageTextTemplate</span><span class="p">(</span><span class="s">"Hello, ${name}."</span><span class="p">)</span>
</pre></div>
</div>
<p>This is similar to the standard library class <tt class="docutils literal"><span class="pre">string.Template</span></tt>,
but uses the expression engine to substitute variables.</p>
</dd></dl>
<dl class="class">
<dt id="chameleon.PageTextTemplateFile">
<em class="property">class </em><tt class="descclassname">chameleon.</tt><tt class="descname">PageTextTemplateFile</tt><big>(</big><em>filename</em>, <em>search_path=None</em>, <em>loader_class=<class 'chameleon.loader.TemplateLoader'></em>, <em>**config</em><big>)</big><a class="headerlink" href="#chameleon.PageTextTemplateFile" title="Permalink to this definition">¶</a></dt>
<dd><p>File-based constructor.</p>
</dd></dl>
</div>
<div class="section" id="template-loader">
<h3>Template loader<a class="headerlink" href="#template-loader" title="Permalink to this headline">¶</a></h3>
<p>Some systems have framework support for loading templates from
files. The following loader class is directly compatible with the
Pylons framework and may be adapted to other frameworks:</p>
<dl class="class">
<dt id="chameleon.chameleon.PageTemplateLoader">
<em class="property">class </em><tt class="descclassname">chameleon.</tt><tt class="descname">PageTemplateLoader</tt><big>(</big><em>search_path=None</em>, <em>default_extension=None</em>, <em>**config</em><big>)</big><a class="headerlink" href="#chameleon.chameleon.PageTemplateLoader" title="Permalink to this definition">¶</a></dt>
<dd><p>Load templates from <tt class="docutils literal"><span class="pre">search_path</span></tt> (must be a string or a list of
strings):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">templates</span> <span class="o">=</span> <span class="n">PageTemplateLoader</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
<span class="n">example</span> <span class="o">=</span> <span class="n">templates</span><span class="p">[</span><span class="s">'example.pt'</span><span class="p">]</span>
</pre></div>
</div>
<p>If <tt class="docutils literal"><span class="pre">default_extension</span></tt> is provided, this will be added to inputs
that do not already have an extension:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">templates</span> <span class="o">=</span> <span class="n">PageTemplateLoader</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s">".pt"</span><span class="p">)</span>
<span class="n">example</span> <span class="o">=</span> <span class="n">templates</span><span class="p">[</span><span class="s">'example'</span><span class="p">]</span>
</pre></div>
</div>
<p>Any additional keyword arguments will be passed to the template
constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">templates</span> <span class="o">=</span> <span class="n">PageTemplateLoader</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">debug</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s">"utf-8"</span><span class="p">)</span>
</pre></div>
</div>
<dl class="method">
<dt id="chameleon.chameleon.PageTemplateLoader.PageTemplateLoader.load">
<tt class="descclassname">PageTemplateLoader.</tt><tt class="descname">load</tt><big>(</big><em>filename</em>, <em>format=None</em><big>)</big><a class="headerlink" href="#chameleon.chameleon.PageTemplateLoader.PageTemplateLoader.load" title="Permalink to this definition">¶</a></dt>
<dd><p>Load and return a template file.</p>
<p>The format parameter determines will parse the file. Valid
options are <cite>xml</cite> and <cite>text</cite>.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="id1">
<h3>Expression engine<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<p>For advanced integration, the compiler module provides support for
dynamic expression evaluation:</p>
<span class="target" id="module-chameleon.compiler"></span><dl class="class">
<dt id="chameleon.compiler.ExpressionEvaluator">
<em class="property">class </em><tt class="descclassname">chameleon.compiler.</tt><tt class="descname">ExpressionEvaluator</tt><big>(</big><em>engine</em>, <em>builtins</em><big>)</big><a class="headerlink" href="#chameleon.compiler.ExpressionEvaluator" title="Permalink to this definition">¶</a></dt>
<dd><p>Evaluates dynamic expression.</p>
<p>This is not particularly efficient, but supported for legacy
applications.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">chameleon</span> <span class="kn">import</span> <span class="n">tales</span>
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">tales</span><span class="o">.</span><span class="n">ExpressionParser</span><span class="p">({</span><span class="s">'python'</span><span class="p">:</span> <span class="n">tales</span><span class="o">.</span><span class="n">PythonExpr</span><span class="p">},</span> <span class="s">'python'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">engine</span> <span class="o">=</span> <span class="n">functools</span><span class="o">.</span><span class="n">partial</span><span class="p">(</span><span class="n">ExpressionEngine</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">evaluate</span> <span class="o">=</span> <span class="n">ExpressionEvaluator</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="p">{</span>
<span class="gp">... </span> <span class="s">'foo'</span><span class="p">:</span> <span class="s">'bar'</span><span class="p">,</span>
<span class="gp">... </span> <span class="p">})</span>
</pre></div>
</div>
<p>The evaluation function is passed the local and remote context,
the expression type and finally the expression.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">evaluate</span><span class="p">({</span><span class="s">'boo'</span><span class="p">:</span> <span class="s">'baz'</span><span class="p">},</span> <span class="p">{},</span> <span class="s">'python'</span><span class="p">,</span> <span class="s">'foo + boo'</span><span class="p">)</span>
<span class="go">'barbaz'</span>
</pre></div>
</div>
<p>The cache is now primed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">evaluate</span><span class="p">({</span><span class="s">'boo'</span><span class="p">:</span> <span class="s">'baz'</span><span class="p">},</span> <span class="p">{},</span> <span class="s">'python'</span><span class="p">,</span> <span class="s">'foo + boo'</span><span class="p">)</span>
<span class="go">'barbaz'</span>
</pre></div>
</div>
<p>Note that the call method supports currying of the expression
argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">python</span> <span class="o">=</span> <span class="n">evaluate</span><span class="p">({</span><span class="s">'boo'</span><span class="p">:</span> <span class="s">'baz'</span><span class="p">},</span> <span class="p">{},</span> <span class="s">'python'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">python</span><span class="p">(</span><span class="s">'foo + boo'</span><span class="p">)</span>
<span class="go">'barbaz'</span>
</pre></div>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Library Documentation</a><ul>
<li><a class="reference internal" href="#getting-started">Getting started</a></li>
<li><a class="reference internal" href="#performance">Performance</a></li>
<li><a class="reference internal" href="#extension">Extension</a></li>
<li><a class="reference internal" href="#changes-between-1-x-and-2-x">Changes between 1.x and 2.x</a><ul>
<li><a class="reference internal" href="#new-parser">New parser</a></li>
<li><a class="reference internal" href="#compatible-output">Compatible output</a></li>
<li><a class="reference internal" href="#new-language-features">New language features</a></li>
<li><a class="reference internal" href="#code-improvements">Code improvements</a></li>
<li><a class="reference internal" href="#expression-engine">Expression engine</a></li>
<li><a class="reference internal" href="#compiler">Compiler</a></li>
</ul>
</li>
<li><a class="reference internal" href="#api-reference">API reference</a><ul>
<li><a class="reference internal" href="#template-classes">Template classes</a></li>
<li><a class="reference internal" href="#template-loader">Template loader</a></li>
<li><a class="reference internal" href="#id1">Expression engine</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Chameleon</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="reference.html"
title="next chapter">Language Reference</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/library.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="reference.html" title="Language Reference"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Chameleon"
>previous</a> |</li>
<li><a href="index.html">Chameleon 2.10 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008-2011 by Malthe Borch and the Repoze Community.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
