Table of Contents

   Templatemytemplate  Template()
 mytemplaterender()

   Templatemytemplate  Template()
 mytemplaterender(name)

   Template
   Context
   StringIOmytemplate  Template()
buf  StringIO()
ctx  Context(buf, name)
mytemplaterender_context(ctx)
 bufgetvalue()

使用基于文件的模板

你也可以从文件中加载 Template 的内容，使用 filename 关键字参数：

   Templatemytemplate  Template(filename)
 mytemplaterender()

为提高性能，从文件中加载的 Template, 可以将它产生的模块的源代码以普通 python 模块文件的形式(.py)，缓存到文件系统中。只要加一个参数 module_directory 即可做到这一点：

   Templatemytemplate  Template(filename, module_directory)
 mytemplaterender()

当上述代码被 render 的时候，会创建文件 /tmp/mako_modules/docs/mytmpl.txt.py. 下一次 Template 对象被用同样参数调用的时候，就会直接重用该模块文件。

使用 TemplateLookup

在模板中，我们有时候需要调用或引用其他模板的内容，这就牵涉一个模板查找定位的问题，通常用简单的 URI 字符串来定位。我们用 TemplateLookup 类来负责这个任务。该类的构造函数需要传递一系列可供查找模板的路径的列表。然后我们再将此 TemplateLookup 对象用关键字参数的形式传递给 Template 对象。

   Template
   TemplateLookupmylookup  TemplateLookup(directories[])
mytemplate  Template(,     lookupmylookup)

上述例子中创建了一个文本模板，其中有一个对 header.txt 文件的包含引用。而从何处去查找 header.txt, 则由 TemplateLookup 指明，是 "/docs" 目录。

通常，应用程序会把模板用文本文件的形式保存在文件系统中。而为了方便起见，我们可以直接通过 TemplateLookup 来获取模板对象，利用 TemplateLookup 的 get_template 方法，并传递模板的 URI 作为参数：

   Template
   TemplateLookupmylookup  TemplateLookup(directories[], module_directory) (templatename, kwargs):mytemplate  mylookupget_template(templatename) mytemplaterender(kwargs)

lookup 在查找模板时通过向其中的每一个搜索路径附加我们提供的模板 URI 的方式，来尝试获取模板文件。如果找不到则引发 TopLevelNotFound 异常，这是一个 Mako 的自定义异常类型。
当 lookup 找到模板时，它还会给 Template 指定一个 uri 属性，这个 uri 就是传递给 get_template() 方法的参数。Template 可以用此 uri 来计算出其对应的模块文件的名称。比如在上述例子中，/etc/beans/info.txt 这个 URI 名称参数，会导致创建模块文件 /tmp/mako_modules/etc/beans/info.txt.py.

mylookup  TemplateLookup(directories[], module_directory, collection_size)

使用 Unicode 和 Encoding

Template 和 TemplateLookup 都可以接受 output_encoding 和 encoding_errors 参数，用来对输出以 Python 支持的任何方式进行编码：

另外，render_unicode() 方法可以将模板的输出转换为一个 Python 的 Unicode 对象返回：

 mytemplaterender_unicode()

上面的方法调用未提供输出编码参数，你可以通过下列语法来进行编码：

 mytemplaterender_unicode()encode(, )

注意， Mako 能将数据返回为任何 encoding 或 unicode 的能力暗示着，模板内部的输出流是一个 Python unicode 对象。这种行为的详细描述在 The Unicode Chapter.

处理异常

模板异常可能在两种截然不同的地方出现。第一种是当你查找，分析和编译模板时，另一种是当你运行模板的时候。
在模板的运行过程中，异常通常从产生问题的 python 代码出抛出。Mako 有其独立的一套异常类，它们大多数针对模板构造过程的查找和词法分析/编译阶段。Mako 还提供了一些库函数，这些函数用来帮助提供 Mako 相关的异常栈跟踪信息，并可用纯文本或 HTML 方式格式化异常信息。不管是哪种情况，这些处理函数的作用在于将 Python 文件名，行号，以及代码例子转换为 Mako 的模板文件名，行号，以及代码范例。在跟踪栈里对应于某个 Moko 模板的每一行，都回被转换为和源模板文件相关的。

为了格式化异常跟踪信息，系统提供了 text_error_template 和 html_error_template 函数。它们都利用了 sys.exc_info() 函数来获取最近抛出的异常信息。下面是常见的用法：

   exceptions:template  lookupget_template(uri) templaterender()
: exceptionstext_error_template()render()

如果使用 HTML 的输出函数：

   exceptions:template  lookupget_template(uri) templaterender()
: exceptionshtml_error_template()render()

HTML 输出函数也内建到了 Template 中。通过 format_exceptions 这个标志位参数。这样，任何在 template 的 render 阶段引发的异常，都会使得 template 的输出内容被 html_error_template 方法的输出所替代。

template  Template(filename, format_exceptions)
 templaterender()

注意，上述模板的编译阶段发生在你构造 Template 对象本身的时候，并且没有定义输出流。所以，在查找/解析/编译阶段引发的异常不会被处理，而是像平常那样被继续抛出到更高层次的调用堆栈上（繁殖, propagate）。虽然 pre-render traceback 不会包含任何 Mako 特定的行，这意味着发生在 rendering 之前的异常，以及 rendering 过程中发生的异常，需要用不同的办法分别处理。因此，上面的 try/except 模式可能是比较通用的一种写法。

被错误模板函数使用的内部对象是 RichTraceback. 该对象也可以被直接用于提供自定义错误视图。下面是一个范例应用，可以描述其一般使用的 API:

   RichTraceback:template  lookupget_template(uri) templaterender()
:traceback  RichTraceback() (filename, lineno, function, line)  tracebacktraceback:   (filename, lineno, function) line,    ((tracebackerror__class____name__), tracebackerror)

关于 RichTraceback 的更深入信息可以查阅 mako.exceptions 的模块级文档。

常见框架的集成

Mako 的发布包包含了一些帮助代码，用于在其他流行的 web 框架中使用 Mako 的场景。下面是其概述：