模板化翻译 Mako 模板系统文档翻译(1) 使用基础

译者前言（伍迪·福克斯）：

Mako 是一个模板引擎，快速而强大。它的语法类似于Python，可以随时在模板中创建可复用的函数，灵活性比较高。让我想起当初学写ASP的感觉。

Mako的主页地址：

相比之下，Django内置的模板引擎，为了保持所谓模板语法的纯粹和简洁，更纯粹地满足MVC模式的要求，牺牲了很大的灵活性，一些高级功能不得不使用标签和过滤器要实现，它的写法不是很方便。而我前段时间也为此苦恼，曾经想过如何在Django中学习一点Karrigell的免费pih方法，但时间不够，*后还是忍不住了。

因此，将 Mako 集成到 Django 中以替换 Django 自带的模板引擎可能是一个很好的方法。可以提高模板的灵活性和可操作性。在这方面，黄毅和力摩豆做了很多努力：

我现在想做的是翻译真子的文件。该文件的正文从下面开始。

-------------------------------------------------- ---------------

原来的：

翻译：

版本：0.1.5 *后更新：05/01/07 20:21:35

下一部分：语法

目录

基本用法

使用基础

本节介绍 Mako 模板的 Python API。如果你在 Pylons 等 web 框架中使用 Mako，那么集成 Mako API 的工作可能已经为你完成了。您可以直接跳到下一部分，语法。

*简单的方法是创建一个模板并通过 Template 类进行渲染：

from mako.template import Template
mytemplate = Template("hello world!")
print mytemplate.render()

在上面的例子中，传递给 Template 的文本参数被编译成一个 python 模块。该模块有一个 render_body() 函数来输出模板内容。当 mytemplate.render() 被调用时，Mako 将为这个模板创建一个运行时环境，调用 render_body() 函数，然后将其输出捕获到缓冲区，然后返回其字符串内容。

render_body() 函数中的代码可以访问包含一些变量的命名空间。您可以向 render() 方法传递额外的关键字参数，这些参数将转换为可访问的变量：

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

template.render() 方法将使 Mako 创建一个 Context 对象，该对象包含模板可访问的所有变量的名称和用于捕获输出的缓冲区。也可以自己创建一个Context对象，命令模板使用这个Context来渲染，只需要使用render_context方法即可：

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

使用基于文件的模板

您还可以使用 filename 关键字参数从文件加载模板的内容：

from mako.template import Template
mytemplate = Template(filename='/docs/mytmpl.txt')
print mytemplate.render()

为了提高性能模板化翻译，从文件中加载的Template可以将其生成的模块的源代码以普通python模块文件（.py）的形式缓存在文件系统中。只需添加一个参数 module_directory 即可：

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

当上面的代码被渲染时，文件 /tmp/mako_modules/docs/mytmpl.txt.py 将被创建。下次使用相同参数调用 Template 对象时，将直接重用模块文件。

使用模板查找

在模板中，我们有时需要调用或引用其他模板的内容，这就涉及到模板搜索和定位问题，通常使用简单的URI字符串来定位。我们使用 TemplateLookup 类来处理这个任务。此类的构造函数需要传递路径列表来查找模板。然后我们将这个 TemplateLookup 对象以关键字参数的形式传递给 Template 对象。

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

在上面的示例中，创建了一个文本模板，其中包含对 header.txt 文件的引用。在哪里可以找到 header.txt 由 TemplateLookup 指示，它是“/docs”目录。

通常，应用程序将模板以文本文件的形式保存在文件系统中。为了方便，我们可以直接通过 TemplateLookup 获取模板对象，使用 TemplateLookup 的 get_template 方法模板化翻译，将模板的 URI 作为参数传递：

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)

当 lookup 寻找模板时，它会尝试通过将我们提供的模板 URI 附加到每个搜索路径来获取模板文件。如果没有找到，则会引发 TopLevelNotFound 异常，这是 Mako 的自定义异常类型。

当查找找到模板时，它还为模板分配一个 uri 属性。这个 uri 是传递给 get_template() 方法的参数。模板可以使用这个 uri 来计算其对应模块文件的名称。例如，在上面的示例中，URI 名称参数 /etc/beans/info.txt 将导致创建模块文件 /tmp/mako_modules/etc/beans/info.txt.py。

设置集合的大小

TemplateLookup 还在内存中缓存了一组模板，因此并非每个请求都会导致模板重新编译和模块重新加载。默认的 TemplateLookup 大小不受限制，但您可以通过 collection_size 参数对其进行限制：

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

上述查找将继续将模板加载到内存中，直到达到 500，它会根据“*近*少访问”原则清除一定比例的模板缓存条目。

设置文件系统检查

另一个与 TemplateLookup 相关的标志是 filesystem_checks。默认为 True，每次 get_template() 方法返回模板时，都会将原始模板文件的修订时间与上次加载模板的时间进行比较。如果文件被更新，其内容将被加载。，并重新编译模板。在生产环境中，将filesystem_checks设置为False可以带来一定的性能提升（与具体的文件系统有关）。

使用 Unicode 和编码

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

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_unicode() 方法可以将模板的输出转换为 Python Unicode 对象并返回：

print mytemplate.render_unicode()

上述方法调用不提供输出编码参数，可以使用如下语法进行编码：

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

请注意，Mako 能够以任何编码或 unicode 形式返回数据，这意味着模板内的输出流是 Python unicode 对象。这种行为在 Unicode 章节中有详细描述。

处理异常

模板异常可能出现在两个完全不同的地方。第一个是在您查找、分析和编译模板时，另一个是在您运行模板时。

在模板运行过程中，通常会从导致问题的python代码中抛出异常。Mako 有自己的一组异常类，其中大部分针对模板构建过程的搜索和词法分析/编译阶段。Mako 还提供了一些库函数，用于帮助提供 Mako 相关的异常堆栈跟踪信息，并且可以将异常信息格式化为纯文本或 HTML。无论哪种情况，这些处理函数的作用都是将 Python 文件名、行号和代码示例转换为 Mako 模板文件名、行号和代码示例。对应于 Moko 模板的跟踪堆栈中的每一行都被转换回源模板文件。

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

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

如果您使用 HTML 输出功能：

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

HTML 输出功能也内置在模板中。传递 format_exceptions 标志参数。这样，在模板渲染阶段引发的任何异常都会导致模板的输出被 html_error_template 方法的输出替换。

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

请注意，上述模板的编译阶段发生在您构造 Template 对象本身时，并且没有定义输出流。因此，在搜索/解析/编译阶段引发的异常不会被处理，而是会像往常一样继续抛出到更高级别的调用堆栈（传播）。虽然预渲染回溯不会包含任何 Mako 特定的行，但这意味着渲染之前发生的异常和渲染过程中发生的异常需要以不同的方式处理。因此，上面的 try/except 模式可能是一种更通用的写法。

错误模板函数使用的内部对象是 RichTraceback。该对象也可以直接用于提供自定义错误视图。下面是一个示例应用程序，可以描述其常用的 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)

更多关于 RichTraceback 的深入信息可以在 mako.exceptions 的模块级文档中找到。

通用框架的集成

Mako 发布包包含一些帮助代码，适用于 Mako 在其他流行的 Web 框架中使用的场景。这是它的概述：

涡轮齿轮/塔架插件

Turbogears 和 Pylons 使用的基本插件方法包含在模块 mako.ext.turbogears 中，使用 TGPlugin 类。这也是名为 mako 的标题 python.templating.engines 下的 setuptools 入口点。

WSGI

在 examples/wsgi/run_wsgi.py 中，包含了一个 WSGI 程序的示例。这个程序的目的是从模板和 htdocs 目录中提取文件，并包含一个初步的两个文件布局。WSGI 运行器扮演一个功能齐全的 Web 服务器的角色。它使用 wsgiutils 来运行自己，并将请求中的 GET 和 POST 参数信息传递给 Context。它可以提供图像、css 文件和其他类型的文件。并且您可以使用 Mako 的内置异常处理功能来显示错误。

色素

mako.ext.pygmentplugin 下包含与 Pygments 兼容的语法高亮模块。该模块用于生成 Mako 文档，还包含标题 pygments.lexers 下的各种 setuptools 入口点，包括 mako、html+mako、xml+mako（所有入口点请参见 setup.py 文件）。

下一部分：语法