Specifying the Encoding of a Template File¶

Mako templates support Python’s “magic encoding comment” syntax described in pep-0263:

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

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

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(str("hello world"))

That is, the output of all expressions is run through the ``str`` built-in. This is the default setting, and can be modified to expect various encodings. The str 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 byte-strings that contain an encoding other than ASCII must first be decoded to a Python unicode object.

Similarly, if you are reading data from a file that is streaming bytes, or returning data from some object that is returning a Python byte-string containing a non-ASCII encoding, you have to explicitly 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() built-in for details on this.

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

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

Note that the built-in decode object is slower than the str function, since unlike str it’s not a Python built-in, 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())

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

Template.render_unicode() will return the template output as a Python str 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'))