Templess API

The public API for version 0.2 of Templess. Note that this may well change in the future, the API will 'freeze' starting version 1.0 (which might not take long, I expect after 0.3 or something).

Note that this document only describes the functionality that you are supposed to use, not functions that, even though not marked 'protected' or 'private', are used internally mostly (and only interesting for public use in very specific cases). For more information about the full API, see the documentation strings in the code.

class template(data, charset='UTF-8')

This is the main class in the code base, usually you just want to instantiate one of these, feed it some XML and ask for some XML back.

  • data

the XML, can be a string or unicode object, or a file-like object with a read() method

  • charset

the character set of the 'data' argument, if appropriate (string or file-like objects)

template.unicode(context)

Render the template and return unicode.

  • context

a dictionary containing the context for the Templess directives, see TemplessDirectives and TemplessExamples for more information

template.generate(context)

Render the template and return a generator, yielding unicode strings. For the context argument, see template.unicode() above.

template.render(context)

Render the template and return an elnode instance (see below). For the context argument, see template.unicode() above.

class cgitemplate(template, content_type='text/html; charset=UTF-8', error_template='templates/cgi-error.html', headers={})

A simple example how to use Templess in a CGI environment, see also 'example.cgi' in the Templess package.

  • template

a 'template()' instance (see above)

  • content_type

the content type

  • error_template

HTML file used for errors, can have slots for exception (string), message (string), traceback (string), tblist (list of strings) and footer (string), prints output to sys.stdout

  • headers

a dictionary used to generate the HTTP headers for the response

render(context)

Render the template and print the output to stdout.

  • context

the context for rendering, see template.unicode() above

Support classes

class node()

When Templess templates are rendered, internally a very simple tree of XML nodes is built. This is something you will not usually want to poke around in, but the node classes can be used to build a tree for interpolation.

The node class is the base class of all nodes, and will not usually be used for anything except that (so only interesting if you plan to implement new node types for some reason).

Common functionality to all nodes:

node.unicode()

Return a unicode representation of the node (XML).

node.generate()

Return a generator that yields bit of unicode.

class elnode(name, attrs, parent, charset='UTF-8')

The 'element' node type.

  • name

the name (including prefix, there is no namespace support (read: hack, namespace support in e.g. DOM or SAX is usually done by using nasty hacks and not required for most XML processing, not even if you use namespaces and prefixes)) of the element

  • attrs

a dictionary containing the node attributes

  • parent

the parent node, or None if it's the root (note: no error checking! make sure you don't use circular references and don't use textnodes as parent and such!)

  • charset

the encoding set of the name and attributes

elnode.find(name)

Returns a generator of all elements with node name name.

  • name

the node name (including prefix) of the nodes you want to find

class textnode(text, parent, charset='UTF-8')

A text node.

  • text

the text value of the node

  • parent

the parent to attach the node to

  • charset

the character set of the text argument

class cdatanode(text, parent, charset='UTF-8')

A CDATA section, see textnode() above.

class commentnode(text, parent, charset='UTF-8')

A commend node, see textnode() above.

class templessnode(name, attrs, parent, t_prefix, charset='UTF-8')

A Templess node, subclass of elnode but contains some additional functionality to process Templess directives contained by itself.

templessnode.convert(context, parent=None)

Returns a 'normal' element node with Templess directives processed.

  • context

the context to use for rendering, see template.unicode() for more details

  • parent

used internally, don't provide when calling this from code

class xmlstring(unicode)

Wrap a unicode string so it's not entitized on interpolation.

  • unicode

a unicode object containing a snippet of well-formed XML

class objectcontext(obj)

Rather scary generic wrapper around objects to allow using them as Templess context. It provides some magic that makes that if a key is requested from the context, a getattr is tried if getitem fails (so if foo['bar'] can not be found, foo.bar is tried). Only if that fails, a KeyError is raised. But that's not all, it gets better... (or worse? ;) If a value is found, if it's callable, it gets called (no args) and instead of the callable, the return value is returned. Oh, and all wrapped to allow the same nastyness on the return value, of course...

This was inspired by Zope's TAL behaviour, although still not as nasty (no acquisition) it gets close... Usually I'd advise to avoid using it, but in certain cases it may be useful...