Kajiki Runtime

It’s sometimes good to have a mental model of the Python code that Kajiki creates in order to generate your templates. This document uses several examples taken from the text templating language to illustrate the semantics of Kajiki templates. If in doubt, you can always view the Python text generated for a template by examining the py_text attribute of the generated Template class.

xml_template.XMLTemplate(filename=None, mode=None, is_fragment=False, encoding='utf-8', autoblocks=None, cdata_scripts=True, strip_text=False, base_globals=None)

Given XML source code of a Kajiki Templates parses and returns a template class.

The source code is parsed to its DOM representation by _Parser, which is then expanded to separate directives from tags by _DomTransformer and then compiled to the Intermediate Representation tree by _Compiler.

The Intermediate Representation generates the Python code which creates a new kajiki.template._Template subclass through kajiki.template.Template().

The generated code is then executed to return the newly created class.

Calling .render() on an instance of the generate class will then render the template.

class kajiki.ir.TemplateNode(mod_py=None, defs=None)

Represents the root Intermediate Representation node of a template.

Iterating over this will generate the Python code for the class that provides all the functions that are part of the template including the __main__ function that represents the template code itself.

The generated class will then be passed to kajiki.template.Template() to create a kajiki.template._Template subclass that has the render method to render the template.

template.Template()

Creates a _Template subclass from an entity with exposed functions.

Kajiki uses classes as containers of the exposed functions for convenience, but any object that can have the functions as attributes works.

To be a valid template the original entity must provide at least a __main__ function:

class Example:
    @kajiki.expose
    def __main__():
        yield "Hi"


t = kajiki.Template(Example)
output = t().render()

print(output)
"Hi"

class kajiki.template._Template(context=None)

Base Class for all compiled Kajiki Templates.

All kajiki templates created from a kajiki.ir.TemplateNode will be subclasses of this class.

As the template body code runs inside __main__ method of this class, the instance of this class is always available as self inside the template code.

This class also makes available some global object inside the template code itself:

• local which is the instance of the template

• defined which checks if the given variable is defined inside the template scope.

• Markup which marks the passed object as markup code and prevents escaping for its content.

• __kj__ which is a special object used by generated code providing features like keeping track of py:with stack or or the gettext function used to translate text.

defined(name)

Check if a variable was provided to the template or not

render()

Render the template to a string.

class kajiki.xml_template._Compiler(filename, doc, mode=None, is_fragment=False, autoblocks=None, cdata_scripts=True)

Compiles a DOM tree into IR kajiki.ir.TemplateNode.

Intermediate Representation is a tree of nodes that represent Python Code that should be generated to execute the template.

compile()

Compile the document provided by _Parser.

Returns as kajiki.ir.TemplateNode instance representing the whole tree of nodes as their intermediate representation.

The returned template will include at least a __main__ function which is the document itself including a DOCTYPE and any function declared through py:def or as a py:block.

The TemplateNode will also include the module level code specified through <?py %.

If the compiled document didn’t specify a DOCTYPE provides one at least for HTML5.

Note

As this alters the functions and mode wide code registries of the compiler compile should never be called twice or might lead to unexpected results.

class kajiki.xml_template._Parser(filename, source)

Parse an XML template into a Tree of DOM Nodes.

Nodes should then be passed to a _Compiler to be converted into the intermediate representation and then to Python Code.

characters(content)

Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity so that the Locator provides useful information.

endElement(name)

Signals the end of an element in non-namespace mode.

The name parameter contains the name of the element type, just as with the startElement event.

abstract endElementNS(name, qname)

Signals the end of an element in namespace mode.

The name parameter contains the name of the element type, just as with the startElementNS event.

abstract endPrefixMapping(prefix)

End the scope of a prefix-URI mapping.

See startPrefixMapping for details. This event will always occur after the corresponding endElement event, but the order of endPrefixMapping events is not otherwise guaranteed.

parse()

Parse an XML/HTML document to its DOM representation.

processingInstruction(target, data)

Receive notification of a processing instruction.

The Parser will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.

A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.

skippedEntity(name)

Receive notification of a skipped entity.

The Parser will invoke this method once for each entity skipped. Non-validating processors may skip entities if they have not seen the declarations (because, for example, the entity was declared in an external DTD subset). All processors may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities and the http://xml.org/sax/features/external-parameter-entities properties.

startDocument()

Receive notification of the beginning of a document.

The SAX parser will invoke this method only once, before any other methods in this interface or in DTDHandler (except for setDocumentLocator).

startElement(name, attrs)

Signals the start of an element in non-namespace mode.

The name parameter contains the raw XML 1.0 name of the element type as a string and the attrs parameter holds an instance of the Attributes class containing the attributes of the element.

abstract startElementNS(name, qname, attrs)

Signals the start of an element in namespace mode.

The name parameter contains the name of the element type as a (uri, localname) tuple, the qname parameter the raw XML 1.0 name used in the source document, and the attrs parameter holds an instance of the Attributes class containing the attributes of the element.

The uri part of the name tuple is None for elements which have no namespace.

abstract startPrefixMapping(prefix, uri)

Begin the scope of a prefix-URI Namespace mapping.

The information from this event is not necessary for normal Namespace processing: the SAX XML reader will automatically replace prefixes for element and attribute names when the http://xml.org/sax/features/namespaces feature is true (the default).

There are cases, however, when applications need to use prefixes in character data or in attribute values, where they cannot safely be expanded automatically; the start/endPrefixMapping event supplies the information to the application to expand prefixes in those contexts itself, if necessary.

Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each-other: all startPrefixMapping events will occur before the corresponding startElement event, and all endPrefixMapping events will occur after the corresponding endElement event, but their order is not guaranteed.

class kajiki.xml_template._DomTransformer(doc, strip_text=True)

Applies standard Kajiki transformations to a parsed document.

Given a document generated by Parser it applies some node transformations that are necessary before applying the compilation steps to achieve result we usually expect.

This includes things like squashing consecutive text nodes and expanding py: directives.

The Transformer mutates the original document.

transform()

Applies all the DOM transformations to the document.

Calling this twice will do nothing as the result is persisted.

Basic Expressions

Let’s start with a hello world template:

Hello, World!

This converts to the equivalent Python:

@kajiki.expose
def __call__():
    yield 'Hello, World!\n'

Slightly more verbose “hello_name.txt”:

Hello, $name!

This converts to the equivalent Python:

@kajiki.expose
def __call__():
     yield 'Hello, '
     yield name
     yield '!\n'

By default, the $-syntax picks up any identifiers following it, as well as any periods. If you want something more explicit, use the extended expression form as in “hello_arithmetic.txt”:

Hello, 2 + 2 is ${2+2}!

This converts to:

@kajiki.expose
def __call__():
    yield 'Hello, 2 + 2 is '
    yield 2+2
    yield '!'

If you wish to include a literal $, simply prefix it with a backslash.

Control Flow

Kajiki provides several tags that affect the rendering of a template. The following template “control_flow.txt” illustrates:

A{%for i in range(5)%}
    {%if i < 2%}Low{%elif i < 4%}Mid{%else%}High{%end%}$i
    {%switch i % 2%}
        {%case 0%}
            even
        {%default%}
            odd
        {%end%}{%end%}{%end%}

This yields the following Python:

@kajiki.expose
def __call__():
    yield 'A\n' # from the {%for... line
    for i in range(10):
        yield '\n        ' # from the newline and initial indent of next line
        if i < 2:
            yield 'Low'
        elif i < 4:
            yield 'Mid'
        else:
            yield 'High'
        yield i
        yield '\n        ' # from the {%if... newline and next indent
        local.__kj__.push_switch(i%2)
        # whitespace after {%switch is always stripped
        if local.__kj__.case(0):
            yield '\n            even\n        '
        else:
            yield '\n            odd\n        '
        local.__kj__.pop_switch()

Which would in turn generate the following text:

A
    Low0

        even

    Low1

        odd

    Mid2

        even

    Mid3

        odd

    High4

        even

If you want to strip whitespace before or after a tag, just replace {% with {%- (for stripping leading whitespace) or %} with -%} (for stripping trailing whitespace). If you would like to remove newlines, just end a line with a backslash. Here is the equivalent template with whitespace removed, “control_flow_ws.txt”:

A{%-for i in range(5) -%}\
    {%-if i < 2%}Low{%elif i < 4%}Mid{%else%}High{%end%}$i
    {%-switch i % 2%}\
        {%-case 0%}\
            even
        {%-default%}\
            odd
        {%-end%}\
    {%-end%}\
{%-end%}\

This would generate the following Python:

@kajiki.expose
def __call__():
    yield 'A'
    for i in range(10):
        if i < 2:
            yield 'Low'
        elif i < 4:
            yield 'Mid'
        else:
            yield 'High'
        yield i
        yield '\n'
        local.__kj__.push_switch(i % 2)
        if local.__kj__.case(0):
            yield 'even\n'
        else:
            yield 'odd\n'
        local.__kj__.pop_switch()

Which would generate the following text:

ALow0
even
Low1
odd
Mid2
even
Mid3
odd
High4
even

which is probably closer to what you wanted. There is also a shorthand syntax that allows for line-oriented control flow as seen in “control_flow_ws_short.txt”:

A\
%for i in range(5)
    %if i < 2
        Low\
    %elif i < 4
        Mid\
    %else
        High\
    {%-end%}$i
    %switch i % 2
        %case 0
            even
        %default
            odd
        %end
    %end
%end

This syntax yields exactly the same results as “control_flow_ws.txt” above.

Python Blocks

You can insert literal Python code into your template using the following syntax in “simple_py_block.txt”:

{%py%}\
    yield 'Prefix'
{%end%}\
Body

or alternatively:

%py
    yield 'Prefix'
%end
Body

or even more succinctly:

%py yield 'Prefix'
Body

all of which will generate the following Python:

def __call__():
    yield 'Prefix'
    yield 'Body'

Note in particular that the Python block can have any indentation, as long as it

is consistent (the amount of leading whitespace in the first non-empty line of the block is stripped from all lines within the block). You can insert module-level Python (imports, etc.) by using the %py% directive (or {%py%%} as in “module_py_block.txt”:

%py%
    import sys
    import re
%end
Hello
%py% import os
%end

This yields the following Python:

import sys
import re

import os

@kajiki.expose
def __call__():
    yield 'Hello'

Functions and Imports

Kajiki provides for code reuse via the %def and %import directives. First, let’s see %def in action in “simple_function.txt”:

%def evenness(n)
    %if n % 2 == 0
        even\
    %else
        odd\
    %end
%end
%for i in range(5)
$i is ${evenness(i)}
%end

This compiles to the following Python:

@kajiki.expose
def evenness(n):
    if n % 2:
        yield 'even'
    else:
        yield 'odd'

@kajiki.expose
def __call__():
    for i in range(5):
        yield i
        yield ' is '
        yield evenness(i)

The %import directive allows you to package up your functions for reuse in another template file (or even in a Python package). For instance, consider the following file “import_test.txt”:

%import "simple_function.txt" as simple_function
%for i in range(5)
$i is ${simple_function.evenness(i)}
%end

This would then compile to the following Python:

@kajiki.expose
def __call__():
    simple_function = local.__kj__.import_("simple_function.txt")
    for i in range(5):
        yield i
        yield ' is '
        yield simple_function.evenness(i)

Note that when using the %import directive, any “body” in the imported template is ignored and only functions are imported. If you actually wanted to insert the body of the imported template, you would simply call the imported template as a function itself (e.g. ${simple_function()}).

Sometimes it is convenient to pass the contents of a tag to a function. In this case, you can use the %call directive as shown in “call.txt”:

%def quote(caller, speaker)
    %for i in range(5)
Quoth $speaker, "${caller(i)}."
    %end
%end
%call(n) quote('the raven')
Nevermore $n\
%end

This results in the following Python:

@kajiki.expose
def quote(caller, speaker):
    for i in range(5):
        yield 'Quoth '
        yield speaker
        yield ', "'
        yield caller(i)
        yield '."'

@kajiki.expose
def __call__():
    @kajiki.expose
    def _fpt_lambda(n):
        yield 'Nevermore '
        yield n
    yield quote(_fpt_lambda, 'the raven')
    del _fpt_lambda

Which in turn yields the following output:

Quoth the raven, "Nevermore 0."
Quoth the raven, "Nevermore 1."
Quoth the raven, "Nevermore 2."
Quoth the raven, "Nevermore 3."
Quoth the raven, "Nevermore 4."

Includes

Sometimes you just want to pull the text of another template into your template verbatim. For this, you use the %include directive as in “include_example.txt”:

This is my story:
%include "call.txt"
Isn't it good?

which yields the following Python:

@kajiki.expose
def __call__():
    yield 'This is my story:\n'
    yield _fpt.import("simple_function.txt")()
    yield 'Isn't it good?\n'

Which of course yields:

This is my story:
Quoth the raven, "Nevermore 0."
Quoth the raven, "Nevermore 1."
Quoth the raven, "Nevermore 2."
Quoth the raven, "Nevermore 3."
Quoth the raven, "Nevermore 4."
Isn't it good?

Inheritance

Kajiki supports a concept of inheritance whereby child templates can extend parent templates, replacing their methods and “blocks” (to be defined below). For instance, consider the following template “parent.txt”:

%def greet(name)
Hello, $name!\
%end
%def sign(name)
Sincerely,
$name\
%end
${greet(to)}

%block body
It was good seeing you last Friday.  Thanks for the gift!
%end

${sign(from)}

This would generate the following Python:

@kajiki.expose
def greet(name):
    yield 'Hello, '
    yield name
    yield '!'

@kajiki.expose
def sign(name):
    yield 'Sincerely,\n'
    yield name

@kajiki.expose
def _fpt_block_body():
    yield 'It was good seeing you last Friday! Thanks for the gift!\n'

@kajiki.expose
def __call__():
    yield greet(to)
    yield '\n\n'
    yield self._fpt_block_body()
    yield '\n\n'
    yield sign(from)

Here is the corresponding “child.txt”:

%extends "parent.txt"
%def greet(name)
Dear $name:\
%end
%block body
${parent_block()}\\

And don't forget you owe me money!
%end

This would then yield the following Python:

@kajiki.expose
def greet(name):
    yield 'Dear '
    yield name
    yield ':'

@kajiki.expose
def _fpt_block_body():
    yield parent._fpt_block_body()
    yield '\n\n'
    yield 'And don\'t forget you owe me money!\n'

@kajiki.expose
def __call__():
    yield local.__kj__.extend(local.__kj__.import_('parent.txt')).__call__()

The final text would be (assuming context had to=’Mark’ and from=’Rick’:

Dear Mark:

It was good seeing you last Friday! Thanks for the gift!

And don't forget you owe me money!

Sincerely,
Rick