譯者前言（伍迪·?？怂梗?/p>

Mako 是一個模板引擎，快速而強大。它的語法類似于Python，可以隨時在模板中創(chuàng)建可復(fù)用的函數(shù)，靈活性比較高。讓我想起當(dāng)初學(xué)寫ASP的感覺。

Mako的主頁地址：

相比之下，Django內(nèi)置的模板引擎，為了保持所謂模板語法的純粹和簡潔，更純粹地滿足MVC模式的要求，犧牲了很大的靈活性，一些高級功能不得不使用標(biāo)簽和過濾器要實現(xiàn)，它的寫法不是很方便。而我前段時間也為此苦惱，曾經(jīng)想過如何在Django中學(xué)習(xí)一點Karrigell的免費pih方法，但時間不夠，*后還是忍不住了。

因此，將 Mako 集成到 Django 中以替換 Django 自帶的模板引擎可能是一個很好的方法?？梢蕴岣吣０宓撵`活性和可操作性。在這方面，黃毅和力摩豆做了很多努力：

我現(xiàn)在想做的是翻譯真子的文件。該文件的正文從下面開始。

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

原來的：

翻譯：

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

下一部分：語法

目錄

基本用法

使用基礎(chǔ)

本節(jié)介紹 Mako 模板的 Python API。如果你在 Pylons 等 web 框架中使用 Mako，那么集成 Mako API 的工作可能已經(jīng)為你完成了。您可以直接跳到下一部分，語法。

*簡單的方法是創(chuàng)建一個模板并通過 Template 類進(jìn)行渲染：

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

在上面的例子中，傳遞給 Template 的文本參數(shù)被編譯成一個 python 模塊。該模塊有一個 render_body() 函數(shù)來輸出模板內(nèi)容。當(dāng) mytemplate.render() 被調(diào)用時，Mako 將為這個模板創(chuàng)建一個運行時環(huán)境，調(diào)用 render_body() 函數(shù)，然后將其輸出捕獲到緩沖區(qū)，然后返回其字符串內(nèi)容。

render_body() 函數(shù)中的代碼可以訪問包含一些變量的命名空間。您可以向 render() 方法傳遞額外的關(guān)鍵字參數(shù)，這些參數(shù)將轉(zhuǎn)換為可訪問的變量：

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

template.render() 方法將使 Mako 創(chuàng)建一個 Context 對象，該對象包含模板可訪問的所有變量的名稱和用于捕獲輸出的緩沖區(qū)。也可以自己創(chuàng)建一個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 關(guān)鍵字參數(shù)從文件加載模板的內(nèi)容：

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

為了提高性能模板化翻譯，從文件中加載的Template可以將其生成的模塊的源代碼以普通python模塊文件（.py）的形式緩存在文件系統(tǒng)中。只需添加一個參數(shù) module_directory 即可：

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

當(dāng)上面的代碼被渲染時，文件 /tmp/mako_modules/docs/mytmpl.txt.py 將被創(chuàng)建。下次使用相同參數(shù)調(diào)用 Template 對象時，將直接重用模塊文件。

使用模板查找

在模板中，我們有時需要調(diào)用或引用其他模板的內(nèi)容，這就涉及到模板搜索和定位問題，通常使用簡單的URI字符串來定位。我們使用 TemplateLookup 類來處理這個任務(wù)。此類的構(gòu)造函數(shù)需要傳遞路徑列表來查找模板。然后我們將這個 TemplateLookup 對象以關(guān)鍵字參數(shù)的形式傳遞給 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)

在上面的示例中，創(chuàng)建了一個文本模板，其中包含對 header.txt 文件的引用。在哪里可以找到 header.txt 由 TemplateLookup 指示，它是“/docs”目錄。

通常，應(yīng)用程序?qū)⒛０逡晕谋疚募男问奖４嬖谖募到y(tǒng)中。為了方便，我們可以直接通過 TemplateLookup 獲取模板對象，使用 TemplateLookup 的 get_template 方法模板化翻譯，將模板的 URI 作為參數(shù)傳遞：

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)

當(dāng) lookup 尋找模板時，它會嘗試通過將我們提供的模板 URI 附加到每個搜索路徑來獲取模板文件。如果沒有找到，則會引發(fā) TopLevelNotFound 異常，這是 Mako 的自定義異常類型。

當(dāng)查找找到模板時，它還為模板分配一個 uri 屬性。這個 uri 是傳遞給 get_template() 方法的參數(shù)。模板可以使用這個 uri 來計算其對應(yīng)模塊文件的名稱。例如，在上面的示例中，URI 名稱參數(shù) /etc/beans/info.txt 將導(dǎo)致創(chuàng)建模塊文件 /tmp/mako_modules/etc/beans/info.txt.py。

設(shè)置集合的大小

TemplateLookup 還在內(nèi)存中緩存了一組模板，因此并非每個請求都會導(dǎo)致模板重新編譯和模塊重新加載。默認(rèn)的 TemplateLookup 大小不受限制，但您可以通過 collection_size 參數(shù)對其進(jìn)行限制：

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

上述查找將繼續(xù)將模板加載到內(nèi)存中，直到達(dá)到 500，它會根據(jù)“*近*少訪問”原則清除一定比例的模板緩存條目。

設(shè)置文件系統(tǒng)檢查

另一個與 TemplateLookup 相關(guān)的標(biāo)志是 filesystem_checks。默認(rèn)為 True，每次 get_template() 方法返回模板時，都會將原始模板文件的修訂時間與上次加載模板的時間進(jìn)行比較。如果文件被更新，其內(nèi)容將被加載。，并重新編譯模板。在生產(chǎn)環(huán)境中，將filesystem_checks設(shè)置為False可以帶來一定的性能提升（與具體的文件系統(tǒng)有關(guān)）。

使用 Unicode 和編碼

Template 和 TemplateLookup 都可以接受 output_encoding 和 encoding_errors 參數(shù)，它們用于以 Python 支持的任何方式對輸出進(jìn)行編碼：

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() 方法可以將模板的輸出轉(zhuǎn)換為 Python Unicode 對象并返回：

print mytemplate.render_unicode()

上述方法調(diào)用不提供輸出編碼參數(shù)，可以使用如下語法進(jìn)行編碼：

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

請注意，Mako 能夠以任何編碼或 unicode 形式返回數(shù)據(jù)，這意味著模板內(nèi)的輸出流是 Python unicode 對象。這種行為在 Unicode 章節(jié)中有詳細(xì)描述。

處理異常

模板異常可能出現(xiàn)在兩個完全不同的地方。第一個是在您查找、分析和編譯模板時，另一個是在您運行模板時。

在模板運行過程中，通常會從導(dǎo)致問題的python代碼中拋出異常。Mako 有自己的一組異常類，其中大部分針對模板構(gòu)建過程的搜索和詞法分析/編譯階段。Mako 還提供了一些庫函數(shù)，用于幫助提供 Mako 相關(guān)的異常堆棧跟蹤信息，并且可以將異常信息格式化為純文本或 HTML。無論哪種情況，這些處理函數(shù)的作用都是將 Python 文件名、行號和代碼示例轉(zhuǎn)換為 Mako 模板文件名、行號和代碼示例。對應(yīng)于 Moko 模板的跟蹤堆棧中的每一行都被轉(zhuǎn)換回源模板文件。

為了格式化異常跟蹤信息，系統(tǒng)提供了text_error_template 和html_error_template 函數(shù)。它們都使用 sys.exc_info() 函數(shù)來獲取有關(guān)*近拋出的異常的信息。以下是常見的用法：

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 輸出功能也內(nèi)置在模板中。傳遞 format_exceptions 標(biāo)志參數(shù)。這樣，在模板渲染階段引發(fā)的任何異常都會導(dǎo)致模板的輸出被 html_error_template 方法的輸出替換。

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

請注意，上述模板的編譯階段發(fā)生在您構(gòu)造 Template 對象本身時，并且沒有定義輸出流。因此，在搜索/解析/編譯階段引發(fā)的異常不會被處理，而是會像往常一樣繼續(xù)拋出到更高級別的調(diào)用堆棧（傳播）。雖然預(yù)渲染回溯不會包含任何 Mako 特定的行，但這意味著渲染之前發(fā)生的異常和渲染過程中發(fā)生的異常需要以不同的方式處理。因此，上面的 try/except 模式可能是一種更通用的寫法。

錯誤模板函數(shù)使用的內(nèi)部對象是 RichTraceback。該對象也可以直接用于提供自定義錯誤視圖。下面是一個示例應(yīng)用程序，可以描述其常用的 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)

更多關(guān)于 RichTraceback 的深入信息可以在 mako.exceptions 的模塊級文檔中找到。

通用框架的集成

Mako 發(fā)布包包含一些幫助代碼，適用于 Mako 在其他流行的 Web 框架中使用的場景。這是它的概述：

渦輪齒輪/塔架插件

Turbogears 和 Pylons 使用的基本插件方法包含在模塊 mako.ext.turbogears 中，使用 TGPlugin 類。這也是名為 mako 的標(biāo)題 python.templating.engines 下的 setuptools 入口點。

WSGI

在 examples/wsgi/run_wsgi.py 中，包含了一個 WSGI 程序的示例。這個程序的目的是從模板和 htdocs 目錄中提取文件，并包含一個初步的兩個文件布局。WSGI 運行器扮演一個功能齊全的 Web 服務(wù)器的角色。它使用 wsgiutils 來運行自己，并將請求中的 GET 和 POST 參數(shù)信息傳遞給 Context。它可以提供圖像、css 文件和其他類型的文件。并且您可以使用 Mako 的內(nèi)置異常處理功能來顯示錯誤。

色素

mako.ext.pygmentplugin 下包含與 Pygments 兼容的語法高亮模塊。該模塊用于生成 Mako 文檔，還包含標(biāo)題 pygments.lexers 下的各種 setuptools 入口點，包括 mako、html+mako、xml+mako（所有入口點請參見 setup.py 文件）。

下一部分：語法