The current time is ${time.strftime('%C %c')}.
Kid supports more advanced features such as conditionals (``py:if``), iteration (``py:for``), and reusable sub templates (``py:def``). For more information on kid template syntax, see the `Kid Language Specification`_. Kid templates should use the ``.kid`` file extension if importing the template module using normal Python code is desired. The Kid import hook extensions rely on the ``.kid`` file extension being present. A Note on Template Design ------------------------- It is possible to embed blocks of Python code using the ```` 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. Keeping large amounts of code out of templates is important for a few reasons: * 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. * Editors with Python support (like Emacs) will not recognize Python code embedded in Kid templates. * People will call you names. 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. *That* being said, there are some limitations on what types of usage the ```` 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. You cannot do stuff like this::| ... |
too'?>
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. The ``kid`` package =================== The ``kid`` package contains functions and classes for using templates. Kid relies heavily on ElementTree_ and also exports much of that packages functionality. .. _ElementTree: http://effbot.org/zone/element-index.htm Loading and Executing Templates ------------------------------- ``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.) .. _template function: ``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='$foo
', foo='Hello World!') print template.serialize() ``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. Template Classes ================ 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 ``Template`` and possibly a set of functions (one for each ``py:def`` declared in the template). Importing --------- 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 ``sys.path``:: file1.py file2.py file3.kid The ``file1`` module may import the ``file3`` template module using the normal Python import syntax after making a call to ``kid.enable_import()``:: # enable kid import hooks import kid kid.enable_import() # now import the template import file3 print file3.serialize() The importer checks whether a compiled version of the template exists by looking for a ``template.pyc`` file and if not found, loads the ``template.kid`` file, compiles it, and attempts to save it to ``template.pyc``. If the compiled version cannot be saved properly, processing continues as normal; no errors or warnings are generated. ``Template`` class ------------------ Each template module exports a class named "Template". An instance of a template is obtained in one of three ways: * The `Template function`_. * Enabling the import hook, using Python's import to obtain the module, and then retrieving the ``Template`` class. * Calling the ``kid.load_template`` function and then retrieving the ``Template`` class. The ``Template`` function is the preferred method of obtaining a template instance. All Template classes subclass the ``kid.BaseTemplate`` class, providing a uniform set of methods that all templates expose. These methods are described in the following sections. ``__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::Hello ${hello}
.. note:: The names ``source``, ``file``, and ``name`` should be avoided because they are used by the generic `Template Function`_. .. _serialze: ``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 (````) 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. .. note:: The ``__str__`` method is overridden to use this same function so that calls like ``str(t)``, where ``t`` is a template instance, are equivalent to calling ``t.serialize()``. ``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. ``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. ``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. .. _serialize: Serialization ---------------------------- The Template object's ``serialize``, ``generate``, and ``write`` methods take an ``output`` 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. The ``kid`` package exposes a set of classes that handle serialization. The ``Serializer`` class provides some base functionality but does not perform serialization; it provides useful utility services to subclasses. The ``XMLSerializer``, ``HTMLSerializer``, and ``PlainSerializer`` classes are concrete and can be used to serialize template output as XML or HTML, respectively. ``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) ``HTMLSerializer`` ~~~~~~~~~~~~~~~~~~ The ``HTMLSerializer`` is cabable of serializing an XML Infoset using HTML 4.01 syntax. This serializer varies from the ``XMLSerializer`` as follows: * No ```` 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 ```` 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: ``