Multiple Pages | One Page

# Mako Documentation

Version: 0.1.9 Last Updated: 09/25/07 16:19:18
Next: Syntax

### Table of Contents

### Basic Usage

This section describes the Python API for Mako templates. If you are using Mako within a web framework such as Pylons, the work of integrating Mako's API is already done for you, in which case you can skip to the next section, Syntax.

The most basic way to create a template and render it is through the `Template` class:

    from mako.template import Template

    mytemplate = Template("hello world!")
    print mytemplate.render()

Above, the text argument to `Template` is compiled into a Python module representation. This module contains a function called `render_body()`, which produces the output of the template. When `mytemplate.render()` is called, Mako sets up a runtime environment for the template and calls the `render_body()` function, capturing the output into a buffer and returning it's string contents.

The code inside the `render_body()` function has access to a namespace of variables. You can specify these variables by sending them as additional keyword arguments to the `render()` method:

    from mako.template import Template

    mytemplate = Template("hello, ${name}!")
    print mytemplate.render(name="jack")

The `template.render()` method calls upon Mako to create a `Context` object, which stores all the variable names accessible to the template and also stores a buffer used to capture output. You can create this `Context` yourself and have the template render with it, using the `render_context` method:

    from mako.template import Template
    from mako.runtime import Context
    from StringIO import StringIO

    mytemplate = Template("hello, ${name}!")
    buf = StringIO()
    ctx = Context(buf, name="jack")
    mytemplate.render_context(ctx)
    print buf.getvalue()

### 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.

back to section top

### 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`.

### Setting the Collection Size

The `TemplateLookup` also serves the important need of caching a fixed set of templates in memory at a given time, so that successive uri lookups do not result in full template compilations and/or module reloads on each request. By default, the `TemplateLookup` size is unbounded. You can specify a fixed size using the `collection_size` argument:

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

The above lookup will continue to load templates into memory until it reaches a count of around 500. At that point, it will clean out a certain percentage of templates using a least recently used scheme.

back to section top

### Setting Filesystem Checks

Another important flag on `TemplateLookup` is `filesystem_checks`. This defaults to `True`, and says that each time a template is returned by the `get_template()` method, the revision time of the original template file is checked against the last time the template was loaded, and if the file is newer will reload its contents and recompile the template. On a production system, seting `filesystem_checks` to `False` can afford a small to moderate performance increase (depending on the type of filesystem used).

back to section top

### 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()

Additionally, the `render_unicode()` method exists which will return the template output as a Python `unicode` object:

    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')

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.

back to section top

### 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`.

back to section top

### 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.

### Turbogears/Pylons Plugin

The standard plugin methodology used by Turbogears as well as Pylons is included in the module `mako.ext.turbogears`, using the `TGPlugin` class. This is also a setuptools entrypoint under the heading `python.templating.engines` with the name `mako`.

back to section top

### WSGI

A sample WSGI application is included in the distrubution in the file `examples/wsgi/run_wsgi.py`. This runner is set up to pull files from a `templates` as well as an `htdocs` directory and includes a rudimental two-file layout. The WSGI runner acts as a fully functional standalone web server, using `wsgiutils` to run itself, and propagates GET and POST arguments from the request into the `Context`, can serve images, css files and other kinds of files, and also displays errors using Mako's included exception-handling utilities.

back to section top

### Pygments

A Pygments-compatible syntax highlighting module is included under `mako.ext.pygmentplugin`. This module is used in the generation of Mako documentation and also contains various setuptools entry points under the heading `pygments.lexers`, including `mako`, `html+mako`, `xml+mako` (see the `setup.py` file for all the entry points).

back to section top

### Babel (Internationalization)

Mako provides support for extracting gettext messages from templates via a Babel extractor entry point under `mako.ext.babelplugin`.

Gettext messages are extracted from all Python code sections, even the more obscure ones such as control structures, def tag function declarations, call tag exprs and even page tag args.

Translator comments may also be extracted from Mako templates when a comment tag is specified to Babel (such as with the -c option).

For example, a project '`myproj`' contains the following Mako template at myproj/myproj/templates/name.html:

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

To extract gettext messages from this template the project needs a Mako section in its Babel Extraction Method Mapping file (typically located at myproj/babel.cfg):

    # Extraction from Python source files

    [python: myproj/**.py]

    # Extraction from Mako templates

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

The Mako extractor supports an optional `input_encoding` parameter specifying the encoding of the templates (identical to `Template`/`TemplateLookup`'s `input_encoding` parameter).

Invoking Babel's extractor at the command line in the project's root directory:

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

Will output a gettext catalog to stdout including the following:

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

This is only a basic example: Babel can be invoked from setup.py and its command line options specified in the accompanying setup.cfg via Babel Distutils/Setuptools Integration.

Comments must immediately precede a gettext message to be extracted. In the following case the TRANSLATORS: comment would not have been extracted:

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

See the Babel User Guide for more information.

back to section top
Previous: Basic Usage | Next: Defs

### Table of Contents

### Syntax

A Mako template is parsed from a text stream containing any kind of content, XML, HTML, email text, etc. The template can further contain Mako-specific directives which represent variable and/or expression substitutions, control structures (i.e. conditionals and loops), server-side comments, full blocks of Python code, as well as various tags that offer additional functionality. All of these constructs compile into real Python code. This means that you can leverage the full power of Python in almost every aspect of a Mako template.

### Expression Substiution

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.

### Expression Escaping

Mako includes a number of built-in escaping mechanisms, including HTML, URI and XML escaping, as well as a "trim" function. These escapes can be added to an expression substituion using the `|` operator:

    ${"this is some text" | u}

The above expression applies URL escaping to the expression, and produces `this+is+some+text`. The `u` name indicates URL escaping, whereas `h` represents HTML escaping, `x` represents XML escaping, and `trim` applies a trim function.

Read more about built in filtering functions, including how to make your own filter functions, in Filtering and Buffering.

back to section top

### 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

back to section top

### 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>

Note that this is new behavior as of Mako 0.1.3. The syntax prior to this version was the single pound sign (`#`), which was agreed by the Mako userbase that it conflicted with CSS elements too often and also did not address multiline comments easily.

back to section top

### 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.

back to section top

### 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: ${y}
    % 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.

### Module-level Blocks

A variant on `<% %>` is the module-level code block, denoted by `<%! %>`. Code within these tags is executed at the module level of the template, and not within the rendering function of the template. Therefore, this code does not have access to the template's context and is only executed when the template is loaded into memory (which can be only once per application, or more, depending on the runtime environment). Use the `<%! %>` tags to declare your template's imports, as well as any pure-Python functions you might want to declare:

    <%!
        import mylib
        import re

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

Any number of `<%! %>` blocks can be declared anywhere in a template; they will be rendered in the resulting module in the order that they appear.

back to section top

### 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>

This tag defines general characteristics of the template, including caching arguments, and optional lists of arguments which the template expects when invoked.

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

Or a page tag that defines caching characteristics:

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

Currently, only one `<%page>` tag gets used per template, the rest get ignored. While this will be improved in a future release, for now make sure you have only one `<%page>` tag defined in your template, else you may not get the results you want. The details of what `<%page>` is used for are described further in The "body()" method as well as Caching.

back to section top

### <%include>

A tag that is familiar from other template languages, %include is a regular joe that just accepts a file argument and calls in the rendered result of that file:

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

        hello world

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

back to section top

### <%def>

The `%def` tag defines a Python function which contains a set of content, that can be called at some other point in the template. The basic idea is simple:

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

    ${myfunc(7)}

The %def tag is a lot more powerful than a plain Python def, as the Mako compiler provides many extra services with %def that you wouldn't normally have, such as the ability to export defs as template "methods", automatic propigation of the current `Context`, buffering/filtering/caching flags, and def calls with content, which enable packages of defs to be sent as arguments to other def calls (not as hard as it sounds). Get the full deal on what %def can do in Defs.

back to section top

### <%namespace>

%namespace is Mako's equivalent of Python's `import` statement. It allows access to all the rendering functions and metadata of other template files, plain Python modules, as well as locally defined "packages" of functions.

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

The underlying object generated by %namespace, an instance of `mako.runtime.Namespace`, is a central construct used in templates to reference template-specific information such as the current URI, inheritance structures, and other things that are not as hard as they sound right here. Namespaces are described in Namespaces.

back to section top

### <%inherit>

Inherit allows templates to arrange themselves in inheritance chains. This is a concept familiar in many other template languages.

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

When using the %inherit tag, control is passed to the topmost inherited template first, which then decides how to handle calling areas of content from its inheriting templates. Mako offers a lot of flexbility in this area, including dynamic inheritance, content wrapping, and polymorphic method calls. Check it out in Inheritance.

back to section top

### <%call>

The call tag is used to call `<%defs>` with additional embedded content. This tag is described in Calling a def with embedded content and/or other defs.

back to section top

### <%doc>

The doc tag handles multiline comments:

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

Also the `##` symbol as the first non-space characters on a line can be used for single line comments.

back to section top

### <%text>

This tag suspends the Mako lexer's normal parsing of Mako template directives, and returns its entire body contents as plain text. It is used pretty much to write documentation about Mako:

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

back to section top
Previous: Syntax | Next: The Mako Runtime Environment

### Table of Contents

### Defs

The def is the single tag used to demarcate any block of text and/or code. It exists within generated Python as a callable function.

    <%def name="hello()">
        hello world
    </%def>

They are normally called as expressions.

    the def:  ${hello()}

If the `<%def>` is not nested inside of another `<%def>`, its known as a top level def and can be accessed anywhere in the template, including above where it was defined.

All defs, top level or not, have access to the current contextual namespace in exactly the same way their containing template does. Suppose the template below is executed with the variables `username` and `accountdata` inside the context:

    Hello there ${username}, how are ya.  Lets see what your account says:

    ${account()}

    <%def name="account()">
        Account for ${username}:<br/>

        % for row in accountdata:
            Value: ${row}<br/>
        % endfor
    </%def>

The `username` and `accountdata` variables are present within the main template body as well as the body of the `account()` def.

Since defs are just Python functions, you can define and pass arguments to them as well:

    ${account(accountname='john')}

    <%def name="account(accountname, type='regular')">
        account name: ${accountname}, type ${type}
    </%def>

When you declare an argument signature for your def, they are required following normal Python conventions (i.e., all arguments are required except keyword arguments with a default value). This is in contrast to using context-level variables, which evaluate to `UNDEFINED` if you reference a name that does not exist.

### 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.

back to section top

### 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.

back to section top

### 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 `<%call>` tag instead of the normal `${}` syntax. The target def then gets a variable `caller` placed in its context which contains a namespace containing the body and other defs defined within the `<%call>` tag. The body itself is referenced by the method `body()`:

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

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

This produces the output (whitespace formatted):

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

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(1,count):
            ${caller.body()}
        % endfor
    </%def>

    <%call expr="lister(3)">
        hi
    </%call>

Produces:

    hi
    hi
    hi

A custom "conditional" tag:

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

    <%call expr="conditional(4==4)">
        im the result
    </%call>

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:

    <%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>

    <%call expr="layoutdata([[1,2,3],[4,5,6],[7,8,9]])" args="col">
        Body data: ${col}
    </%call>

Produces (whitespace formatted):

    <table>
        <tr>
            <td>Body data: 1</td><td>Body data: 2</td><td>Body data: 3</td>
            <td>Body data: 4</td><td>Body data: 5</td><td>Body data: 6</td>
            <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
    <%call expr="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
    </%call>

The above layout would produce (whitespace formatted):

    <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>` 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 or even plain Python callables which are called via `<%call>`.

back to section top
Previous: Defs | Next: Namespaces

### Table of Contents

### The Mako Runtime Environment

This section describes a little bit about the objects and built-in functions that are available in templates.

### 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.

### The Buffer

The buffer is stored within the `Context`, and writing to it is achieved by calling `context.write()`. You usually don't need to care about this as all text within a template, as well as all expressions provided by `${}`, automatically send everything to this method. The cases you might want to be aware of its existence are if you are dealing with various filtering/buffering scenarios, which are described in Filtering and Buffering, or if you want to programmatically send content to the output stream, such as within a `<% %>` block.

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

The actual buffer may or may not be the original buffer sent to the `Context` object, as various filtering/caching scenarios may "push" a new buffer onto the context's underlying buffer stack. For this reason, just stick with `context.write()` and content will always go to the topmost buffer.

back to section top

### Context Variables

When your template is compiled into a Python module, the body content is enclosed within a Python function called `render_body`. Other top-level defs defined in the template are defined within their own function bodies which are named after the def's name with the prefix `render_` (i.e. `render_mydef`). One of the first things that happens within these functions is that all variable names that are referenced within the function which are not defined in some other way (i.e. such as via assignment, module level imports, etc.) are pulled from the `Context` object's dictionary of variables. This is how you're able to freely reference variable names in a template which automatically correspond to what was passed into the current `Context`.

- What happens if I reference a variable name that is not in the current context? - the value you get back is a special value called `UNDEFINED`. This is just a simple global variable with the class `mako.runtime.Undefined`. The `UNDEFINED` object throws an error when you call `str()` on it, which is what happens if you try to use it in an expression.

- Why not just return None? Using `UNDEFINED` is more explicit and allows differentiation between a value of `None` that was explicitly passed to the `Context` and a value that wasn't present at all.

- Why raise an exception when you call str() on it ? Why not just return a blank string? - Mako tries to stick to the Python philosophy of "explicit is better than implicit". In this case, its decided that the template author should be made to specifically handle a missing value rather than experiencing what may be a silent failure. Since `UNDEFINED` is a singleton object just like Python's `True` or `False`, you can use the `is` operator to check for it:

      % if someval is UNDEFINED:
          someval is: no value
      % else:
          someval is: ${someval}
      % endif

Another facet of the `Context` is that its dictionary of variables is immutable. Whatever is set when `template.render()` is called is what stays. Of course, since its Python, you can hack around this and change values in the context's internal dictionary, but this will probably will not work as well as you'd think. The reason for this is that Mako in many cases creates copies of the `Context` object, which get sent to various elements of the template and inheriting templates used in an execution. So changing the value in your local `Context` will not necessarily make that value available in other parts of the template's execution. Examples of where Mako creates copies of the `Context` include within top-level def calls from the main body of the template (the context is used to propagate locally assigned variables into the scope of defs; since in the template's body they appear as inlined functions, Mako tries to make them act that way), and within an inheritance chain (each template in an inheritance chain has a different notion of `parent` and `next`, which are all stored in unique `Context` instances).

- So what if I want to set values that are global to everyone within a template request? - All you have to do is provide a dictionary to your `Context` when the template first runs, and everyone can just get/set variables from that. Lets say its called `attributes`.

Running the template looks like:

    output = template.render(attributes={})

Within a template, just reference the dictionary:

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

- Why can't "attributes" be a built-in feature of the Context? - This is an area where Mako is trying to make as few decisions about your application as it possibly can. Perhaps you don't want your templates to use this technique of assigning and sharing data, or perhaps you have a different notion of the names and kinds of data structures that should be passed around. Once again Mako would rather ask the user to be explicit.

back to section top

### Context Methods and Accessors

Significant members off of `Context` include:

- `context[key]` / `context.get(key, default=None)` - dictionary-like accessors for the context. Normally, any variable you use in your template is automatically pulled from the context if it isnt defined somewhere already. Use the dictionary accessor and/or `get` method when you want a variable that is already defined somewhere else, such as in the local arguments sent to a %def call. If a key is not present, like a dictionary it raises `KeyError`.

- `keys()` - all the names defined within this context.

- `kwargs` - this returns a copy of the context's dictionary of variables. This is useful when you want to propagate the variables in the current context to a function as keyword arguments, i.e.:

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

- `write(text)` - write some text to the current output stream.

- `lookup` - returns the `TemplateLookup` instance that is used for all file-lookups within the current execution (even though individual `Template` instances can conceivably have different instances of a `TemplateLookup`, only the `TemplateLookup` of the originally-called `Template` gets used in a particular execution).

back to section top

### 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.

back to section top
Previous: The Mako Runtime Environment | Next: Inheritance

### Table of Contents

### Namespaces

Namespaces are used to organize groups of components into categories, and also to "import" components from other files.

If the file `components.html` defines these two components:

    ## components.html
    <%def name="comp1()">
        this is comp1
    </%def>

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

You can make another file, for example `index.html`, that pulls those two components into a namespace called `comp`:

    ## index.html
    <%namespace name="comp" file="components.html"/>

    Heres comp1:  ${comp.comp1()}
    Heres comp2:  ${comp.comp2()}

The `comp` variable above is an instance of `mako.runtime.Namespace`, a proxy object which delivers method calls to the underlying template callable using the current context.

`<%namespace>` also provides an `import` attribute which can be used to pull the names into the local namespace, removing the need to call it via the ".". When `import` is used, the `name` attribute is optional.

    <%namespace file="components.html" import="comp1, comp2"/>

    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2()}

`import` also supports the "*" operator:

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

    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2()}

The names imported by the `import` attribute take precedence over any names that exist within the current context.

### 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")

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.

back to section top

### 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()}

back to section top

### 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.

back to section top

### Namespace methods and properties

The `Namespace` class includes helpful accessors and methods:

- `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.

back to section top

### 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.

### local

The `local` namespace is basically the namespace for the currently executing template. This means that all of the top level defs defined in your template, as well as your template's `body()` function, are also available off of the `local` namespace.

The `local` namespace is also where properties like `uri`, `filename`, and `module` and the `get_namespace` method can be particularly useful.

back to section top

### self

The `self` namespace, in the case of a template that does not use inheritance, is synonomous with `local`. If inheritance is used, then `self` references the topmost template in the inheritance chain, where it is most useful for providing the ultimate form of various "method" calls which may have been overridden at various points in an inheritance chain. See Inheritance.

back to section top

### 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.

back to section top
Previous: Namespaces | Next: Filtering and Buffering

### Table of Contents

### Inheritance

Using template inheritance, two or more templates can organize themselves into an inheritance chain, where content and functions from all involved templates can be intermixed. The general paradigm of template inheritance is this: if a template `A` inherits from template `B`, then template `A` agrees to send the executional control to template `B` at runtime (`A` is called the inheriting template). Template `B`, the inherited template, then makes decisions as to what resources from `A` shall be executed.

In practice, it looks like this. Heres a hypothetical inheriting template, `index.html`:

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

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

    this is the body content.

And `base.html`, the inherited template:

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

            ${self.body()}

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

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

Here is a breakdown of the execution:

- When `index.html` is rendered, control immediately passes to `base.html`.

- `base.html` then renders the top part of an HTML document, then calls the method `header()` off of a built in namespace called `self` (this namespace was first introduced in the Namespaces chapter in self). Since `index.html` is the topmost template and also defines a def called `header()`, its this `header()` def that gets executed.

- Control comes back to `base.html`. Some more HTML is rendered.

- `base.html` executes `self.body()`. The `body()` function on all template-based namespaces refers to the main body of the template, therefore the main body of `index.html` is rendered.

- Control comes back to `base.html`. More HTML is rendered, then the `self.footer()` expression is invoked.

- The `footer` def is only defined in `base.html`, so being the topmost definition of `footer`, its the one that executes. If `index.html` also specified `footer`, then its version would override that of the base.

- `base.html` finishes up rendering its HTML and the template is complete, producing:

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

              this is the body content.

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

...and that is template inheritance in a nutshell. The main idea is that the methods that you call upon `self` always correspond to the topmost definition of that method. Very much the way `self` works in a Python class, even though Mako is not actually using Python class inheritance to implement this functionality. (Mako doesn't take the "inheritance" metaphor too seriously; while useful to setup some commonly recognized semantics, a textual template is not very much like an object-oriented class construct in practice).

### 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.

back to section top

### 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 !

back to section top
Previous: Inheritance | Next: The Unicode Chapter

### Table of Contents

### Filtering and Buffering

### 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 `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` : 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 `&lt;tag&gt;some value&lt;/tag&gt;`, 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: &lt;html&gt;some html&lt;/html&gt;

### The default_filters Argument

New in version 0.1.2

In addition to the `expression_filter` argument, the `default_filters` argument to both `Template` and `TemplateLookup` can specify filtering for all expression tags at the programmatic level. This array-based argument defaults to `["unicode"]`:

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

To replace the usual `unicode` function with a specific encoding, the `decode` filter can be substituted:

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

Any string name can be added to `default_filters` where it will be added to all expressions as a filter. The filters are applied from left to right, meaning the leftmost filter is applied first.

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

To ease the usage of `default_filters` with custom filters, you can also add imports (or other code) to all templates using the `imports` argument:

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

The above will generate templates something like this:

    # ....
    from mypackage import myfilter

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

back to section top

### Turning off Filtering with the "n" filter

In all cases the special `n` filter, used locally within an expression, will disable all filters declared in the `<%page>` tag as well `default_filters`. Such as:

    ${'myexpression' | n}

Will render `myexpression` with no filtering of any kind, and

    ${'myexpression' | n, trim}

will render `myexpression` using the `trim` filter only.

back to section top

### 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.

back to section top

### 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)}

back to section top
Previous: Filtering and Buffering | Next: Caching

### Table of Contents

### The Unicode Chapter

The Python language in the 2.x series supports two ways of representing string objects. One is the `string` type and the other is the `unicode` type, both of which extend a type called `basestring`. A key issue in Python, which is hopefully to be resolved in Python 3000, is that objects of type `string` (i.e. created from an expression such as `"hello world"`) contain no information regarding what encoding the data is stored in. For this reason they are often referred to as byte strings. The origins of this come from Python's background of being developed before the Unicode standard was even available, back when strings were C-style strings and were just that, a series of bytes. Strings that had only values below 128 just happened to be ascii strings and were printable on the console, whereas strings with values above 128 would produce all kinds of graphical characters and bells.

Contrast the Python `string` type with the Python `unicode` type. Objects of this type are created whenever you say something like `u"hello world"`. In this case, Python represents each character in the string internally using multiple bytes per character (something similar to UTF-16). Whats important is that when using the `unicode` type to store strings, Python knows the data's encoding; its in its own internal format. Whereas when using the `string` type, it does not.

When Python attempts to treat a byte-string as a string, which means its attempting to compare/parse its characters, to coerce it into another encoding, or to decode it to a unicode object, it has to guess what the encoding is. In this case, it will pretty much always guess the encoding as `ascii`...and if the bytestring contains bytes above value 128, you'll get an error.

There is one operation that Python can do with a non-ascii bytestring, and its a great source of confusion: it can dump the bytestring straight out to a stream or a file, with nary a care what the encoding is. To Python, this is pretty much like dumping any other kind of binary data (like an image) to a stream somewhere. So in a lot of cases, programs that embed all kinds of international characters and encodings into plain byte-strings (i.e. using `"hello world"` style literals) can fly right through their run, sending reams of strings out to whereever they are going, and the programmer, seeing the same output as was expressed in the input, is now under the illusion that his or her program is Unicode-compliant. In fact, their program has no unicode awareness whatsoever, and similarly has no ability to interact with libraries that are unicode aware.

Particularly, some template languages like Cheetah, as well as earlier versions of Myghty, will treat expressions in this manner..they just go right through. Theres nothing "incorrect" about this, but Mako, since it deals with unicode internally, usually requires explicitness when dealing with non-ascii encodings. Additionally, if you ever need to handle unicode strings and other kinds of encoding conversions more intelligently, the usage of raw bytestrings quickly becomes a nightmare, since you are sending the Python interpreter collections of bytes for which it can make no intelligent decisions with regards to encoding.

In Mako, all parsed template constructs and output streams are handled internally as Python `unicode` objects. Its only at the point of `render()` that this unicode stream is rendered into whatever the desired output encoding is. The implication here is that the template developer must ensure that the encoding of all non-ascii templates is explicit, that all non-ascii-encoded expressions are in one way or another converted to unicode, and that the output stream of the template is handled as a unicode stream being encoded to some encoding.

### 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.

back to section top

### 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"))

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:

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

You must instead say this:

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

Similarly, if you are reading data from a file, 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')}

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.

back to section top

### 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()

And `render_unicode()` will return the template output as a Python `unicode` object:

    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')

### Buffer Selection

Mako does play some games with the style of buffering used internally, to maximize performance. Since the buffer is by far the most heavily used object in a render operation, its important!

When calling `render()` on a template that does not specify any output encoding (i.e. its `ascii`), Python's `cStringIO` module, which cannot handle encoding of non-ascii `unicode` objects (even though it can send raw bytestrings through), is used for buffering. Otherwise, a custom Mako class called `FastEncodingBuffer` is used, which essentially is a super dumbed-down version of `StringIO` that gathers all strings into a list and uses `u''.join(elements)` to produce the final output - its markedly faster than `StringIO`.

back to section top
Previous: The Unicode Chapter

### Table of Contents

### Caching

Any template or component can be cached using the `cache` argument to the `<%page>` or `<%def>` directives:

    <%page cached="True"/>

    template text

The above template, after being executed the first time, will store its content within a cache that by default is scoped within memory. Subsequent calls to the template's `render()` method will return content directly from the cache. When the `Template` object itself falls out of scope, its corresponding cache is garbage collected along with the template.

Caching requires that the `beaker` package be installed on the system.

The caching flag and all its options can be used with the `<%def>` tag.

    <%def name="mycomp" cached="True" cache_timeout="30" cache_type="memory">
        other text
    </%def>

### 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`. (TODO: describe extra arguments for memcached)

- 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.

- 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

back to section top