File: guide.txt

package info (click to toggle)
kid 0.6.3-2
links: PTS
area: main
in suites: sarge
size: 588 kB
ctags: 588
sloc: python: 2,447; makefile: 5; xml: 4
file content (673 lines) | stat: -rw-r--r-- 22,593 bytes
================
Kid User's Guide
================

:Author: Ryan Tomayko
:Contact: rtomayko@gmail.com
:Revision: $Rev: 131 $
:Date: $Date: 2005-03-09 15:26:45 -0500 (Wed, 09 Mar 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

.. warning::

  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.

.. contents:: Table of Contents

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

The ``enable_import`` 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.

::

  import kid
  kid.enable_import()


.. _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`` and ``HTMLSerializer`` 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.


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.

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.