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 throughkajiki.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)[source]¶
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 akajiki.template._Template
subclass that has therender
method to render the template.
- template.Template()¶
Creates a
_Template
subclass from an entity withexposed
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)[source]¶
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 asself
inside the template code.This class also makes available some global object inside the template code itself:
local
which is the instance of the templatedefined
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.
- class kajiki.xml_template._Compiler(filename, doc, mode=None, is_fragment=False, autoblocks=None, cdata_scripts=True)[source]¶
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()[source]¶
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 throughpy:def
or as apy: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)[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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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.
- processingInstruction(target, data)[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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.
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