Werkzeug

The Swiss Army Knife For Python Web Developers

Mini Templates

Werkzeug ships a minimal templating system which is useful for small scripts where you just want to generate some HTML and don’t want another dependency or full blown template engine system.

It it however not recommended to use this template system for anything else than simple content generation. The Template class can be directly imported from the werkzeug module.

This template engine recognizes ASP/PHP like blocks and executes the code in them:

t = Template('<% for u in users %>${u["username"]}\n<% endfor %>')
t.render(users=[{'username': 'John'},
                {'username': 'Jane'}])

would result in:

John
Jane

You can also create templates from files:

t = Template.from_file('test.html')

The syntax elements are a mixture of django, genshi text and mod_python templates and used internally in werkzeug components.

We do not recommend using this template engine in a real environment because is quite slow and does not provide any advanced features. For simple applications (cgi script like) this can however be sufficient.

Syntax Elements

Printing Variables:

$variable
$variable.attribute[item](some, function)(calls)
${expression} or <%py print expression %>

Keep in mind that the print statement adds a newline after the call or a whitespace if it ends with a comma.

For Loops:

<% for item in seq %>
    ...
<% endfor %>

While Loops:

<% while expression %>
    <%py break / continue %>
<% endwhile %>

If Conditions:

<% if expression %>
    ...
<% elif expression %>
    ...
<% else %>
    ...
<% endif %>

Python Expressions:

<%py
    ...
%>

<%python
    ...
%>

Note on python expressions: You cannot start a loop in a python block and continue it in another one. This example does not work:

<%python
    for item in seq:
%>
    ...

Comments:

<%#
    This is a comment
%>

Missing Variables

If you try to access a missing variable you will get back an Undefined object. You can iterate over such an object or print it and it won’t fail. However every other operation will raise an error. To test if a variable is undefined you can use this expression:

<% if variable is Undefined %>
    ...
<% endif %>

Python 2.3 Compatibility

Because of limitations in Python 2.3 it’s impossible to achieve the semi-silent variable lookup fallback. If a template relies on undefined variables it won’t execute under Python 2.3.

The Template Class

class Template

Represents a simple text based template. It’s a good idea to load such templates from files on the file system to get better debug output.

render (*args, **kwargs)
This function accepts either a dict or some keyword arguments which will then be the context the template is evaluated in. The return value will be the rendered template.
from_file (file, encoding='utf-8', errors='strict', unicode_mode=True)
Load a template from a file.

Besides the normal global functions and objects, the following functions are added to every namespace: escape, url_encode, url_quote, and url_quote_plus. You can change those by subclassing Template and overriding the default_context dict:

class MyTemplate(Template):
    default_namespace = {
        'ueber_func':       ueber_func
    }
    # Now add the old functions, too, because they are useful.
    default_namespace.update(Template.default_namespace)