2.1.1   enable_import(suffixes=None)

The enable_import function turns on the Kid import hooks and allows Python's native import statement to be used to access template modules. The template modules are generally stored in files using a .kid file extension. The optional suffixes argument can be used to pass in a list of alternate file extensions. This is useful is you wish to put you XML templates in .html files and have them importable.

It is generally called once at the beginning of program execution, but calling multiple times has no effect adverse or otherwise.

Example:

import kid
kid.enable_import()

# or

import kid
kid.enable_import(suffixes=[".html"])

There are a few very simple rules used to determine which file to load for a particular import statement. The first file matching the criteria will be loaded even if other matching files exist down the chain. The rules are so follows: 1. look for module.kid file 2. traverse the suffixes list, if supplied, looking for module.suffix 3. look for the standard Python suffixes (.py, .pyc, etc.)

2.1.2   Template

Sometimes using Python's native import doesn't make sense for template usage. In these cases, the kid.Template function can be used to load a template module and create an instance of the module's Template class.

The kid.Template function requires one of the following arguments to be provided to establish the template:

file

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.

source

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.

name

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.

import kid
template = Template(file='test.kid', foo='bar', baz='bling')
print template.serialize()

import kid
template = Template(source='<p>$foo</p>', foo='Hello World!')
print template.serialize()

2.1.3   load_template

The load_template 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.

import kid
template_module = kid.load_template('test.kid', cache=1)
template = template_module.Template(foo='bar', baz='bling')
print str(template)

Note that the Template function usually provides a better interface for creating templates as it automatically creates an instance of the Template class for the module, removing a line of code or two.

3.2.1   __init__(**kw)

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.

For example:

from mytemplate import Template
t = Template(foo='bar', hello='world')

is equivalent to:

from mytemplate import Template
t = Template()
t.foo = 'bar'
t.hello = 'world'

And these names are available within a template as if they were locals:

<p>Hello ${hello}</p>

3.2.2   serialize()

Execute the template and return the result as one big string.

def serialize(encoding=None, fragment=0, output=None)

This method returns a string containing the output of the template encoded using the character encoding specified by the encoding argument. If no encoding is specified, "utf-8" is used.

The fragment argument specifies whether prologue information such as the XML declaration (<?xml ...?>) and/or DOCTYPE should be output. Set to a truth value if you need to generate XML suitable for insertion into another document.

The output argument specifies the serialization method that should be used. This can be a string or a Serializer instance.

3.2.3   generate()

Execute the template and generate serialized output incrementally.

def generate(encoding=None, fragment=0, output=None)

This method returns an iterator that yields an encoded string for each iteration. The iteration ends when the template is done executing.

See the serialize method for more info on the encoding, fragment, and output arguments.

3.2.4   write()

Execute the template and write output to file.

def write(file, encoding=None, fragment=0, output=None)

This method writes the processed template out to a file. If the file argument is a string, a file object is created using open(file, 'wb'). If the file argument is a file-like object (supports write), it is used directly.

See the serialize method for more info on the encoding, fragment, and output arguments.

3.2.5   transform()

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.

3.3.1   XMLSerializer

The XMLSerializer has the the following options, which can be set when an instance is constructed, or afterwards as instance attributes:

encoding

The character encoding that should be used when serializing output. This can be any character encoding supported by Python.

decl

Boolean specifying whether the XML declaration should be output. Note that the fragment argument can be used to turn this off when calling the serialize, generate, or write methods.

doctype

A 3-tuple of the form (TYPE, PUBLIC, SYSTEM) that specifies a DOCTYPE that should be output. If the doctype attribute is None, no DOCTYPE is output. Note that if the fragment argument is set, no DOCTYPE will be output.

The following example creates a custom XML serializer for DocBook and uses it to serialize template output:

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)

3.3.2   HTMLSerializer

The HTMLSerializer is cabable of serializing an XML Infoset using HTML 4.01 syntax. This serializer varies from the XMLSerializer as follows:

• No <?xml ...?> declaration.
• HTML 4.01 DOCTYPE(s).
• Transpose element/attribute names to upper-case by default (can be configured to transpose to lowercase or to not transpose at all).
• Injects a <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=enc"> where enc is the output encoding.
• Outputs the following element's as "empty elements" (i.e. no closing tag): area, base, basefont, br, col, frame, hr, img, input, isindex, link, meta, param.
• No such thing as short-form elements: <elem />. All elements (except for empty elements) must have a full end tag.
• Does not escape reserved characters in <SCRIPT> and <STYLE> blocks. This includes less-than signs and ampersands.
• Boolean attributes are output without a value part. For example, <OPTION SELECTED>foo</OPTION>.
• Discards namespace information.

Much of this functionality can be controlled by setting options on the HTMLSerializer instance. These options are as follows:

encoding

The character encoding that should be used when serializing output. This can be any character encoding supported by Python.

doctype

A 3-tuple of the form (TYPE, PUBLIC, SYSTEM) that specifies a DOCTYPE that should be output. If the doctype attribute is None, no DOCTYPE is output.

transpose

This is a reference to a function that is called to transpose tag and attribute names. string.upper and string.lower are generally used here. If set to None, all tag names are output as they are in the source document.

inject_type

Boolean specifying whether a <META> tag should be inserted into the <HEAD> of the document specifying the character encoding. This is enabled by default.

empty_elements

A set containing the names (in lower case) of the elements that do not have closing tags. Set to [] to turn off empty_element processing.

noescape_elements

A set containing the names (in lower case) of elements whose content should not be escaped. This defaults to ['script', 'style']. Set to [] to turn enable escaping in all elements.

boolean_attributes

A set 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 [] to disable boolean attribute processing.

3.3.3   PlainSerializer

The PlainSerializer can be used to generate non-markup, like a CSS or Javascript file. All markup that is rendered is thrown away, and entities are resolved.

When using this serializer, your template must still be valid XML. A typical pattern might be:

<css>
/* Look &amp; Feel */
body {color: #f00}
</css>

Which renders to:

/* Look & Feel */
body {color: #f00}

3.3.4   Common Output Methods

The kid.output_methods dictionary contains a mapping of names to frequently used Serializer configurations. You can pass any of these names as the output argument in Template methods.

xml

The xml output method is the default. It serializes the infoset items as well-formed XML and includes a <?xml?> declaration. The serializer is created as follows:

XMLSerializer(encoding='utf-8', decl=1)

html / html-strict

The html and html-strict output methods use the HTMLSerializer to serialize the infoset. The HTMLSerializer used has the following options set:

• Tag and attribute names converted to uppercase (HTMLSerializer.transpose = string.upper).
• HTML Transitional or HTML Strict DOCTYPE.

For more information on how content is serialized, see the HTMLSerializer documentation.

xhtml / xhtml-strict

The xhtml and xhtml-strict output methods use a custom XMLSerializer to serialize the infoset. The XMLSerializer used has the following options set:

• No <?xml?> declaration.
• XHTML Transitional or XHTML Strict DOCTYPE.

plain

The plain output method uses PlainSerializer, which takes only an encoding argument. All markup is stripped, entities are resolved, and only the resulting text is output.

The following example serializes data as HTML instead of XML:

>>> 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>

Note that the DOCTYPE is output, tag names are converted to uppercase, and some elements have no end tag.

The same code can be used to output XHTML as follows:

>>> 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>