================
Kid User's Guide
================

:Author: Ryan Tomayko
:Contact: rtomayko@gmail.com
:Revision: $Rev: 215 $
:Date: $Date: 2005-11-25 08:29:11 -0500 (Fri, 25 Nov 2005) $
:Copyright: 2005, Ryan Tomayko
:Other Formats: Text__

.. __: guide.txt

Kid is an XML based template language that uses embedded Python_ to do cool
stuff. The syntax was inspired by a number of existing template languages,
namely XSLT_, TAL_, and PHP_.

.. _python: http://www.python.org/
.. _xslt: http://www.w3.org/TR/xslt
.. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
.. _php: http://www.php.net/

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 `Kid Language
Specification`_.

.. _Kid Language Specification: language.html

.. contents:: Table of Contents
.. sectnum::

Introduction
============

Why use Kid?
------------

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:

* APIs like SAX, DOM, or ElementTree can guarantee well-formed output but
  require that output documents be created entirely in Python.

* Template languages like Cheetah_ or PTL_ 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.

* 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 *not being able to generate XML
  content safely and easily*.

Kid is an attempt to bring the benefits of these technologies together into
a single cohesive package.

.. _Cheetah: http://www.cheetahtemplate.org/
.. _PTL: http://www.mems-exchange.org/software/quixote/doc/PTL.html

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.

What Types of XML Documents?
----------------------------

Kid can be used to generate any kind of XML documents including XHTML, RSS,
Atom, FOAF, RDF, XBEL, XSLT, RelaxNG, Schematron, SOAP, etc.

XHTML is generally used for examples as it is arguably the most widely
understood XML vocabulary in existence today.

Template Example
----------------

Kid template files are well-formed XML documents with embedded Python used
for generating and controlling dynamic content.

The following illustrates a very basic Kid Template::

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

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 ``<?python?>``
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
``<?python?>`` 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::

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

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='<p>$foo</p>', 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::

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

.. 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 (``<?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. 

.. 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 ``<?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.


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


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>


Template Variables
==================

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 `template is instantiated`_ or by assigning attributes to
the template instance directly.

.. _template is instantiated: `__init__(**kw)`_

The following example template relies on two arguments being provided by the
code that calls the template: ``title`` and ``message``.

``message_template.kid``::

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

The code that executes this template is responsible for passing the `title`
and `message` values.

``message.py``::

  from kid import Template
  template = Template(file='message_template.kid',
                      title="Hello World",
                      message="Keep it simple, stupid.")
  print template.serialize()

This should result in the following output::

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


Command Line Tools
==================

Template Compiler (``kidc``)
----------------------------

Kid templates may be compiled to Python byte-code (``.pyc``) files
explicitly using the ``kidc`` command. ``kidc`` is capable of compiling
individual files or recursively compiling all ``.kid`` files in a directory.

Use ``kidc --help`` for more information.

Note that you do not have to compile templates before using them. They are
automatically compiled the first time they are used.

Run Templates (``kid``)
---------------------------------------------

Kid templates may be executed directly without having been precompiled using
the ``kid`` command as follows::

  kid template-file.kid

Template output is written to ``stdout`` and may be redirected to a file
or piped through XML compliant tools.
