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
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
|
<?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 User's Guide</title>
<meta name="author" content="Ryan Tomayko" />
<meta name="date" content="2005-03-09 15:26:45 -0500 (Wed, 09 Mar 2005)" />
<meta name="copyright" content="2005, Ryan Tomayko" />
<link rel="stylesheet" href="custom.css" type="text/css" />
</head>
<body>
<div class="document" id="kid-user-s-guide">
<h1 class="title">Kid User's Guide</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Ryan Tomayko</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:rtomayko@gmail.com">rtomayko@gmail.com</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>131</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2005-03-09 15:26:45 -0500 (Wed, 09 Mar 2005)</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>2005, Ryan Tomayko</td></tr>
<tr class="field"><th class="docinfo-name">Other Formats:</th><td class="field-body"><a class="reference" href="guide.txt">Text</a></td>
</tr>
</tbody>
</table>
<p>Kid is an XML based template language that uses embedded <a class="reference" href="http://www.python.org/">Python</a> to do cool
stuff. The syntax was inspired by a number of existing template languages,
namely <a class="reference" href="http://www.w3.org/TR/xslt">XSLT</a>, <a class="reference" href="http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL">TAL</a>, and <a class="reference" href="http://www.php.net/">PHP</a>.</p>
<p>This document describes the Kid Python interface, command line tools, and
methods for configuring Kid in various web environments. For more
information about the template language, see the <a class="reference" href="language.html">Kid Language
Specification</a>.</p>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">This software is in very early stages of development and will change
significantly before a 1.0 stable release. Most of the usage described in
this document will change. No promises are being made toward backward
compatibility between versions at this point.</p>
</div>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a><ul>
<li><a class="reference" href="#why-use-kid" id="id4" name="id4">Why use Kid?</a></li>
<li><a class="reference" href="#what-types-of-xml-documents" id="id5" name="id5">What Types of XML Documents?</a></li>
<li><a class="reference" href="#template-example" id="id6" name="id6">Template Example</a></li>
<li><a class="reference" href="#a-note-on-template-design" id="id7" name="id7">A Note on Template Design</a></li>
</ul>
</li>
<li><a class="reference" href="#the-kid-package" id="id8" name="id8">The <tt class="docutils literal"><span class="pre">kid</span></tt> package</a><ul>
<li><a class="reference" href="#loading-and-executing-templates" id="id9" name="id9">Loading and Executing Templates</a><ul>
<li><a class="reference" href="#enable-import" id="id10" name="id10"><tt class="docutils literal"><span class="pre">enable_import</span></tt></a></li>
<li><a class="reference" href="#template" id="id11" name="id11"><tt class="docutils literal"><span class="pre">Template</span></tt></a></li>
<li><a class="reference" href="#load-template" id="id12" name="id12"><tt class="docutils literal"><span class="pre">load_template</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#template-classes" id="id13" name="id13">Template Classes</a><ul>
<li><a class="reference" href="#importing" id="id14" name="id14">Importing</a></li>
<li><a class="reference" href="#template-class" id="id15" name="id15"><tt class="docutils literal"><span class="pre">Template</span></tt> class</a><ul>
<li><a class="reference" href="#init-kw" id="id16" name="id16"><tt class="docutils literal"><span class="pre">__init__(**kw)</span></tt></a></li>
<li><a class="reference" href="#serialize" id="id17" name="id17"><tt class="docutils literal"><span class="pre">serialize()</span></tt></a></li>
<li><a class="reference" href="#generate" id="id18" name="id18"><tt class="docutils literal"><span class="pre">generate()</span></tt></a></li>
<li><a class="reference" href="#write" id="id19" name="id19"><tt class="docutils literal"><span class="pre">write()</span></tt></a></li>
<li><a class="reference" href="#transform" id="id20" name="id20"><tt class="docutils literal"><span class="pre">transform()</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#serialization" id="id21" name="id21">Serialization</a><ul>
<li><a class="reference" href="#xmlserializer" id="id22" name="id22"><tt class="docutils literal"><span class="pre">XMLSerializer</span></tt></a></li>
<li><a class="reference" href="#htmlserializer" id="id23" name="id23"><tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt></a></li>
<li><a class="reference" href="#common-output-methods" id="id24" name="id24">Common Output Methods</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#template-variables" id="id25" name="id25">Template Variables</a></li>
<li><a class="reference" href="#command-line-tools" id="id26" name="id26">Command Line Tools</a><ul>
<li><a class="reference" href="#template-compiler-kidc" id="id27" name="id27">Template Compiler (<tt class="docutils literal"><span class="pre">kidc</span></tt>)</a></li>
<li><a class="reference" href="#run-templates-kid" id="id28" name="id28">Run Templates (<tt class="docutils literal"><span class="pre">kid</span></tt>)</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id3" name="introduction">Introduction</a></h1>
<div class="section" id="why-use-kid">
<h2><a class="toc-backref" href="#id4" name="why-use-kid">Why use Kid?</a></h2>
<p>Kid was designed to simplify the process of generating and transforming
dynamic well-formed XML documents using Python. While there are a myriad of
tools for working with XML documents in Python, generating XML is generally
tedious, error prone, or both:</p>
<blockquote>
<ul class="simple">
<li>APIs like SAX, DOM, or ElementTree can guarantee well-formed output but
require that output documents be created entirely in Python.</li>
<li>Template languages like <a class="reference" href="http://www.cheetahtemplate.org/">Cheetah</a> or <a class="reference" href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">PTL</a> make generating text content
easy but offer little to help ensure the output is
correct/well-formed. Using text based tools to generate XML can result in
bad data as there are many issues with basic XML syntax and encoding that
need to be understood and coded for by the programmer.</li>
<li>XSLT provides much of the functionality required to generate good XML
content but requires all input to be in the form of an XML document. This
brings us back to the original problem of <em>not being able to generate XML
content safely and easily</em>.</li>
</ul>
</blockquote>
<p>Kid is an attempt to bring the benefits of these technologies together into
a single cohesive package.</p>
<p>Kid also allows the programmer to exploit the structured nature of XML by
writing filters and transformations that work at the XML infoset level. Kid
templates use generators to produce infoset items. This allows pipelines to
be created that filter and modify content as needed.</p>
</div>
<div class="section" id="what-types-of-xml-documents">
<h2><a class="toc-backref" href="#id5" name="what-types-of-xml-documents">What Types of XML Documents?</a></h2>
<p>Kid can be used to generate any kind of XML documents including XHTML, RSS,
Atom, FOAF, RDF, XBEL, XSLT, RelaxNG, Schematron, SOAP, etc.</p>
<p>XHTML is generally used for examples as it is arguably the most widely
understood XML vocabulary in existence today.</p>
</div>
<div class="section" id="template-example">
<h2><a class="toc-backref" href="#id6" name="template-example">Template Example</a></h2>
<p>Kid template files are well-formed XML documents with embedded Python used
for generating and controlling dynamic content.</p>
<p>The following illustrates a very basic Kid Template:</p>
<pre class="literal-block">
<?xml version='1.0' encoding='utf-8'?>
<?python
import time
title = "A Kid Template"
?>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:py="http://purl.org/kid/ns#"
>
<head>
<title py:content="title">
This is replaced with the value of the title variable.
</title>
</head>
<body>
<p>
The current time is ${time.strftime('%C %c')}.
</p>
</body>
</html>
</pre>
<p>Kid supports more advanced features such as conditionals (<tt class="docutils literal"><span class="pre">py:if</span></tt>),
iteration (<tt class="docutils literal"><span class="pre">py:for</span></tt>), and reusable sub templates (<tt class="docutils literal"><span class="pre">py:def</span></tt>). For more
information on kid template syntax, see the <a class="reference" href="language.html">Kid Language Specification</a>.</p>
<p>Kid templates should use the <tt class="docutils literal"><span class="pre">.kid</span></tt> file extension if importing the
template module using normal Python code is desired. The Kid import hook
extensions rely on the <tt class="docutils literal"><span class="pre">.kid</span></tt> file extension being present.</p>
</div>
<div class="section" id="a-note-on-template-design">
<h2><a class="toc-backref" href="#id7" name="a-note-on-template-design">A Note on Template Design</a></h2>
<p>It is possible to embed blocks of Python code using the <tt class="docutils literal"><span class="pre"><?python?></span></tt>
processing instruction (PI). However, the practice of embedding object model,
data persistence, and business logic code in templates is highly
discouraged. In most cases, these types of functionality should be moved
into external Python modules and imported into the template.</p>
<p>Keeping large amounts of code out of templates is important for a few
reasons:</p>
<blockquote>
<ul class="simple">
<li>Separation of content and logic. Templates are meant to model a document
format and should not be laden with code whose main concern is something
else.</li>
<li>Editors with Python support (like Emacs) will not recognize Python code
embedded in Kid templates.</li>
<li>People will call you names.</li>
</ul>
</blockquote>
<p>That being said, circumstances requiring somewhat complex formatting or
presentation logic arise often enough to incline us to include the ability
to embed blocks of real code in Templates. Template languages that help by
hindering ones ability to write a few lines of code when needed lead to even
greater convolution and general distress.</p>
<p><em>That</em> being said, there are some limitations on what types of usage the
<tt class="docutils literal"><span class="pre"><?python?></span></tt> PI may be put to. Specifically, you cannot generate output
within a code block (without feeling dirty), and all Python blocks end with
the PI.</p>
<p>You cannot do stuff like this:</p>
<pre class="literal-block">
<table>
<?python #
for row in rows: ?>
<tr><td py:content="row.colums[0]">...</td></tr>
</table>
<p><?python print 'some text and <markup/> too'?></p>
</pre>
<p>This is a feature. One of the important aspects of Kid is that it guarantees
well-formed XML output given a valid template. Allowing unstructured text
output would make this impossible.</p>
</div>
</div>
<div class="section" id="the-kid-package">
<h1><a class="toc-backref" href="#id8" name="the-kid-package">The <tt class="docutils literal"><span class="pre">kid</span></tt> package</a></h1>
<p>The <tt class="docutils literal"><span class="pre">kid</span></tt> package contains functions and classes for using templates. Kid
relies heavily on <a class="reference" href="http://effbot.org/zone/element-index.htm">ElementTree</a> and also exports much of that packages
functionality.</p>
<div class="section" id="loading-and-executing-templates">
<h2><a class="toc-backref" href="#id9" name="loading-and-executing-templates">Loading and Executing Templates</a></h2>
<div class="section" id="enable-import">
<h3><a class="toc-backref" href="#id10" name="enable-import"><tt class="docutils literal"><span class="pre">enable_import</span></tt></a></h3>
<p>The <tt class="docutils literal"><span class="pre">enable_import</span></tt> function turns on the Kid import hooks and allows
Python's native import statement to be used to access template
modules. It is generally called once at the beginning of program execution,
but calling multiple times has no adverse effects.</p>
<pre class="literal-block">
import kid
kid.enable_import()
</pre>
<a class="target" id="template-function" name="template-function"></a></div>
<div class="section" id="template">
<h3><a class="toc-backref" href="#id11" name="template"><tt class="docutils literal"><span class="pre">Template</span></tt></a></h3>
<p>Sometimes using Python's native import doesn't make sense for template
usage. In these cases, the <tt class="docutils literal"><span class="pre">kid.Template</span></tt> function can be used to load a
template module and create an instance of the module's <tt class="docutils literal"><span class="pre">Template</span></tt> class.</p>
<p>The <tt class="docutils literal"><span class="pre">kid.Template</span></tt> function requires one of the following arguments to be
provided to establish the template:</p>
<blockquote>
<dl class="docutils">
<dt>file</dt>
<dd>The template should be loaded from the file specified. If a compiled
version of template exists, it will be loaded. If not, the template is
loaded and an attempt will be made to write a compiled version.</dd>
<dt>source</dt>
<dd>The template should be loaded from the string specified. There is no
mechanism for caching string templates other than to keep a reference to
the object returned.</dd>
<dt>name</dt>
<dd>The template should be loaded by importing a module with the specified
name. This is exactly like using Python's normal import but allows
template names to be specified dynamically and also doesn't require the
import hook to be enabled.</dd>
</dl>
</blockquote>
<pre class="literal-block">
import kid
template = Template(file='test.kid', foo='bar', baz='bling')
print template.serialize()
</pre>
<pre class="literal-block">
import kid
template = Template(source='<p>$foo</p>', foo='Hello World!')
print template.serialize()
</pre>
</div>
<div class="section" id="load-template">
<h3><a class="toc-backref" href="#id12" name="load-template"><tt class="docutils literal"><span class="pre">load_template</span></tt></a></h3>
<p>The <tt class="docutils literal"><span class="pre">load_template</span></tt> function returns the module object for the template
given a template filename. This module object can be used as if the module
was loaded using Python's import statement. Use this function in cases where
you need access to the template module but the template doesn't reside on
Python's path.</p>
<pre class="literal-block">
import kid
template_module = kid.load_template('test.kid', cache=1)
template = template_module.Template(foo='bar', baz='bling')
print str(template)
</pre>
<p>Note that the <a class="reference" href="#template-function">Template function</a> usually provides a better interface for
creating templates as it automatically creates an instance of the <cite>Template</cite>
class for the module, removing a line of code or two.</p>
</div>
</div>
</div>
<div class="section" id="template-classes">
<h1><a class="toc-backref" href="#id13" name="template-classes">Template Classes</a></h1>
<p>Kid templates are converted into normal Python modules and may be used like
normal Python modules. All template modules have a uniform interface that
expose a class named <tt class="docutils literal"><span class="pre">Template</span></tt> and possibly a set of functions (one for
each <tt class="docutils literal"><span class="pre">py:def</span></tt> declared in the template).</p>
<div class="section" id="importing">
<h2><a class="toc-backref" href="#id14" name="importing">Importing</a></h2>
<p>Templates may be imported directly like any other Python module after the
Kid import hooks have been enabled. Consider the following files in a
directory on Python's <tt class="docutils literal"><span class="pre">sys.path</span></tt>:</p>
<pre class="literal-block">
file1.py
file2.py
file3.kid
</pre>
<p>The <tt class="docutils literal"><span class="pre">file1</span></tt> module may import the <tt class="docutils literal"><span class="pre">file3</span></tt> template module using the
normal Python import syntax after making a call to <tt class="docutils literal"><span class="pre">kid.enable_import()</span></tt>:</p>
<pre class="literal-block">
# enable kid import hooks
import kid
kid.enable_import()
# now import the template
import file3
print file3.serialize()
</pre>
<p>The importer checks whether a compiled version of the template exists by
looking for a <tt class="docutils literal"><span class="pre">template.pyc</span></tt> file and if not found, loads the
<tt class="docutils literal"><span class="pre">template.kid</span></tt> file, compiles it, and attempts to save it to
<tt class="docutils literal"><span class="pre">template.pyc</span></tt>. If the compiled version cannot be saved properly,
processing continues as normal; no errors or warnings are generated.</p>
</div>
<div class="section" id="template-class">
<h2><a class="toc-backref" href="#id15" name="template-class"><tt class="docutils literal"><span class="pre">Template</span></tt> class</a></h2>
<p>Each template module exports a class named "Template". An instance of a
template is obtained in one of three ways:</p>
<blockquote>
<ul class="simple">
<li>The <a class="reference" href="#template-function">Template function</a>.</li>
<li>Enabling the import hook, using Python's import to obtain the module,
and then retrieving the <tt class="docutils literal"><span class="pre">Template</span></tt> class.</li>
<li>Calling the <tt class="docutils literal"><span class="pre">kid.load_template</span></tt> function and then retrieving the
<tt class="docutils literal"><span class="pre">Template</span></tt> class.</li>
</ul>
</blockquote>
<p>The <tt class="docutils literal"><span class="pre">Template</span></tt> function is the preferred method of obtaining a template
instance.</p>
<p>All Template classes subclass the <tt class="docutils literal"><span class="pre">kid.BaseTemplate</span></tt> class, providing a
uniform set of methods that all templates expose. These methods are
described in the following sections.</p>
<div class="section" id="init-kw">
<h3><a class="toc-backref" href="#id16" name="init-kw"><tt class="docutils literal"><span class="pre">__init__(**kw)</span></tt></a></h3>
<p>Template instantiation takes a list of keyword arguments and maps them to
attributes on the object instance. You may pass any number of keywords
arguments and they are available as both instance attributes and as locals
to code contained in the template itself.</p>
<p>For example:</p>
<pre class="literal-block">
from mytemplate import Template
t = Template(foo='bar', hello='world')
</pre>
<p>is equivalent to:</p>
<pre class="literal-block">
from mytemplate import Template
t = Template()
t.foo = 'bar'
t.hello = 'world'
</pre>
<p>And these names are available within a template as if they were locals:</p>
<pre class="literal-block">
<p>Hello ${hello}</p>
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The names <tt class="docutils literal"><span class="pre">source</span></tt>, <tt class="docutils literal"><span class="pre">file</span></tt>, and <tt class="docutils literal"><span class="pre">name</span></tt> should be avoided because
they are used by the generic <a class="reference" href="#template-function">Template Function</a>.</p>
</div>
<a class="target" id="serialze" name="serialze"></a></div>
<div class="section" id="serialize">
<h3><a class="toc-backref" href="#id17" name="serialize"><tt class="docutils literal"><span class="pre">serialize()</span></tt></a></h3>
<p>Execute the template and return the result as one big string.</p>
<pre class="literal-block">
def serialize(encoding=None, fragment=0, output=None)
</pre>
<p>This method returns a string containing the output of the template encoded
using the character encoding specified by the <tt class="docutils literal"><span class="pre">encoding</span></tt> argument. If no
encoding is specified, "utf-8" is used.</p>
<p>The <tt class="docutils literal"><span class="pre">fragment</span></tt> argument specifies whether prologue information such as the
XML declaration (<tt class="docutils literal"><span class="pre"><?xml</span> <span class="pre">...?></span></tt>) and/or DOCTYPE should be output. Set to a
truth value if you need to generate XML suitable for insertion into another
document.</p>
<p>The <tt class="docutils literal"><span class="pre">output</span></tt> argument specifies the serialization method that should be
used. This can be a string or a <tt class="docutils literal"><span class="pre">Serializer</span></tt> instance.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">__str__</span></tt> method is overridden to use this same function so that
calls like <tt class="docutils literal"><span class="pre">str(t)</span></tt>, where <tt class="docutils literal"><span class="pre">t</span></tt> is a template instance, are equivalent
to calling <tt class="docutils literal"><span class="pre">t.serialize()</span></tt>.</p>
</div>
</div>
<div class="section" id="generate">
<h3><a class="toc-backref" href="#id18" name="generate"><tt class="docutils literal"><span class="pre">generate()</span></tt></a></h3>
<p>Execute the template and generate serialized output incrementally.</p>
<pre class="literal-block">
def generate(encoding=None, fragment=0, output=None)
</pre>
<p>This method returns an iterator that yields an encoded string for each
iteration. The iteration ends when the template is done executing.</p>
<p>See the <a class="reference" href="#id2">serialize</a> method for more info on the <tt class="docutils literal"><span class="pre">encoding</span></tt>, <tt class="docutils literal"><span class="pre">fragment</span></tt>,
and <tt class="docutils literal"><span class="pre">output</span></tt> arguments.</p>
</div>
<div class="section" id="write">
<h3><a class="toc-backref" href="#id19" name="write"><tt class="docutils literal"><span class="pre">write()</span></tt></a></h3>
<p>Execute the template and write output to file.</p>
<pre class="literal-block">
def write(file, encoding=None, fragment=0, output=None)
</pre>
<p>This method writes the processed template out to a file. If the file argument
is a string, a file object is created using <tt class="docutils literal"><span class="pre">open(file,</span> <span class="pre">'wb')</span></tt>. If the file
argument is a file-like object (supports <tt class="docutils literal"><span class="pre">write</span></tt>), it is used directly.</p>
<p>See the <a class="reference" href="#id2">serialize</a> method for more info on the <tt class="docutils literal"><span class="pre">encoding</span></tt>, <tt class="docutils literal"><span class="pre">fragment</span></tt>,
and <tt class="docutils literal"><span class="pre">output</span></tt> arguments.</p>
</div>
<div class="section" id="transform">
<h3><a class="toc-backref" href="#id20" name="transform"><tt class="docutils literal"><span class="pre">transform()</span></tt></a></h3>
<p>This method returns a generator object that can be used to iterate over the
ElementTree objects produced by template execution. For now this method is
under-documented and its use is not recommended. If you think you need to
use it, ask about it on the mailing list.</p>
<a class="target" id="id2" name="id2"></a></div>
</div>
<div class="section" id="serialization">
<h2><a class="toc-backref" href="#id21" name="serialization">Serialization</a></h2>
<p>The Template object's <tt class="docutils literal"><span class="pre">serialize</span></tt>, <tt class="docutils literal"><span class="pre">generate</span></tt>, and <tt class="docutils literal"><span class="pre">write</span></tt> methods
take an <tt class="docutils literal"><span class="pre">output</span></tt> argument that controls how the XML Infoset items
generated by a template should serialized. Kid has a modular serialization
system allowing a single template to be serialized differently based on
need.</p>
<p>The <tt class="docutils literal"><span class="pre">kid</span></tt> package exposes a set of classes that handle serialization. The
<tt class="docutils literal"><span class="pre">Serializer</span></tt> class provides some base functionality but does not perform
serialization; it provides useful utility services to subclasses. The
<tt class="docutils literal"><span class="pre">XMLSerializer</span></tt> and <tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt> classes are concrete and can be
used to serialize template output as XML or HTML, respectively.</p>
<div class="section" id="xmlserializer">
<h3><a class="toc-backref" href="#id22" name="xmlserializer"><tt class="docutils literal"><span class="pre">XMLSerializer</span></tt></a></h3>
<p>The <tt class="docutils literal"><span class="pre">XMLSerializer</span></tt> has the the following options, which can be set when
an instance is constructed, or afterwards as instance attributes:</p>
<dl class="docutils">
<dt>encoding</dt>
<dd>The character encoding that should be used when serializing output. This
can be any character encoding supported by Python.</dd>
<dt>decl</dt>
<dd>Boolean specifying whether the XML declaration should be output. Note that
the <tt class="docutils literal"><span class="pre">fragment</span></tt> argument can be used to turn this off when calling the
<tt class="docutils literal"><span class="pre">serialize</span></tt>, <tt class="docutils literal"><span class="pre">generate</span></tt>, or <tt class="docutils literal"><span class="pre">write</span></tt> methods.</dd>
<dt>doctype</dt>
<dd>A 3-tuple of the form <em>(TYPE, PUBLIC, SYSTEM)</em> that specifies a DOCTYPE
that should be output. If the <tt class="docutils literal"><span class="pre">doctype</span></tt> attribute is <tt class="docutils literal"><span class="pre">None</span></tt>, no
DOCTYPE is output. Note that if the <tt class="docutils literal"><span class="pre">fragment</span></tt> argument is set, no
DOCTYPE will be output.</dd>
</dl>
<p>The following example creates a custom XML serializer for DocBook and uses
it to serialize template output:</p>
<pre class="literal-block">
from kid import Template, XMLSerializer
dt = ('article', '-//OASIS//DTD DocBook XML V4.1.2//EN',
'http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd')
serializer = XMLSerializer(encoding='ascii', decl=1, doctype=dt)
t = Template(file='example.dbk')
print t.serialize(output=serializer)
</pre>
</div>
<div class="section" id="htmlserializer">
<h3><a class="toc-backref" href="#id23" name="htmlserializer"><tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt></a></h3>
<p>The <tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt> is cabable of serializing an XML Infoset using HTML
4.01 syntax. This serializer varies from the <tt class="docutils literal"><span class="pre">XMLSerializer</span></tt> as follows:</p>
<blockquote>
<ul class="simple">
<li>No <tt class="docutils literal"><span class="pre"><?xml</span> <span class="pre">...?></span></tt> declaration.</li>
<li>HTML 4.01 DOCTYPE(s).</li>
<li>Transpose element/attribute names to upper-case by default (can be
configured to transpose to lowercase or to not transpose at all).</li>
<li>Injects a <tt class="docutils literal"><span class="pre"><META</span> <span class="pre">HTTP-EQUIV="Content-Type"</span> <span class="pre">CONTENT="text/html;</span> <span class="pre">charset=enc"></span></tt> where <em>enc</em> is the output encoding.</li>
<li>Outputs the following element's as "empty elements" (i.e. no closing
tag): <tt class="docutils literal"><span class="pre">area</span></tt>, <tt class="docutils literal"><span class="pre">base</span></tt>, <tt class="docutils literal"><span class="pre">basefont</span></tt>, <tt class="docutils literal"><span class="pre">br</span></tt>, <tt class="docutils literal"><span class="pre">col</span></tt>, <tt class="docutils literal"><span class="pre">frame</span></tt>,
<tt class="docutils literal"><span class="pre">hr</span></tt>, <tt class="docutils literal"><span class="pre">img</span></tt>, <tt class="docutils literal"><span class="pre">input</span></tt>, <tt class="docutils literal"><span class="pre">isindex</span></tt>, <tt class="docutils literal"><span class="pre">link</span></tt>, <tt class="docutils literal"><span class="pre">meta</span></tt>, <tt class="docutils literal"><span class="pre">param</span></tt>.</li>
<li>No such thing as short-form elements: <tt class="docutils literal"><span class="pre"><elem</span> <span class="pre">/></span></tt>. All elements (except
for empty elements) must have a full end tag.</li>
<li>Does not escape reserved characters in <tt class="docutils literal"><span class="pre"><SCRIPT></span></tt> and <tt class="docutils literal"><span class="pre"><STYLE></span></tt>
blocks. This includes less-than signs and ampersands.</li>
<li>Boolean attributes are output without a value part. For example,
<tt class="docutils literal"><span class="pre"><OPTION</span> <span class="pre">SELECTED>foo</OPTION></span></tt>.</li>
<li>Discards namespace information.</li>
</ul>
</blockquote>
<p>Much of this functionality can be controlled by setting options on the
<tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt> instance. These options are as follows:</p>
<blockquote>
<dl class="docutils">
<dt>encoding</dt>
<dd>The character encoding that should be used when serializing output. This
can be any character encoding supported by Python.</dd>
<dt>doctype</dt>
<dd>A 3-tuple of the form <em>(TYPE, PUBLIC, SYSTEM)</em> that specifies a DOCTYPE
that should be output. If the <tt class="docutils literal"><span class="pre">doctype</span></tt> attribute is <tt class="docutils literal"><span class="pre">None</span></tt>, no
DOCTYPE is output.</dd>
<dt>transpose</dt>
<dd>This is a reference to a function that is called to transpose tag and
attribute names. <tt class="docutils literal"><span class="pre">string.upper</span></tt> and <tt class="docutils literal"><span class="pre">string.lower</span></tt> are generally
used here. If set to <tt class="docutils literal"><span class="pre">None</span></tt>, all tag names are output as they are in
the source document.</dd>
<dt>inject_type</dt>
<dd>Boolean specifying whether a <tt class="docutils literal"><span class="pre"><META></span></tt> tag should be inserted into the
<tt class="docutils literal"><span class="pre"><HEAD></span></tt> of the document specifying the character encoding. This is
enabled by default.</dd>
<dt>empty_elements</dt>
<dd>A <tt class="docutils literal"><span class="pre">set</span></tt> containing the names (in lower case) of the elements that do not
have closing tags. Set to <tt class="docutils literal"><span class="pre">[]</span></tt> to turn off empty_element processing.</dd>
<dt>noescape_elements</dt>
<dd>A <tt class="docutils literal"><span class="pre">set</span></tt> containing the names (in lower case) of elements whose content
should not be escaped. This defaults to <tt class="docutils literal"><span class="pre">['script',</span> <span class="pre">'style']</span></tt>. Set to
<tt class="docutils literal"><span class="pre">[]</span></tt> to turn enable escaping in all elements.</dd>
<dt>boolean_attributes</dt>
<dd>A <tt class="docutils literal"><span class="pre">set</span></tt> containing the names (in lower case) of attributes that do not
require a value part. The presence of the attribute name signifies that the
attribute value is set. Set to <tt class="docutils literal"><span class="pre">[]</span></tt> to disable boolean attribute
processing.</dd>
</dl>
</blockquote>
</div>
<div class="section" id="common-output-methods">
<h3><a class="toc-backref" href="#id24" name="common-output-methods">Common Output Methods</a></h3>
<p>The <tt class="docutils literal"><span class="pre">kid.output_methods</span></tt> dictionary contains a mapping of names to
frequently used <tt class="docutils literal"><span class="pre">Serializer</span></tt> configurations. You can pass any of these
names as the <tt class="docutils literal"><span class="pre">output</span></tt> argument in <tt class="docutils literal"><span class="pre">Template</span></tt> methods.</p>
<blockquote>
<dl class="docutils">
<dt>xml </dt>
<dd><p class="first">The <tt class="docutils literal"><span class="pre">xml</span></tt> output method is the default. It serializes the infoset
items as well-formed XML and includes a <tt class="docutils literal"><span class="pre"><?xml?></span></tt> declaration. The
serializer is created as follows:</p>
<pre class="last literal-block">
XMLSerializer(encoding='utf-8', decl=1)
</pre>
</dd>
<dt>html / html-strict </dt>
<dd><p class="first">The <tt class="docutils literal"><span class="pre">html</span></tt> and <tt class="docutils literal"><span class="pre">html-strict</span></tt> output methods use the
<tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt> to serialize the infoset. The <tt class="docutils literal"><span class="pre">HTMLSerializer</span></tt> used
has the following options set:</p>
<blockquote>
<ul class="simple">
<li>Tag and attribute names converted to uppercase
(<tt class="docutils literal"><span class="pre">HTMLSerializer.transpose</span> <span class="pre">=</span> <span class="pre">string.upper</span></tt>).</li>
<li>HTML Transitional or HTML Strict DOCTYPE.</li>
</ul>
</blockquote>
<p class="last">For more information on how content is serialized, see the
<a class="reference" href="#htmlserializer">HTMLSerializer</a> documentation.</p>
</dd>
<dt>xhtml / xhtml-strict</dt>
<dd><p class="first">The <tt class="docutils literal"><span class="pre">xhtml</span></tt> and <tt class="docutils literal"><span class="pre">xhtml-strict</span></tt> output methods use a custom
<tt class="docutils literal"><span class="pre">XMLSerializer</span></tt> to serialize the infoset. The <tt class="docutils literal"><span class="pre">XMLSerializer</span></tt> used
has the following options set:</p>
<blockquote class="last">
<ul class="simple">
<li>No <tt class="docutils literal"><span class="pre"><?xml?></span></tt> declaration.</li>
<li>XHTML Transitional or XHTML Strict DOCTYPE.</li>
</ul>
</blockquote>
</dd>
</dl>
</blockquote>
<p>The following example serializes data as HTML instead of XML:</p>
<pre class="literal-block">
>>> from kid import Template
>>> t = Template("<html xmlns="http://www.w3.org/1999/xhtml">"\
"<body><p>Hello World</p><br /></body></html>")
>>> print t.serialize(output='html-strict')
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<HTML><BODY><P>Hello World</P><BR></HTML>
</pre>
<p>Note that the DOCTYPE is output, tag names are converted to uppercase, and
some elements have no end tag.</p>
<p>The same code can be used to output XHTML as follows:</p>
<pre class="literal-block">
>>> from kid import Template
>>> t = Template("<html xmlns="http://www.w3.org/1999/xhtml">"\
"<body><p>Hello World</p><br /></body></html>")
>>> print t.serialize(output='xhtml-strict')
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<body><p>Hello World</p><br /></html>
</pre>
</div>
</div>
</div>
<div class="section" id="template-variables">
<h1><a class="toc-backref" href="#id25" name="template-variables">Template Variables</a></h1>
<p>When a template is executed, all of the template instance's attributes are
available to template code as local variables. These variables may be
specified when the <a class="reference" href="#init-kw">template is instantiated</a> or by assigning attributes to
the template instance directly.</p>
<p>The following example template relies on two arguments being provided by the
code that calls the template: <tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">message</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">message_template.kid</span></tt>:</p>
<pre class="literal-block">
#!text/html
<?xml version='1.0' encoding='utf-8'?>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:py="http://purl.org/kid/ns#">
<head>
<title>${title.upper()}</title>
</head>
<body>
<h1 py:content="title">Title</h1>
<p>
A message from Python:
</p>
<blockquote py:content="message">
Message goes here.
</blockquote>
</body>
</html>
</pre>
<p>The code that executes this template is responsible for passing the <cite>title</cite>
and <cite>message</cite> values.</p>
<p><tt class="docutils literal"><span class="pre">message.py</span></tt>:</p>
<pre class="literal-block">
from kid import Template
template = Template(file='message_template.kid',
title="Hello World",
message="Keep it simple, stupid.")
print template.serialize()
</pre>
<p>This should result in the following output:</p>
<pre class="literal-block">
<?xml version='1.0' encoding='utf-8'?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HELLO WORLD</title>
</head>
<body>
<h1>Hello World</h1>
<p>
A message from Python:
</p>
<blockquote>
Keep it simple, stupid.
</blockquote>
</body>
</html>
</pre>
</div>
<div class="section" id="command-line-tools">
<h1><a class="toc-backref" href="#id26" name="command-line-tools">Command Line Tools</a></h1>
<div class="section" id="template-compiler-kidc">
<h2><a class="toc-backref" href="#id27" name="template-compiler-kidc">Template Compiler (<tt class="docutils literal"><span class="pre">kidc</span></tt>)</a></h2>
<p>Kid templates may be compiled to Python byte-code (<tt class="docutils literal"><span class="pre">.pyc</span></tt>) files
explicitly using the <tt class="docutils literal"><span class="pre">kidc</span></tt> command. <tt class="docutils literal"><span class="pre">kidc</span></tt> is capable of compiling
individual files or recursively compiling all <tt class="docutils literal"><span class="pre">.kid</span></tt> files in a directory.</p>
<p>Use <tt class="docutils literal"><span class="pre">kidc</span> <span class="pre">--help</span></tt> for more information.</p>
<p>Note that you do not have to compile templates before using them. They are
automatically compiled the first time they are used.</p>
</div>
<div class="section" id="run-templates-kid">
<h2><a class="toc-backref" href="#id28" name="run-templates-kid">Run Templates (<tt class="docutils literal"><span class="pre">kid</span></tt>)</a></h2>
<p>Kid templates may be executed directly without having been precompiled using
the <tt class="docutils literal"><span class="pre">kid</span></tt> command as follows:</p>
<pre class="literal-block">
kid template-file.kid
</pre>
<p>Template output is written to <tt class="docutils literal"><span class="pre">stdout</span></tt> and may be redirected to a file
or piped through XML compliant tools.</p>
</div>
</div>
</div>
</body>
</html>
|
