Mako Documentation

Using File-Based Templates

A Template can also load its template source code from a file, using the filename keyword argument:

from mako.template import Template

mytemplate = Template(filename='/docs/mytmpl.txt')
print mytemplate.render()

For improved performance, a Template which is loaded from a file can also cache the source code to its generated module on the filesystem as a regular Python module file (i.e. a .py file). To do this, just add the module_directory argument to the template:

from mako.template import Template

mytemplate = Template(filename='/docs/mytmpl.txt', module_directory='/tmp/mako_modules')
print mytemplate.render()

When the above code is rendered, a file /tmp/mako_modules/docs/mytmpl.txt.py is created containing the source code for the module. The next time a Template with the same arguments is created, this module file will be automatically re-used.

Using TemplateLookup

All of the examples thus far have dealt with the usage of a single Template object. If the code within those templates tries to locate another template resource, it will need some way to find them, using simple URI strings. For this need, the resolution of other templates from within a template is accomplished by the TemplateLookup class. This class is constructed given a list of directories in which to search for templates, as well as keyword arguments that will be passed to the Template objects it creates.

from mako.template import Template
from mako.lookup import TemplateLookup

mylookup = TemplateLookup(directories=['/docs'])
mytemplate = Template("""<%include file="header.txt"/> hello world!""", lookup=mylookup)

Above, we created a textual template which includes the file header.txt. In order for it to have somewhere to look for header.txt, we passed a TemplateLookup object to it, which will search in the directory /docs for the file header.txt.

Usually, an application will store most or all of its templates as text files on the filesystem. So far, all of our examples have been a little bit contrived in order to illustrate the basic concepts. But a real application would get most or all of its templates directly from the TemplateLookup, using the aptly named get_template method, which accepts the URI of the desired template:

from mako.template import Template
from mako.lookup import TemplateLookup

mylookup = TemplateLookup(directories=['/docs'], module_directory='/tmp/mako_modules')

def serve_template(templatename, **kwargs):
    mytemplate = mylookup.get_template(templatename)
    print mytemplate.render(**kwargs)

In the example above, we create a TemplateLookup which will look for templates in the /docs directory, and will store generated module files in the /tmp/mako_modules directory. The lookup locates templates by appending the given URI to each of its search directories; so if you gave it a URI of /etc/beans/info.txt, it would search for the file /docs/etc/beans/info.txt, else raise a TopLevelNotFound exception, which is a custom Mako exception.

When the lookup locates templates, it will also assign a uri property to the Template which is the uri passed to the get_template() call. Template uses this uri to calculate the name of its module file. So in the above example, a templatename argument of /etc/beans/info.txt will create a module file /tmp/mako_modules/etc/beans/info.txt.py.

mylookup = TemplateLookup(directories=['/docs'], 
                module_directory='/tmp/mako_modules', collection_size=500)

Using Unicode and Encoding

Both Template and TemplateLookup accept output_encoding and encoding_errors parameters which can be used to encode the output in any Python supported codec:

from mako.template import Template
from mako.lookup import TemplateLookup

mylookup = TemplateLookup(directories=['/docs'], output_encoding='utf-8', encoding_errors='replace')

mytemplate = mylookup.get_template("foo.txt")
print mytemplate.render()

When using Python 3, the render() method will return a bytes object, if output_encoding is set. Otherwise it returns a string.

Additionally, the render_unicode() method exists which will return the template output as a Python unicode object, or in Python 3 a string:

print mytemplate.render_unicode()

The above method disregards the output encoding keyword argument; you can encode yourself by saying:

print mytemplate.render_unicode().encode('utf-8', 'replace')

Note that Mako's ability to return data in any encoding and/or unicode implies that the underlying output stream of the template is a Python unicode object. This behavior is described fully in The Unicode Chapter.

Handling Exceptions

Template exceptions can occur in two distinct places. One is when you lookup, parse and compile the template, the other is when you run the template. Within the running of a template, exceptions are thrown normally from whatever Python code originated the issue. Mako has its own set of exception classes which mostly apply to the lookup and lexer/compiler stages of template construction. Mako provides some library routines that can be used to help provide Mako-specific information about any exception's stack trace, as well as formatting the exception within textual or HTML format. In all cases, the main value of these handlers is that of converting Python filenames, line numbers, and code samples into Mako template filenames, line numbers, and code samples. All lines within a stack trace which correspond to a Mako template module will be converted to be against the originating template file.

To format exception traces, the text_error_template and html_error_template functions are provided. They make usage of sys.exc_info() to get at the most recently thrown exception. Usage of these handlers usually looks like:

from mako import exceptions

try:
    template = lookup.get_template(uri)
    print template.render()
except:
    print exceptions.text_error_template().render()

Or for the HTML render function:

from mako import exceptions

try:
    template = lookup.get_template(uri)
    print template.render()
except:
    print exceptions.html_error_template().render()

The html_error_template template accepts two options: specifying full=False causes only a section of an HTML document to be rendered. Specifying css=False will disable the default stylesheet from being rendered.

E.g.:

    print exceptions.html_error_template().render(full=False)

The HTML render function is also available built-in to Template using the format_exceptions flag. In this case, any exceptions raised within the render stage of the template will result in the output being substituted with the output of html_error_template.

template = Template(filename="/foo/bar", format_exceptions=True)
print template.render()

Note that the compile stage of the above template occurs when you construct the Template itself, and no output stream is defined. Therefore exceptions which occur within the lookup/parse/compile stage will not be handled and will propagate normally. While the pre-render traceback usually will not include any Mako-specific lines anyway, it will mean that exceptions which occur previous to rendering and those which occur within rendering will be handled differently...so the try/except patterns described previously are probably of more general use.

The underlying object used by the error template functions is the RichTraceback object. This object can also be used directly to provide custom error views. Here's an example usage which describes its general API:

from mako.exceptions import RichTraceback

try:
    template = lookup.get_template(uri)
    print template.render()
except:
    traceback = RichTraceback()
    for (filename, lineno, function, line) in traceback.traceback:
        print "File %s, line %s, in %s" % (filename, lineno, function)
        print line, "\n"
    print "%s: %s" % (str(traceback.error.__class__.__name__), traceback.error)

Further information about RichTraceback is available within the module-level documentation for mako.exceptions.

Common Framework Integrations

The Mako distribution includes a little bit of helper code for the purpose of using Mako in some popular web framework scenarios. This is a brief description of whats included.

<div id="name">
  Name:
  ## TRANSLATORS: This is a proper name. See the gettext
  ## manual, section Names.
  ${_('Francois Pinard')}
</div>

# Extraction from Python source files

[python: myproj/**.py]

# Extraction from Mako templates

[mako: myproj/templates/**.html]
input_encoding = utf-8

myproj$ pybabel extract -F babel.cfg -c "TRANSLATORS:" .

#. TRANSLATORS: This is a proper name. See the gettext
#. manual, section Names.
#: myproj/templates/name.html:5
msgid "Francois Pinard"
msgstr ""

<div id="name">
  ## TRANSLATORS: This is a proper name. See the gettext
  ## manual, section Names.
  Name: ${_('Francois Pinard')}
</div>

Expression Substitution

The simplest expression is just a variable substitution. The syntax for this is the ${} construct, which is inspired by Perl, Genshi, JSP EL, and others:

this is x: ${x}

Above, the string representation of x is applied to the template's output stream. If you're wondering where x comes from, its usually from the Context supplied to the template's rendering function. If x was not supplied to the template and was not otherwise assigned locally, it evaluates to a special value UNDEFINED. More on that later.

The contents within the ${} tag are evaluated by Python directly, so full expressions are OK:

pythagorean theorem:  ${pow(x,2) + pow(y,2)}

The results of the expression are evaluated into a string result in all cases before being rendered to the output stream, such as the above example where the expression produces a numeric result.

${"this is some text" | u}

Control Structures

A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/else), loops (like while and for), as well as things like try/except. In Mako, control structures are written using the % marker followed by a regular Python control expression, and are "closed" by using another % marker with the tag "end<name>", where "<name>" is the keyword of the expression:

% if x==5:
    this is some output
% endif

The % can appear anywhere on the line as long as no text precedes it; indentation is not signficant. The full range of Python "colon" expressions are allowed here, including if/elif/else, while, for, and even def, although Mako has a built-in tag for defs which is more full-featured.

% for a in ['one', 'two', 'three', 'four', 'five']:
    % if a[0] == 't':
     its two or three
    % elif a[0] == 'f':
    four/five
    % else:
    one
    %endif
% endfor

The % sign can also be "escaped", if you actually want to emit a percent sign as the first non whitespace character on a line, by escaping it as in %%:

%% some text

    %% some more text

Comments

Comments come in two varieties. The single line comment uses ## as the first non-space characters on a line:

## this is a comment.
...text ...

A multiline version exists using <%doc> ...text... </%doc>:

<%doc>
    these are comments
    more comments
</%doc>

Newline Filters

The backslash ("\") character, placed at the end of any line, will consume the newline character before continuing to the next line:

here is a line that goes onto \
another line.

The above text evaluates to:

here is a line that goes onto another line.

Python Blocks

Any arbitrary block of python can be dropped in using the <% %> tags:

this is a template
<%
    x = db.get_resource('foo')
    y = [z.element for z in x if x.frobnizzle==5]
%>
% for elem in y:
    element: ${elem}
% endfor

Within <% %>, you're writing a regular block of Python code. While the code can appear with an arbitrary level of preceding whitespace, it has to be consistently formatted with itself. Mako's compiler will adjust the block of Python to be consistent with the surrounding generated Python code.

<%!
    import mylib
    import re

    def filter(text):
        return re.sub(r'^@', '', text)
%>

Tags

The rest of what Mako offers takes place in the form of tags. All tags use the same syntax, which is similar to an XML tag except that the first character of the tag name is a % character. The tag is closed either by a contained slash character, or an explicit closing tag:

<%include file="foo.txt"/>

<%def name="foo" buffered="True">
    this is a def
</%def>

All tags have a set of attributes which are defined for each tag. Some of these attributes are required. Also, many attributes support evaluation, meaning you can embed an expression (using ${}) inside the attribute text:

<%include file="/foo/bar/${myfile}.txt"/>

Whether or not an attribute accepts runtime evaluation depends on the type of tag and how that tag is compiled into the template. The best way to find out if you can stick an expression in is to try it ! The lexer will tell you if its not valid.

Heres a quick summary of all the tags:

<%page args="x, y, z='default'"/>

<%page cached="True" cache_type="memory"/>

<%include file="header.html"/>

    hello world

<%include file="footer.html"/>

<%include file="toolbar.html" args="current_section='members', username='ed'"/>

<%def name="myfunc(x)">
    this is myfunc, x is ${x}
</%def>

${myfunc(7)}

<%namespace file="functions.html" import="*"/>

<%inherit file="base.html"/>

<%mynamespace:somedef param="some value">
    this is the body
</%mynamespace:somedef>

<%doc>
    these are comments
    more comments
</%doc>

<%text filter="h">
    heres some fake mako ${syntax}
    <%def name="x()">${x}</%def>
</%text>

Returning early from a template

Sometimes you want to stop processing a template or <%def> method in the middle and just use the text you've accumulated so far. You can use a return statement inside a Python block to do that.

% if not len(records):
    No records found.
    <% return %>
% endif

Or perhaps:

<%
    if not len(records):
        return
%>

Calling defs from Other Files

Top level <%defs> are exported by your template's module, and can be called from the outside; including from other templates, as well as normal Python code. Calling a <%def> from another template is something like using an <%include> - except you are calling a specific function within the template, not the whole template.

The remote <%def> call is also a little bit like calling functions from other modules in Python. There is an "import" step to pull the names from another template into your own template; then the function or functions are available.

To import another template, use the <%namespace> tag:

<%namespace name="mystuff" file="mystuff.html"/>

The above tag adds a local variable "mystuff" to the current scope.

Then, just call the defs off of mystuff:

${mystuff.somedef(x=5,y=7)}

The <%namespace> tag also supports some of the other semantics of Python's import statement, including pulling names into the local variable space, or using * to represent all names, using the import attribute:

<%namespace file="mystuff.html" import="foo, bar"/>

This is just a quick intro to the concept of a namespace, which is a central Mako concept that has its own chapter in these docs. For more detail and examples, see Namespaces.

Calling defs programmatically

You can call def's programmatically from any Template object using the get_def() method, which returns a DefTemplate object. This is a Template subclass which the parent Template creates, and is usable like any other template:

from mako.template import Template

template = Template("""
    <%def name="hi(name)">
        hi ${name}!
    </%def>

    <%def name="bye(name)">
        bye ${name}!
    </%def>
""")

print template.get_def("hi").render(name="ed")
print template.get_def("bye").render(name="ed")

Defs within Defs

The def model follows regular Python rules for closures. Declaring <%def> inside another <%def> declares it within the parent's enclosing scope:

<%def name="mydef()">
    <%def name="subdef()">
        a sub def
    </%def>

    im the def, and the subcomopnent is ${subdef()}
</%def>

Just like Python, names that exist outside the inner <%def> exist inside it as well:

<%
    x = 12
%>
<%def name="outer()">
    <%
        y = 15
    %>
    <%def name="inner()">
        inner, x is ${x}, y is ${y}
    </%def>

    outer, x is ${x}, y is ${y}
</%def>

Assigning to a name inside of a def declares that name as local to the scope of that def (again, like Python itself). This means the following code will raise an error:

<%
    x = 10
%>
<%def name="somedef()">
    ## error !
    somedef, x is ${x}  
    <%
        x = 27  
    %>
</%def>

...because the assignment to x declares x as local to the scope of somedef, rendering the "outer" version unreachable in the expression that tries to render it.

Calling a def with embedded content and/or other defs

A flip-side to def within def is a def call with content. This is where you call a def, and at the same time declare a block of content (or multiple blocks) that can be used by the def being called. The main point of such a call is to create custom, nestable tags, just like any other template language's custom-tag creation system - where the external tag controls the execution of the nested tags and can communicate state to them. Only with Mako, you don't have to use any external Python modules, you can define arbitrarily nestable tags right in your templates.

To achieve this, the target def is invoked using the form <%namepacename:defname> instead of the normal ${} syntax. This syntax, introduced in Mako 0.2.3, is functionally equivalent another tag known as call, which takes the form <%call expr='namespacename.defname(args)'>. While %call is available in all versions of Mako, the newer style is probably more familiar looking. The namespace portion of the call is the name of the namespace in which the def is defined - in the most simple cases, this can be local or self to reference the current template's namespace (the difference between local and self is one of inheritance - see Built-in Namespaces for details).

When the target def is invoked, a variable caller is placed in its context which contains another namespace containing the body and other defs defined by the caller. The body itself is referenced by the method body(). Below, we build a %def that operates upon caller.body() to invoke the body of the custom tag:

<%def name="buildtable()">
    <table>
        <tr><td>
            ${caller.body()}
        </td></tr>
    </table>
</%def>

<%self:buildtable>
    I am the table body.
</%self:buildtable>

This produces the output (whitespace formatted):

<table>
    <tr><td>
        I am the table body.
    </td></tr>
</table>

Using the older %call syntax looks like:

<%def name="buildtable()">
    <table>
        <tr><td>
            ${caller.body()}
        </td></tr>
    </table>
</%def>

<%call expr="buildtable()">
    I am the table body.
</%call>

The body() can be executed multiple times or not at all. This means you can use def-call-with-content to build iterators, conditionals, etc:

<%def name="lister(count)">
    % for x in range(count):
        ${caller.body()}
    % endfor
</%def>

<%self:lister count="${3}">
    hi
</%self:lister>

Produces:

hi
hi
hi

Notice above we pass 3 as a Python expression, so that it remains as an integer.

A custom "conditional" tag:

<%def name="conditional(expression)">
    % if expression:
        ${caller.body()}
    % endif
</%def>

<%self:conditional expression="${4==4}">
    im the result
</%self:conditional>

Produces:

im the result

But that's not all. The body() function also can handle arguments, which will augment the local namespace of the body callable. The caller must define the arguments which it expects to receive from its target def using the args attribute, which is a comma-separated list of argument names. Below, our <%def> calls the body() of its caller, passing in an element of data from its argument:

<%def name="layoutdata(somedata)">
    <table>
    % for item in somedata:
        <tr>
        % for col in item:
            <td>${caller.body(col=col)}</td>
        % endfor
        </tr>
    % endfor
    </table>
</%def>

<%self:layoutdata somedata="${[[1,2,3],[4,5,6],[7,8,9]]}" args="col">\
Body data: ${col}\
</%self:layoutdata>

Produces:

<table>
   <tr>
       <td>Body data: 1</td>
       <td>Body data: 2</td>
       <td>Body data: 3</td>
   </tr>
   <tr>
       <td>Body data: 4</td>
       <td>Body data: 5</td>
       <td>Body data: 6</td>
   </tr>
   <tr>
       <td>Body data: 7</td>
       <td>Body data: 8</td>
       <td>Body data: 9</td>
   </tr>
</table>

You don't have to stick to calling just the body() function. The caller can define any number of callables, allowing the <%call> tag to produce whole layouts:

<%def name="layout()">
    ## a layout def
    <div class="mainlayout">
        <div class="header">
            ${caller.header()}
        </div>
        <div class="sidebar">
            ${caller.sidebar()}
        </div>
        <div class="content">
            ${caller.body()}
        </div>
    </div>
</%def>

## calls the layout def
<%self:layout>
    <%def name="header()">
        I am the header
    </%def>
    <%def name="sidebar()">
        <ul>
            <li>sidebar 1</li>
            <li>sidebar 2</li>
        </ul>
    </%def>

        this is the body
</%self:layout>

The above layout would produce:

<div class="mainlayout">
   <div class="header">
   I am the header
   </div>

   <div class="sidebar">
   <ul>
       <li>sidebar 1</li>
       <li>sidebar 2</li>
   </ul>
   </div>

   <div class="content">
   this is the body
   </div>
</div>

The number of things you can do with <%call> and/or the <%namespacename:defname> calling syntax is enormous. You can create form widget libraries, such as an enclosing <FORM> tag and nested HTML input elements, or portable wrapping schemes using <div> or other elements. You can create tags that interpret rows of data, such as from a database, providing the individual columns of each row to a body() callable which lays out the row any way it wants. Basically anything you'd do with a "custom tag" or tag library in some other system, Mako provides via <%def>s and plain Python callables which are invoked via <%namespacename:defname> or <%call>.

Context

The Context is the central object that is created when a template is first executed, and is responsible for handling all communication with the outside world. This includes two major components, one of which is the output buffer, which is a file-like object such as Python's StringIO or similar, and the other a dictionary of variables that can be freely referenced within a template; this dictionary is a combination of the arguments sent to the template.render() function and some built-in variables provided by Mako's runtime environment.

<%
    context.write("some programmatic text")
%>

output = template.render(attributes={})

<%
    attributes['foo'] = 'bar'
%>
'foo' attribute is: ${attributes['foo']}

All the built-in names

A one-stop shop for all the names Mako defines. Most of these names are instances of Namespace, which are described in the next section, Namespaces. Also, most of these names other than context and UNDEFINED are also present within the Context itself.

• local - the namespace of the current template, described in Built-in Namespaces
• self - the namespace of the topmost template in an inheritance chain (if any, otherwise the same as local), mostly described in Inheritance
• parent - the namespace of the parent template in an inheritance chain (otherwise undefined); see Inheritance
• next - the namespace of the next template in an inheritance chain (otherwise undefined); see Inheritance
• caller - a "mini" namespace created when using the <%call> tag to define a "def call with content"; described in Calling a def with embedded content and/or other defs
• capture - a function that calls a given def and captures its resulting content into a string, which is returned. Usage is described in Buffering
• UNDEFINED - a global singleton that is applied to all otherwise uninitialized template variables that were not located within the Context when rendering began. Is an instance of mako.runtime.Undefined, and raises an exception when its __str__() method is called.
• pageargs - this is a dictionary which is present in a template which does not define any kwargs section in its <%page> tag. All keyword arguments sent to the body() function of a template (when used via namespaces) go here by default unless otherwise defined as a page argument. If this makes no sense, it shouldn't; read the section The "body()" method.

Ways to Call Namespaces

There are essentially four ways to call a function from a namespace.

The "expression" format, as described previously. Namespaces are just Python objects with functions on them, and can be used in expressions like any other function:

${mynamespace.somefunction('some arg1', 'some arg2', arg3='some arg3', arg4='some arg4')}

Synonymous with the "expression" format is the "custom tag" format, when a "closed" tag is used. This format, introduced in Mako 0.2.3, allows the usage of a "custom" Mako tag, with the function arguments passed in using named attributes:

<%mynamespace:somefunction arg1="some arg1" arg2="some arg2" arg3="some arg3" arg4="some arg4"/>

When using tags, the values of the arguments are taken as literal strings by default. To embed Python expressions as arguments, use the embedded expression format:

<%mynamespace:somefunction arg1="${someobject.format()}" arg2="${somedef(5, 12)}"/>

The "custom tag" format is intended mainly for namespace functions which recognize body content, which in Mako is known as a "def with embedded content":

<%mynamespace:somefunction arg1="some argument" args="x, y">
    Some record: ${x}, ${y}
</%mynamespace:somefunction>

The "classic" way to call defs with embedded content is the <%call> tag:

<%call expr="mynamespace.somefunction(arg1='some argument')" args="x, y">
    Some record: ${x}, ${y}
</%call>

For information on how to construct defs that embed content from the caller, see Calling a def with embedded content and/or other defs.

Namespaces from Regular Python Modules

Namespaces can also import regular Python functions from modules. These callables need to take at least one argument, context:

A module file some/module.py might contain the callable:

def my_tag(context):
    context.write("hello world")
    return ''

A template can use this module via:

<%namespace name="hw" module="some.module"/>

${hw.my_tag()}

Note that the context argument is not needed in the call; the namespace tag creates a locally-scoped callable which takes care of it. The return '' is so that the def does not dump a None into the output stream - the return value of any def is rendered after the def completes, in addition to whatever was passed to context.write() within its body.

If your def is to be called in an "embedded content" context, that is as described in Calling a def with embedded content and/or other defs, you should use the @supports_caller decorator, which will ensure that Mako will ensure the correct "caller" variable is available when your def is called, supporting embedded content:

from mako.runtime import supports_caller

@supports_caller
def my_tag(context):
    context.write("<div>")
    context['caller'].body()
    context.write("</div>")
    return ''

Capturing of output is available as well, using the outside-of-templates version of the capture() function, which accepts the "context" as its first argument:

from mako.runtime import supports_caller, capture

@supports_caller
def my_tag(context):
    return "<div>%s</div>" % \
            capture(context, context['caller'].body, x="foo", y="bar")

Declaring defs in namespaces.

The <%namespace> tag supports the definition of <%defs> directly inside the tag. These defs become part of the namespace like any other function, and will override the definitions pulled in from a remote template or module:

## define a namespace
<%namespace name="stuff">
    <%def name="comp1()">
        comp1
    </%def>
</%namespace>

## then call it
${stuff.comp1()}

The "body()" method

Every namespace that is generated from a template contains a method called body(). This method corresponds to the main body of the template, and plays its most important roles when using inheritance relationships as well as def-calls-with-content.

Since the body() method is available from a namespace just like all the other defs defined in a template, what happens if you send arguments to it ? By default, the body() method accepts no positional arguments, and for usefulness in inheritance scenarios will by default dump all keyword arguments into a dictionary called pageargs. But if you actually want to get at the keyword arguments, Mako recommends you define your own argument signature explicitly. You do this via using the <%page> tag:

<%page args="x, y, someval=8, scope='foo', **kwargs"/>

A template which defines the above signature requires that the variables x and y are defined, defines default values for someval and scope, and sets up **kwargs to receive all other keyword arguments. If **kwargs or similar is not present, the argument **pageargs gets tacked on by Mako. When the template is called as a top-level template (i.e. via template.render()) or via the <%include> tag, the values for these arguments will be pulled from the Context. In all other cases, i.e. via calling the body() method, the arguments are taken as ordinary arguments from the method call. So above, the body might be called as:

${self.body(5, y=10, someval=15, delta=7)}

The Context object also supplies a kwargs accessor, for cases when youd like to pass along whatever is in the context to a body() callable:

${next.body(**context.kwargs)}

The usefulness of calls like the above become more apparent when one works with inheriting templates. For more information on this, as well as the meanings of the names self and next, see Inheritance.

Namespace methods and properties

The Namespace class includes helpful accessors and methods:

• attr - allows access module level attributes by name. This accessor allows templates to supply "scalar" attributes which are particularly handy in inheritance relationships. See the example in Inheritance.
• module - the Python module referenced by this Namespace. If the namespace references a Template, then this module is the equivalent of template.module, i.e. the generated module for the template.
• filename - the path of the filesystem file used for this Namespace's module or template. If this is a pure module-based Namespace, this evaluates to module.__file__. If a template-based namespace, it evaluates to the original template file location.
• template - the Template object referenced by this Namespace, if any.
• uri - the uri for this Namespace's template (i.e. whatever was sent to lookup.get_template()). This is the equivalent of template.uri.
• context - the Context object for this namespace. Namespaces are often created with copies of contexts that contain slightly different data, particularly in inheritance scenarios. Using the Context off of a Namespace one can traverse an entire chain of templates that inherit from one-another.
• get_namespace(uri) - this method returns a Namespace at the given uri. If the given uri is a relative uri (i.e. it does not contain ia leading slash /), the uri is adjusted to be relative to the uri of the namespace itself. This method is therefore mostly useful off of the built-in local namespace, described in the next section. In most cases, a template wouldn't need this function, and should instead use the <%namespace> tag to load namespaces. However, since all <%namespace> tags are evaulated before the body of the template ever runs, this method can be used to locate namespaces using expressions that were generated within the body code of the template, or to conditionally use a particular namespace.

Built-in Namespaces

The namespace is so great that Mako gives your template one (or two) for free. The names of these namespaces are local and self. Other built-in namespaces include parent and next, which are optional and are described in Inheritance.

Inheritable Namespaces

The <%namespace> tag includes an optional attribute inheritable="True", which will cause the namespace to be attached to the self namespace. Since self is globally available throughout an inheritance chain (described in the next section), all the templates in an inheritance chain can get at the namespace imported in a super-template via self.

## base.html
<%namespace name="foo" file="foo.html" inheritable="True"/>

${next.body()}

## somefile.html
<%inherit file="base.html"/>

${self.foo.bar()}

This allows a super-template to load a whole bunch of namespaces that its inheriting templates can get to, without them having to explicitly load those namespaces themselves.

The import="*" part of the <%namespace> tag doesn't yet interact with the inheritable flag, so currently you have to use the explicit namespace name off of self, followed by the desired function name. But more on this in a future release.

Using the "next" namespace to produce content wrapping

Sometimes you have an inheritance chain that spans more than two templates. Or maybe you don't, but youd like to build your system such that extra inherited templates can be inserted in the middle of a chain where they would be smoothly integrated. If each template wants to define its layout just within its main body, you can't just call self.body() to get at the inheriting template's body, since that is only the topmost body. To get at the body of the next template, you call upon the namespace next, which is the namespace of the template immediately following the current template.

Lets change the line in base.html which calls upon self.body() to instead call upon next.body():

## base.html
<html>
    <body>
        <div class="header">
            ${self.header()}
        </div>

        ${next.body()}

        <div class="footer">
            ${self.footer()}
        </div>
    </body>
</html>

<%def name="footer()">
    this is the footer
</%def>

Lets also add an intermediate template called layout.html, which inherits from base.html:

## layout.html
<%inherit file="base.html"/>
<ul>
    ${self.toolbar()}
</ul>
<div class="mainlayout">
    ${next.body()}
</div>

<%def name="toolbar()">
    <li>selection 1</li>
    <li>selection 2</li>
    <li>selection 3</li>
</%def>

And finally change index.html to inherit from layout.html instead:

## index.html
<%inherit file="layout.html"/>

## .. rest of template

In this setup, each call to next.body() will render the body of the next template in the inheritance chain (which can be written as base.html -> layout.html -> index.html). Control is still first passed to the bottommost template base.html, and self still references the topmost definition of any particular def.

The output we get would be:

<html>
    <body>
        <div class="header">
            this is some header content
        </div>

        <ul>
            <li>selection 1</li>
            <li>selection 2</li>
            <li>selection 3</li>
        </ul>

        <div class="mainlayout">
        this is the body content.
        </div>

        <div class="footer">
            this is the footer
        </div>
    </body>
</html>

So above, we have the <html>, <body> and header/footer layout of base.html, we have the <ul> and mainlayout section of layout.html, and the main body of index.html as well as its overridden header def. The layout.html template is inserted into the middle of the chain without base.html having to change anything. Without the next namespace, only the main body of index.html could be used; there would be no way to call layout.html's body content.

Using the "parent" namespace to augment defs

Lets now look at the other inheritance-specific namespace, the opposite of next called parent. parent is the namespace of the template immediately preceding the current template. What is most useful about this namespace is the methods within it which can be accessed within overridden versions of those methods. This is not as hard as it sounds and is very much like using the super keyword in Python. Lets modify index.html to augment the list of selections provided by the toolbar function in layout.html:

## index.html
<%inherit file="layout.html"/>

<%def name="header()">
    this is some header content
</%def>

<%def name="toolbar()">
    ## call the parent's toolbar first
    ${parent.toolbar()}
    <li>selection 4</li>
    <li>selection 5</li>
</%def>

this is the body content.

Above, we implemented a toolbar() function, which is meant to override the definition of toolbar within the inherited template layout.html. However, since we want the content from that of layout.html as well, we call it via the parent namespace whenever we want it's content, in this case before we add our own selections. So the output for the whole thing is now:

<html>
    <body>
        <div class="header">
            this is some header content
        </div>

        <ul>
            <li>selection 1</li>
            <li>selection 2</li>
            <li>selection 3</li>
            <li>selection 4</li>
            <li>selection 5</li>
        </ul>

        <div class="mainlayout">
        this is the body content.
        </div>

        <div class="footer">
            this is the footer
        </div>
    </body>
</html>

and you're now a template inheritance ninja !

Inheritable Attributes

The attr accessor of the Namespace object allows access to module level variables declared in a template. By accessing self.attr, you can access regular attributes from the inheritance chain as declared in <%! %> sections. Such as:

<%!
    class_ = "grey"
%>

<div class="${self.attr.class_}">
    ${self.body()}
</div>

If a an inheriting template overrides class_ to be white, as in:

<%!
    class_ = "white"
%>
<%inherit file="parent.html"/>

This is the body

You'll get output like:

<div class="white">
    This is the body
</div>

Expression Filtering

As described in the Syntax chapter, the "|" operator can be applied to a "${}" expression to apply escape filters to the output:

${"this is some text" | u}

The above expression applies URL escaping to the expression, and produces this+is+some+text.

The built-in escape flags are:

• u : URL escaping, provided by urllib.quote_plus(string.encode('utf-8'))
• h : HTML escaping, provided by markupsafe.escape(string) (new as of 0.3.4 - prior versions use cgi.escape(string, True))
• x : XML escaping
• trim : whitespace trimming, provided by string.strip()
• entity : produces HTML entity references for applicable strings, derived from htmlentitydefs
• unicode (str on Python 3): produces a Python unicode string (this function is applied by default).
• decode.<some encoding> : decode input into a Python unicode with the specified encoding
• n : disable all default filtering; only filters specified in the local expression tag will be applied.

To apply more than one filter, separate them by a comma:

${"  <tag>some value</tag> " | h,trim}

The above produces <tag>some value</tag>, with no leading or trailing whitespace. The HTML escaping function is applied first, the "trim" function second.

Naturally, you can make your own filters too. A filter is just a Python function that accepts a single string argument, and returns the filtered result. The expressions after the | operator draw upon the local namespace of the template in which they appear, meaning you can define escaping functions locally:

<%!
    def myescape(text):
        return "<TAG>" + text + "</TAG>"
%>

Heres some tagged text: ${"text" | myescape}

Or from any Python module:

<%!
    import myfilters
%>

Heres some tagged text: ${"text" | myfilters.tagfilter}

A page can apply a default set of filters to all expression tags using the expression_filter argument to the %page tag:

<%page expression_filter="h"/>

Escaped text:  ${"<html>some html</html>"}

Result:

Escaped text: <html>some html</html>

t = TemplateLookup(directories=['/tmp'], default_filters=['unicode'])

t = TemplateLookup(directories=['/tmp'], default_filters=['decode.utf8'])

t = TemplateLookup(directories=['/tmp'], default_filters=[])

t = Template(templatetext, default_filters=['unicode', 'myfilter'])

t = TemplateLookup(directories=['/tmp'], 
    default_filters=['unicode', 'myfilter'], 
    imports=['from mypackage import myfilter'])

# ....
from mypackage import myfilter

def render_body(context):
    context.write(myfilter(unicode("some text")))

${'myexpression' | n}

${'myexpression' | n, trim}

Filtering Defs

The %def tag has a filter argument which will apply the given list of filter functions to the output of the %def:

<%def name="foo()" filter="h, trim">
    <b>this is bold</b>
</%def>

When the filter attribute is applied to a def as above, the def is automatically buffered as well. This is described next.

Buffering

One of Mako's central design goals is speed. To this end, all of the textual content within a template and its various callables is by default piped directly to the single buffer that is stored within the Context object. While this normally is easy to miss, it has certain side effects. The main one is that when you call a def using the normal expression syntax, i.e. ${somedef()}, it may appear that the return value of the function is the content it produced, which is then delivered to your template just like any other expression substitution, except that normally, this is not the case; the return value of ${somedef()} is simply the empty string ''. By the time you receive this empty string, the output of somedef() has been sent to the underlying buffer.

You may not want this effect, if for example you are doing something like this:

${" results " + somedef() + " more results "}

If the somedef() function produced the content "somedef's results", the above template would produce this output:

somedef's results results more results

This is because somedef() fully executes before the expression returns the results of its concatenation; the concatenation in turn receives just the empty string as its middle expression.

Mako provides two ways to work around this. One is by applying buffering to the %def itself:

<%def name="somedef()" buffered="True">
    somedef's results
</%def>

The above definition will generate code similar to this:

def somedef():
    context.push_buffer()
    try:
        context.write("somedef's results")
    finally:
        buf = context.pop_buffer()
    return buf.getvalue()

So that the content of somedef() is sent to a second buffer, which is then popped off the stack and its value returned. The speed hit inherent in buffering the output of a def is also apparent.

Note that the filter argument on %def also causes the def to be buffered. This is so that the final content of the %def can be delivered to the escaping function in one batch, which reduces method calls and also produces more deterministic behavior for the filtering function itself, which can possibly be useful for a filtering function that wishes to apply a transformation to the text as a whole.

The other way to buffer the output of a def or any Mako callable is by using the built-in capture function. This function performs an operation similar to the above buffering operation except it is specified by the caller.

${" results " + capture(somedef) + " more results "}

Note that the first argument to the capture function is the function itself, not the result of calling it. This is because the capture function takes over the job of actually calling the target function, after setting up a buffered environment. To send arguments to the function, just send them to capture instead:

${capture(somedef, 17, 'hi', use_paging=True)}

The above call is equivalent to the unbuffered call:

${somedef(17, 'hi', use_paging=True)}

Decorating

This is a feature that's new as of version 0.2.5. Somewhat like a filter for a %def but more flexible, the decorator argument to %def allows the creation of a function that will work in a similar manner to a Python decorator. The function can control whether or not the function executes. The original intent of this function is to allow the creation of custom cache logic, but there may be other uses as well.

decorator is intended to be used with a regular Python function, such as one defined in a library module. Here we'll illustrate the python function defined in the template for simplicities' sake:

<%!
    def bar(fn):
        def decorate(context, *args, **kw):
            context.write("BAR")
            fn(*args, **kw)
            context.write("BAR")
            return ''
        return decorate
%>

<%def name="foo()" decorator="bar">
    this is foo
</%def>

${foo()}

The above template will return, with more whitespace than this, "BAR this is foo BAR". The function is the render callable itself (or possibly a wrapper around it), and by default will write to the context. To capture its output, use the capture callable in the mako.runtime module (available in templates as just runtime):

<%!
    def bar(fn):
        def decorate(context, *args, **kw):
            return "BAR" + runtime.capture(context, fn, *args, **kw) + "BAR"
        return decorate
%>

<%def name="foo()" decorator="bar">
    this is foo
</%def>

${foo()}

The decorator can be used with top-level defs as well as nested defs. Note that when calling a top-level def from the Template api, i.e. template.get_def('somedef').render(), the decorator has to write the output to the context, i.e. as in the first example. The return value gets discarded.

Specifying the Encoding of a Template File

This is the most basic encoding-related setting, and it is equivalent to Python's "magic encoding comment", as described in pep-0263. Any template that contains non-ascii characters requires that this comment be present so that Mako can decode to unicode (and also make usage of Python's AST parsing services). Mako's lexer will use this encoding in order to convert the template source into a unicode object before continuing its parsing:

## -*- coding: utf-8 -*-

Alors vous imaginez ma surprise, au lever du jour, quand une drôle de petit voix m’a réveillé. Elle disait: « S’il vous plaît… dessine-moi un mouton! »

For the picky, the regular expression used is derived from that of the abovementioned pep:

#.*coding[:=]\s*([-\w.]+).*\n

The lexer will convert to unicode in all cases, so that if any characters exist in the template that are outside of the specified encoding (or the default of ascii), the error will be immediate.

As an alternative, the template encoding can be specified programmatically to either Template or TemplateLookup via the input_encoding parameter:

t = TemplateLookup(directories=['./'], input_encoding='utf-8')

The above will assume all located templates specify utf-8 encoding, unless the template itself contains its own magic encoding comment, which takes precedence.

Handling Expressions

The next area that encoding comes into play is in expression constructs. By default, Mako's treatment of an expression like this:

${"hello world"}

looks something like this:

context.write(unicode("hello world"))

In Python 3, its just:

context.write(str("hello world"))

That is, the output of all expressions is run through the unicode builtin. This is the default setting, and can be modified to expect various encodings. The unicode step serves both the purpose of rendering non-string expressions into strings (such as integers or objects which contain __str()__ methods), and to ensure that the final output stream is constructed as a unicode object. The main implication of this is that any raw bytestrings that contain an encoding other than ascii must first be decoded to a Python unicode object. It means you can't say this in Python 2:

${"voix m’a réveillé."}  ## error in Python 2!

You must instead say this:

${u"voix m’a réveillé."}  ## OK !

Similarly, if you are reading data from a file that is streaming bytes, or returning data from some object that is returning a Python bytestring containing a non-ascii encoding, you have to explcitly decode to unicode first, such as:

${call_my_object().decode('utf-8')}

Note that filehandles acquired by open() in Python 3 default to returning "text", that is the decoding is done for you. See Python 3's documentation for the open() builtin for details on this.

If you want a certain encoding applied to all expressions, override the unicode builtin with the decode builtin at the Template or TemplateLookup level:

t = Template(templatetext, default_filters=['decode.utf8'])

Note that the built-in decode object is slower than the unicode function, since unlike unicode its not a Python builtin, and it also checks the type of the incoming data to determine if string conversion is needed first.

The default_filters argument can be used to entirely customize the filtering process of expressions. This argument is described in The default_filters Argument.

Defining Output Encoding

Now that we have a template which produces a pure unicode output stream, all the hard work is done. We can take the output and do anything with it.

As stated in the "Usage" chapter, both Template and TemplateLookup accept output_encoding and encoding_errors parameters which can be used to encode the output in any Python supported codec:

from mako.template import Template
from mako.lookup import TemplateLookup

mylookup = TemplateLookup(directories=['/docs'], output_encoding='utf-8', encoding_errors='replace')

mytemplate = mylookup.get_template("foo.txt")
print mytemplate.render()

render() will return a bytes object in Python 3 if an output encoding is specified. By default it performs no encoding and returns a native string.

render_unicode() will return the template output as a Python unicode object (or string in Python 3):

print mytemplate.render_unicode()

The above method disgards the output encoding keyword argument; you can encode yourself by saying:

print mytemplate.render_unicode().encode('utf-8', 'replace')

Saying to Heck with it: Disabling the usage of Unicode entirely

Some segements of Mako's userbase choose to make no usage of Unicode whatsoever, and instead would prefer the "passthru" approach; all string expressions in their templates return encoded bytestrings, and they would like these strings to pass right through. The only advantage to this approach is that templates need not use u"" for literal strings; there's an arguable speed improvement as well since raw bytestrings generally perform slightly faster than unicode objects in Python. For these users, assuming they're sticking with Python 2, they can hit the disable_unicode=True flag as so:

# -*- encoding:utf-8 -*-
from mako.template import Template

t = Template("drôle de petit voix m’a réveillé.", disable_unicode=True, input_encoding='utf-8')
print t.code

The disable_unicode mode is strictly a Python 2 thing. It is not supported at all in Python 3.

The generated module source code will contain elements like these:

# -*- encoding:utf-8 -*-
#  ...more generated code ...

def render_body(context,**pageargs):
    context.caller_stack.push_frame()
    try:
        __M_locals = dict(pageargs=pageargs)
        # SOURCE LINE 1
        context.write('dr\xc3\xb4le de petit voix m\xe2\x80\x99a r\xc3\xa9veill\xc3\xa9.')
        return ''
    finally:
        context.caller_stack.pop_frame()

Where above that the string literal used within context.write is a regular bytestring.

When disable_unicode=True is turned on, the default_filters argument which normally defaults to ["unicode"] now defaults to ["str"] instead. Setting default_filters to the empty list [] can remove the overhead of the str call. Also, in this mode you cannot safely call render_unicode() - you'll get unicode/decode errors.

The h filter (html escape) uses a less performant pure Python escape function in non-unicode mode (note that in versions prior to 0.3.4, it used cgi.escape(), which has been replaced with a function that also escapes single quotes). This because MarkupSafe only supports Python unicode objects for non-ascii strings.

Rules for using disable_unicode=True

• don't use this mode unless you really, really want to and you absolutely understand what you're doing
• don't use this option just because you don't want to learn to use Unicode properly; we aren't supporting user issues in this mode of operation. We will however offer generous help for the vast majority of users who stick to the Unicode program.
• Python 3 is unicode by default, and the flag is not available when running on Python 3.

Cache arguments

The various cache arguments are cascaded from their default values, to the arguments specified programmatically to the Template or its originating TemplateLookup, then to those defined in the <%page> tag of an individual template, and finally to an individual <%def> tag within the template. This means you can define, for example, a cache type of dbm on your TemplateLookup, a cache timeout of 60 seconds in a particular template's <%page> tag, and within one of that template's <%def> tags cache=True, and that one particular def will then cache its data using a dbm cache and a data timeout of 60 seconds.

The options available are:

• cached="False|True" - turn caching on

• cache_timeout - number of seconds in which to invalidate the cached data. after this timeout, the content is re-generated on the next call.

• cache_type - type of caching. memory, file, dbm, or memcached.

• cache_url - (only used for memcached but required) a single IP address or a semi-colon separated list of IP address of memcache servers to use.

• cache_dir - In the case of the file and dbm cache types, this is the filesystem directory with which to store data files. If this option is not present, the value of module_directory is used (i.e. the directory where compiled template modules are stored). If neither option is available an exception is thrown. In the case of the memcached type, this attribute is required and it's used to store the lock files.

• cache_key - the "key" used to uniquely identify this content in the cache. the total namespace of keys within the cache is local to the current template, and the default value of "key" is the name of the def which is storing its data. It is an evaluable tag, so you can put a Python expression to calculate the value of the key on the fly. For example, heres a page that caches any page which inherits from it, based on the filename of the calling template:

  <%page cached="True" cache_key="${self.filename}"/>
  
  ${next.body()}
  
  ## rest of template
  

Accessing the Cache

The Template, as well as any template-derived namespace, has an accessor called cache which returns the Cache object for that template. This object is a facade on top of the Beaker internal cache object, and provides some very rudimental capabilities, such as the ability to get and put arbitrary values:

<%
    local.cache.put("somekey", type="memory", "somevalue")
%>

Above, the cache associated with the local namespace is accessed and a key is placed within a memory cache.

More commonly the cache object is used to invalidate cached sections programmatically:

template = lookup.get_template('/sometemplate.html')

# invalidate the "body" of the template
template.cache.invalidate_body()

# invalidate an individual def
template.cache.invalidate_def('somedef')

# invalidate an arbitrary key
template.cache.invalidate('somekey')