1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
<?xml version="1.0" encoding="utf-8" ?>
<!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" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
<title>Kid 0.6 Release Notes</title>
<link rel="stylesheet" href="custom.css" type="text/css" />
</head>
<body>
<div class="document" id="kid-0-6-release-notes">
<h1 class="title">Kid 0.6 Release Notes</h1>
<p>There has been significant change in version 0.6. This includes enhancements
and modifications to the template language and python interface.</p>
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#language-and-api-changes" id="id6" name="id6">Language and API Changes</a><ul>
<li><a class="reference" href="#kid-namespace-change" id="id7" name="id7">Kid Namespace Change</a></li>
<li><a class="reference" href="#py-omit-is-now-py-strip" id="id8" name="id8"><tt class="docutils literal"><span class="pre">py:omit</span></tt> is now <tt class="docutils literal"><span class="pre">py:strip</span></tt></a></li>
<li><a class="reference" href="#python-expression-substitution-syntax" id="id9" name="id9">Python Expression Substitution Syntax</a></li>
</ul>
</li>
<li><a class="reference" href="#enhancements" id="id10" name="id10">Enhancements</a><ul>
<li><a class="reference" href="#celementtree-support" id="id11" name="id11">cElementTree Support</a></li>
<li><a class="reference" href="#death-of-comment-wart" id="id12" name="id12">Death of Comment Wart</a></li>
<li><a class="reference" href="#improved-template-api" id="id13" name="id13">Improved Template API</a><ul>
<li><a class="reference" href="#the-template-class" id="id14" name="id14">The <tt class="docutils literal"><span class="pre">Template</span></tt> Class</a></li>
<li><a class="reference" href="#the-kid-template-function" id="id15" name="id15">The <tt class="docutils literal"><span class="pre">kid.Template</span></tt> function</a></li>
</ul>
</li>
<li><a class="reference" href="#match-templates-filters" id="id16" name="id16">Match Templates / Filters</a></li>
<li><a class="reference" href="#template-inheritance" id="id17" name="id17">Template Inheritance</a></li>
<li><a class="reference" href="#dynamic-attribute-generation-py-attrs" id="id18" name="id18">Dynamic Attribute Generation (<tt class="docutils literal"><span class="pre">py:attrs</span></tt>)</a></li>
</ul>
</li>
<li><a class="reference" href="#upgrade-script" id="id19" name="id19">Upgrade Script</a></li>
</ul>
</div>
<div class="section" id="language-and-api-changes">
<h1><a class="toc-backref" href="#id6" name="language-and-api-changes">Language and API Changes</a></h1>
<p>The following changes are likely to impact existing code and
templates. Where possible, we have tried to maintain backward compatibility
but that wasn't possible in all cases.</p>
<p>The <a class="reference" href="#upgrade-script">Upgrade Script</a> can be used to bring 0.5 templates up to 0.6 syntax.</p>
<div class="section" id="kid-namespace-change">
<h2><a class="toc-backref" href="#id7" name="kid-namespace-change">Kid Namespace Change</a></h2>
<p>The Kid namespace has changed from <tt class="docutils literal"><span class="pre">http://naeblis.cx/ns/kid#</span></tt> to
<tt class="docutils literal"><span class="pre">http://purl.org/kid/ns#</span></tt>. The naeblis.cx domain is privately owned and
could expire some time in the future. purl.org is a system for establishing
and maintaining "persistent" URIs.</p>
<p>A temporary hack has been put in place to substitute references to the old
namespace URI with the new namespace URI. A warning is output when this
occurs. This will be removed in a couple of months so it is recommended that
templates be upgraded as soon as possible.</p>
</div>
<div class="section" id="py-omit-is-now-py-strip">
<h2><a class="toc-backref" href="#id8" name="py-omit-is-now-py-strip"><tt class="docutils literal"><span class="pre">py:omit</span></tt> is now <tt class="docutils literal"><span class="pre">py:strip</span></tt></a></h2>
<p>Due to initial confusion many experienced with the name <tt class="docutils literal"><span class="pre">py:omit</span></tt>, it has
been renamed <tt class="docutils literal"><span class="pre">py:strip</span></tt>. The term "omit" was often read as "omit the
element and all descendants". The new term "strip" seems to better indicate
the semantic: "strip the start and end tag but process descendants."</p>
</div>
<div class="section" id="python-expression-substitution-syntax">
<h2><a class="toc-backref" href="#id9" name="python-expression-substitution-syntax">Python Expression Substitution Syntax</a></h2>
<p>The syntax of brace expansions has been modified match more closely with
existing Python substitution syntax. In 0.5 python expressions enclosed in
curly braces ({}) were evaluated and their results substituted. In 0.6, the
rules have changed as follows:</p>
<blockquote>
<ol class="arabic simple">
<li><tt class="docutils literal"><span class="pre">$$</span></tt> is an escape; it is replaced with a single $.</li>
<li><tt class="docutils literal"><span class="pre">$name</span></tt> substitutes a variable value.</li>
<li><tt class="docutils literal"><span class="pre">${expr}</span></tt> substitutes the result of evaluating any python expression.</li>
</ol>
</blockquote>
<p>See <a class="reference" href="language.html#python-expression-substitution-expr">Python Expression Substitution</a> in the Language Reference.</p>
<!-- warning:
The expression substitution **is not** backward compatible. If you use the
old-style brace-expansion, you will need to upgrade your templates for Kid
0.6. -->
</div>
</div>
<div class="section" id="enhancements">
<h1><a class="toc-backref" href="#id10" name="enhancements">Enhancements</a></h1>
<div class="section" id="celementtree-support">
<h2><a class="toc-backref" href="#id11" name="celementtree-support">cElementTree Support</a></h2>
<p>Kid now uses cElementTree if it is available. Preliminary tests show
moderate performance increases. In most cases, we're seeing template parse
and execution time increase by about 15%. The poor increase (relative to
other cET/ET numbers) is due to the fact that we're not using cElementTree's
native parser as it doesn't support comments or processing instructions. The
plan is to lobby the effbot organization to add these features (hint, hint:
send patches) so that we can get the huge increases people are seeing
elsewhere.</p>
<p>Kid automatically determines whether cElementTree is available and uses it
if so. If cElementTree is not available, Kid falls back on Python
ElementTree. If you want to turn off use of cElementTree, you can set the
environment variable <tt class="docutils literal"><span class="pre">KID_NOCET</span></tt> to 1.</p>
</div>
<div class="section" id="death-of-comment-wart">
<h2><a class="toc-backref" href="#id12" name="death-of-comment-wart">Death of Comment Wart</a></h2>
<p>In versions of Kid prior to 0.6, the first line of an embedded Python code
block had to be a Python comment (#). This was due to Python's whitespace
semantics. Christoph determined a process for establishing the correct indent
levels without requiring a comment as the first line.</p>
<p>Starting in Kid 0.6, a comment is no longer required to be the first line in
a <tt class="docutils literal"><span class="pre"><?python?></span></tt> processing instruction. It is also possible to have single
line code blocks:</p>
<pre class="literal-block">
<?python x = 10 ?>
</pre>
</div>
<div class="section" id="improved-template-api">
<h2><a class="toc-backref" href="#id13" name="improved-template-api">Improved Template API</a></h2>
<p>The Python interfaces have been reworked significantly and now are very
similar to Cheetah's. There are two preferred methods for accessing a
template.</p>
<div class="section" id="the-template-class">
<h3><a class="toc-backref" href="#id14" name="the-template-class">The <tt class="docutils literal"><span class="pre">Template</span></tt> Class</a></h3>
<p>The first method existed in 0.5 but was not documented well. If you have
enabled the kid import hooks, then you can import a template and create an
instance of the template by accessing the <tt class="docutils literal"><span class="pre">Template</span></tt> class exposed by the
module:</p>
<pre class="literal-block">
import kid ; kid.enable_import()
import mytemplate
template = mytemplate.Template(foo='bar', bling=1)
print template.serialize()
</pre>
<p>The primary difference from 0.5 is that template variables are passed to the
<tt class="docutils literal"><span class="pre">Template</span></tt> constructor instead of to the individual execution methods
(<tt class="docutils literal"><span class="pre">serialize</span></tt>, <tt class="docutils literal"><span class="pre">generate</span></tt>, <tt class="docutils literal"><span class="pre">write</span></tt>, <tt class="docutils literal"><span class="pre">pull</span></tt>).</p>
<p>It is also possible to set template variables after the template instance
is created by simply assigning to template object instance:</p>
<pre class="literal-block">
template = mytemplate.Template()
template.foo = 'bar'
template.bling = 1
print str(template)
</pre>
<p>Here we see another small addition: template instances implement <tt class="docutils literal"><span class="pre">__str__</span></tt>
and <tt class="docutils literal"><span class="pre">__unicode__</span></tt> built-ins. These methods are equivalent to calling
<tt class="docutils literal"><span class="pre">serialize(encoding='utf-8')</span></tt> and <tt class="docutils literal"><span class="pre">serialize(encoding='utf-16')</span></tt>,
respectively.</p>
</div>
<div class="section" id="the-kid-template-function">
<h3><a class="toc-backref" href="#id15" name="the-kid-template-function">The <tt class="docutils literal"><span class="pre">kid.Template</span></tt> function</a></h3>
<p>The <tt class="docutils literal"><span class="pre">kid.Template</span></tt> function works much like <tt class="docutils literal"><span class="pre">Template</span></tt> class
constructors but takes an additional parameter that allows the template to
be loaded from a file, string, or module name. It is sometimes easier to
manage templates as files on disk rather than as python modules.</p>
<p>Example:</p>
<pre class="literal-block">
from kid import Template
# create a template from file
template = Template(file='mytemplate.kid', foo='bar', bling=1)
# create a template from string
template = Template(source="<p>${foo}</p>", foo='bar')
# create a template from a python module name
template = Template(name='templates.mytemplate', foo='bar')
</pre>
<p>This last form is sometimes useful because it doesn't require the kid
import hook to be enabled and it also allows template names to be specified
at run-time.</p>
<p>See <a class="reference" href="guide.html#template-function">kid.Template function</a> in the User's Guide for more info.</p>
</div>
</div>
<div class="section" id="match-templates-filters">
<h2><a class="toc-backref" href="#id16" name="match-templates-filters">Match Templates / Filters</a></h2>
<p>Match Templates are a cross between XSLT's match templates and JSP tag
libraries. They allow a set of filters to be put in place that matches
infoset items generated by a template so that output can be modified.</p>
<p>While match templates provide a general purpose mechanism for transforming
XML content, it is especially useful in a couple of situations which have
driven the design:</p>
<blockquote>
<ol class="arabic simple">
<li>Creating tag libraries that inject new tags into an XML vocabulary.</li>
<li>Applying headers/footers without inserting place-holders into the
source document/template.</li>
</ol>
</blockquote>
<p>See <a class="reference" href="language.html#match-templates">Match Templates</a> in the Language Reference for more information.</p>
</div>
<div class="section" id="template-inheritance">
<h2><a class="toc-backref" href="#id17" name="template-inheritance">Template Inheritance</a></h2>
<p>Templates now support multiple inheritance of template functions
(<tt class="docutils literal"><span class="pre">py:def</span></tt>) and match templates (<tt class="docutils literal"><span class="pre">py:match</span></tt>). A template indicates that
it extends one or more other templates by setting the <tt class="docutils literal"><span class="pre">py:extends</span></tt>
attribute on the root element:</p>
<pre class="literal-block">
<?xml version='1.0' encoding='utf-8'?>
<html py:extends="'common.kid', 'forms.kid'" ...
</pre>
<p><tt class="docutils literal"><span class="pre">py:extends</span></tt> may contain template modules, Template classes, or strings
specifying template paths relative to current template file.</p>
<p>See <a class="reference" href="language.html#template-reuse">Template Reuse</a> in the Language Reference for more information.</p>
</div>
<div class="section" id="dynamic-attribute-generation-py-attrs">
<h2><a class="toc-backref" href="#id18" name="dynamic-attribute-generation-py-attrs">Dynamic Attribute Generation (<tt class="docutils literal"><span class="pre">py:attrs</span></tt>)</a></h2>
<p>A new <tt class="docutils literal"><span class="pre">py:attrs</span></tt> attribute has been added that allows attributes to be
specified using a dictionary.</p>
<p>See <a class="reference" href="language.html#dynamic-attributes-py-attrs">Dynamic Attributes</a> in the Language Reference for more information.</p>
</div>
</div>
<div class="section" id="upgrade-script">
<h1><a class="toc-backref" href="#id19" name="upgrade-script">Upgrade Script</a></h1>
<p>Due to the amount of changes in template syntax, a migration script is
provided that can upgrade kid 0.5 templates to 0.6 syntax. This includes
changing the namespace, py:strip, and new expression substitution
syntax.</p>
<p>The script can be found in the source distribution as
<tt class="docutils literal"><span class="pre">misc/upgrade-0.6.py</span></tt>. The script can take multiple file names and
upgrades each in-place while preserving a backup. For instance:</p>
<pre class="literal-block">
$ python upgrade-0.6.py path/to/template.kid
Upgraded: template.kid...
</pre>
<p>On posix systems, you can upgrade a bunch of kid templates under the current
working directory with the following command:</p>
<pre class="literal-block">
$ find . -name '*.kid' | xargs python upgrade-0.6.py
Upgraded: template1.kid...
Upgraded: template2.kid...
Upgraded: template3.kid...
Upgraded: template4.kid...
</pre>
</div>
</div>
</body>
</html>
|
