API

本文档描述 Jinja2 的 API 而不是模板语言。这对实现模板接口，而非创建 Jinja2 模板，是最有用的参考。

基础

Jinja2 使用一个名为 Environment 的中心对象。这个类的实例用于存储配置、全局对象，并用于从文件系统或其它位置加载模板。即使你通过:class:Template类的构造函数用字符串创建模板，也会为你自动创建一个环境，尽管是共享的。

大多数应用在应用初始化时创建一个 Environment 对象，并用它加载模板。
在某些情况下，如果使用多份配置，使用并列的多个环境无论如何是有用的。

配置 Jinja2 为你的应用加载文档的最简单方式看起来大概是这样:

from jinja2 import Environment, PackageLoader
env = Environment(loader=PackageLoader(&"" title="jinja2.Template">Template:

template = env.get_template(&"" title="jinja2.Template">Template 或Environment.from_string() 传递字符串，有许多好处。除了使用上便利，
也使得模板继承成为可能。

Unicode

Jinja2 内部使用 Unicode ，这意味着你需要向渲染函数传递 Unicode 对象或只包含 ASCII 字符的字符串。此外，换行符按照默认 UNIX 风格规定行序列结束（ \n ）。

Python 2.x 支持两种表示字符串对象的方法。一种是 str 类型，另一种是 unicode 类型，它们都继承于 basestring 类型。不幸的是，默认的 str 不 应该用于存储基于文本的信息，除非只用到 ASCII 字符。在 Python 2.6 中，可以 在模块层指定 unicode 为默认值，而在 Python 3 中会是默认值。

要显式使用一个 Unicode 字符串，你需要给字符串字面量加上 u 前缀： u'Hänsel und Gretel sagen Hallo' 。这样 Python 会用当前模块的字符编码来 解码字符串，来把字符串存储为 Unicode 。如果没有指定编码，默认是 ASCII ， 这意味着你不能使用任何非 ASCII 的标识符。

在使用 Unicode 字面量的 Python 模块的首行或第二行添加下面的注释，来妥善设 置模块编码:

"http://docs.python.org/dev/howto/unicode.html" >Unicode documentation 。

另一件重要的事情是 Jinja2 如何处理模板中的字符串字面量。原生实现会对所有 字符串字面量使用 Unicode ，但在过去这是有问题的，因为一些库显式地检查它 们的类型是否为 str 。例如 datetime.strftime 不接受 Unicode 参数。 为了不彻底破坏它， Jinja2 对只有 ASCII 的字符串返回 str，而对其它返回 unicode:

>>> m = Template(u"{% set a, b = &"">低层 API
相反，只在你想深入挖掘 Jinja2 或 开发扩展 时有用。

class jinja2.Environment([options])

The core component of Jinja is the Environment. It contains important shared variables like configuration, filters, tests, globals and others. Instances of this class may be modified if they are not shared and if no template was loaded so far. Modifications on environments after the first template was loaded will lead to surprising effects and undefined behavior.

Here the possible initialization parameters:

block_start_string

The string marking the begin of a block. Defaults to '{%'.

block_end_string

The string marking the end of a block. Defaults to '%}'.

variable_start_string

The string marking the begin of a print statement. Defaults to '{{'.

variable_end_string

The string marking the end of a print statement. Defaults to '}}'.

comment_start_string

The string marking the begin of a comment. Defaults to '{"https://www.xnip.cn/doc/jinja-templates" >行语句.

line_comment_prefix

If given and a string, this will be used as prefix for line based based comments. See also 行语句.

2.2 新版功能.

trim_blocks

If this is set to True the first newline after a block is removed (block, not variable tag!). Defaults to False.

lstrip_blocks

If this is set to True leading spaces and tabs are stripped from the start of a line to a block. Defaults to False.

newline_sequence

The sequence that starts a newline. Must be one of '\r', '\n' or '\r\n'. The default is '\n' which is a useful default for Linux and OS X systems as well as web applications.

keep_trailing_newline

Preserve the trailing newline when rendering templates. The default is False, which causes a single newline, if present, to be stripped from the end of the template.

2.7 新版功能.

extensions

List of Jinja extensions to use. This can either be import paths as strings or extension classes. For more information have a look at the extensions documentation.

optimized

should the optimizer be enabled? Default is True.

undefined

Undefined or a subclass of it that is used to represent undefined values in the template.

finalize

A callable that can be used to process the result of a variable expression before it is output. For example one can convert None implicitly into an empty string here.

autoescape

If set to true the XML/HTML autoescaping feature is enabled by default. For more details about auto escaping see Markup. As of Jinja 2.4 this can also be a callable that is passed the template name and has to return True or False depending on autoescape should be enabled by default.

在 2.4 版更改: autoescape can now be a function

loader

The template loader for this environment.

cache_size

The size of the cache. Per default this is 50 which means that if more than 50 templates are loaded the loader will clean out the least recently used template. If the cache size is set to 0 templates are recompiled all the time, if the cache size is -1 the cache will not be cleaned.

auto_reload

Some loaders load templates from locations where the template sources may change (ie: file system or database). If auto_reload is set to True (default) every time a template is requested the loader checks if the source changed and if yes, it will reload the template. For higher performance it&"">字节码缓存 for more information.

shared

如果模板通过 Template 构造函数创建，会自动创建一个环境。这 些环境被创建为共享的环境，这意味着多个模板拥有相同的匿名环境。对所有 模板共享环境，这个属性为 True ，反之为 False 。

sandboxed

如果环境在沙箱中，这个属性为 True 。沙箱模式见文档中的 SandboxedEnvironment 。

filters

该环境的过滤器字典。只要没有加载过模板，添加新过滤器或删除旧的都是 安全的。自定义过滤器见 自定义过滤器 。有效的过滤器名称见 标识符的说明 。

tests

该环境的测试函数字典。只要没有加载过模板，修改这个字典都是安全的。 自定义测试见 see 自定义测试 。有效的测试名见 标识符的说明 。

globals

一个全局变量字典。这些变量在模板中总是可用。只要没有加载过模板，修 改这个字典都是安全的。更多细节见 全局命名空间 。有效的 对象名见 标识符的说明 。

overlay([options])

Create a new overlay environment that shares all the data with the current environment except of cache and the overridden attributes. Extensions cannot be removed for an overlayed environment. An overlayed environment automatically gets all the extensions of the environment it is linked to plus optional extra extensions.

Creating overlays should happen after the initial environment was set up completely. Not all attributes are truly linked, some are just copied over so modifications on the original environment may not shine through.

undefined([hint, obj, name, exc])

为 name 创建一个新 Undefined 对象。这对可能为某些操作返回 未定义对象过滤器和函数有用。除了 hint ，为了良好的可读性，所有参数 应该作为关键字参数传入。如果提供了 hint ，它被用作异常的错误消息， 否则错误信息会由 obj 和 name 自动生成。 exc 为生成未定义对象而 不允许未定义的对象时抛出的异常。默认的异常是 UndefinedError 。 如果提供了 hint ， name 会被发送。

创建一个未定义对象的最常用方法是只提供名称:

return environment.undefined(name=&"https://www.xnip.cn/doc/jinja-templates"  title="first">first() 过滤器
用这种方法创建一个未定义对象:

return environment.undefined(&"" title="jinja2.Environment.list_templates">list_templates().
Each template returned will be compiled to the target folder or
zipfile.

By default template compilation errors are ignored. In case a log function is provided, errors are logged. If you want template syntax errors to abort the compilation you can set ignore_errors to False and you will get an exception on syntax errors.

If py_compile is set to True .pyc files will be written to the target instead of standard .py files. This flag does not do anything on pypy and Python 3 where pyc files are not picked up by itself and don&"https://www.xnip.cn/doc/jinja-extensions" >extensions to register callbacks and configuration values without breaking inheritance.

from_string(source, globals=None, template_class=None)

Load a template from a string. This parses the source given and returns a Template object.

get_or_select_template(template_name_or_list, parent=None, globals=None)

Does a typecheck and dispatches to select_template() if an iterable of template names is given, otherwise to get_template().

2.3 新版功能.

get_template(name, parent=None, globals=None)

Load a template from the loader. If a loader is configured this method ask the loader for the template and returns a Template. If the parent parameter is not None, join_path() is called to get the real template name before loading.

The globals parameter can be used to provide template wide globals. These variables are available in the context at render time.

If the template does not exist a TemplateNotFound exception is raised.

在 2.4 版更改: If name is a Template object it is returned from the function unchanged.

join_path(template, parent)

Join a template with the parent. By default all the lookups are relative to the loader root so this method returns the template parameter unchanged, but if the paths should be relative to the parent template, this function can be used to calculate the real template name.

Subclasses may override this method and implement template path joining here.

list_templates(extensions=None, filter_func=None)

Returns a list of templates for this environment. This requires that the loader supports the loader&"" title="jinja2.Environment.get_template">get_template() but tries a number of templates before it fails. If it cannot find any of the templates, it will raise a TemplatesNotFound exception.

2.3 新版功能.

在 2.4 版更改: If names contains a Template object it is returned from the function unchanged.

class jinja2.Template

The central template object. This class represents a compiled template and is used to evaluate it.

Normally the template object is generated from an Environment but it also has a constructor that makes it possible to create a template instance directly using the constructor. It takes the same arguments as the environment constructor but it&"" title="jinja2.Template.render">render().

stream([context])

Works exactly like generate() but returns a TemplateStream.

make_module(vars=None, shared=False, locals=None)

This method works like the module attribute when called without arguments but it will evaluate the template on every call rather than caching it. It&"" title="jinja2.Template.new_context">new_context() method.

module

The template as module. This is used for imports in the template runtime but is also useful if one wants to access exported template variables from the Python layer:

>>> t = Template(&"https://www.xnip.cn/doc/jinja-extensions" >自动转义扩展
并为自动转义配置一个合适的默认值。这使得在单个模板基础上开关自动转义成为
可能（比如 HTML 对 文本）

这里推荐为以 .html 、 .htm 、 .xml 以及 .xhtml 的模板开启 自动转义 ，并对所有其它扩展名禁用:

def guess_autoescape(template_name):
    if template_name is None or &"https://www.xnip.cn/doc/jinja-templates" >自动转义扩展 ）。

标识符的说明

Jinja2 使用正规的 Python 2.x 命名规则。有效的标识符必须匹配 [a-zA-Z_][a-zA-Z0-9_]* 。事实上，当前不允许非 ASCII 字符。这个限制可能 会在 Python 3 充分规定 unicode 标识符后消失。

过滤器和测试会在独立的命名空间中查找，与标识符语法有细微区别。过滤器和测 试可以包含点，用于按主题给过滤器和测试分组。例如，把一个名为 to.unicode 的函数添加到过滤器字典是完全有效的。过滤器和测试标识符的正则表达式是 [a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)* 。

未定义类型

这些类可以用作未定义类型。 Environment 的构造函数接受一个可以是 那些类或一个 Undefined 的自定义子类的 undefined 参数。无论何时， 这些对象创建或返回时，模板引擎都不能查出其名称或访问其属性。未定义值上的 某些操作之后是允许的，而其它的会失败。

最接近常规 Python 行为的是 StrictUndefined ，如果它是一个未定义对象， 它不允许除了测试之外的一切操作。

class jinja2.Undefined

The default undefined type. This undefined type can be printed and iterated over, but every other access will raise an UndefinedError:

>>> foo = Undefined(name=&"" title="jinja2.UndefinedError">UndefinedError 或
SecurityError 之一。

_fail_with_undefined_error(*args, **kwargs)

参数任意，调用这个方法时会抛出带有由未定义对象上存储的未定义 hint 生成的错误信息的 _undefined_exception 异常。

class jinja2.DebugUndefined

An undefined that returns the debug info when printed.

>>> foo = DebugUndefined(name=&"https://www.xnip.cn/doc/jinja-templates"  title="undefined">undefined 创建。

实现

Undefined 对象通过重载特殊的 __underscore__ 方法实现。例如 默认的 Undefined 类实现 __unicode__ 为返回一个空字符串，但 __int__ 和其它会始终抛出异常。你可以自己通过返回 0 实现转换为 int:

class NullUndefined(Undefined):
    def __int__(self):
        return 0
    def __float__(self):
        return 0.0

要禁用一个方法，重载它并抛出 _undefined_exception 。因
为这在未定义对象中非常常用，未定义对象有辅助方法
_fail_with_undefined_error() 自动抛出错误。这里的一个类
工作类似正规的 Undefined ，但它在迭代时阻塞:

class NonIterableUndefined(Undefined):

__iter__ = Undefined._fail_with_undefined_error

上下文

class jinja2.runtime.Context

The template context holds the variables of a template. It stores the
values passed to the template and also the names the template exports.
Creating instances is neither supported nor useful as it&"" title="jinja2.Context.parent">parent must not
happen and modifications on vars are allowed from generated
template code only. Template filters and global functions marked as
contextfunction()s get the active context passed as first argument
and are allowed to access the context read-only.The template context supports read only dict operations (get,
keys, values, items, iterkeys, itervalues, iteritems,
__getitem__, __contains__). Additionally there is a resolve()
method that doesn&"" title="jinja2.Undefined">Undefined object for missing variables.

parent

一个模板查找的只读全局变量的词典。这些变量可能来自另一个
Context ，或是 Environment.globals ，或是
Template.globals ，或指向一个由全局变量和传递到渲染函数的变
量联立的字典。它一定不能被修改。

vars

模板局域变量。这个列表包含环境和来自 parent 范围的上下文函数
以及局域修改和从模板中导出的变量。模板会在模板求值时修改这个字典，
但过滤器和上下文函数不允许修改它。

environment

加载该模板的环境

exported_vars

这设定了所有模板导出量的名称。名称对应的值在 vars 字典中。
可以用 get_exported() 获取一份导出变量的拷贝字典。

name

拥有此上下文的模板的载入名。

blocks

模板中块当前映射的字典。字典中的键是块名称，值是注册的块的列表。每个
列表的最后一项是当前活动的块（继承链中最新的）。

eval_ctx

当前的 求值上下文 。

call(callable, *args, **kwargs)

Call the callable with the arguments and keyword arguments
provided but inject the active context or environment as first
argument if the callable is a contextfunction() or
environmentfunction().

get_all()

Return a copy of the complete context as dict including the
exported variables.

get_exported()

Get a new dict with the exported variables.

resolve(key)

Looks up a variable like __getitem__ or get but returns an
Undefined object with the name of the name looked up.

实现

Python frame 中的局域变量在函数中是不可变的，出于同样的原因，上下文是不可
变的。 Jinja2 和 Python 都不把上下文/ frame 作为变量的数据存储，而只作为
主要的数据源。

当模板访问一个模板中没有定义的变量时， Jinja2 在上下文中查找变量，此后，
这个变量被视为其是在模板中定义得一样。

加载器

加载器负责从诸如文件系统的资源加载模板。环境会把编译的模块像
Python 的 sys.modules 一样保持在内存中。与 sys.models 不同，无论如何这个
缓存默认有大小限制，且模板会自动重新加载。
所有的加载器都是 BaseLoader 的子类。如果你想要创建自己的加载器，继
承 BaseLoader 并重载 get_source 。

class jinja2.BaseLoader

Baseclass for all loaders. Subclass this and override get_source to
implement a custom loading mechanism. The environment provides a
get_template method that calls the loader&"" title="jinja2.Template">Template object.A very basic example for a loader that looks up templates on the file
system could look like this:

from jinja2 import BaseLoader, TemplateNotFound
from os.path import join, exists, getmtime

class MyLoader(BaseLoader):

    def __init__(self, path):
        self.path = path

    def get_source(self, environment, template):
        path = join(self.path, template)
        if not exists(path):
            raise TemplateNotFound(template)
        mtime = getmtime(path)
        with file(path) as f:
            source = f.read().decode(&"" title="jinja2.BaseLoader.get_source">get_source().  Subclasses should not
override this method as loaders working on collections of other
loaders (such as PrefixLoader or ChoiceLoader)
will not call this method but get_source directly.

这里有一个 Jinja2 提供的内置加载器的列表:

class jinja2.FileSystemLoader(searchpath, encoding='utf-8')

Loads templates from the file system. This loader can find templates in folders on the file system and is the preferred way to load them.

The loader takes the path to the templates as string, or if multiple locations are wanted a list of them which is then looked up in the given order:

>>> loader = FileSystemLoader(&"" title="jinja2.BaseLoader.get_source">BaseLoader.get_source() which has the same
return value.

class jinja2.PrefixLoader(mapping, delimiter='/')

A loader that is passed a dict of loaders where each loader is bound to a prefix. The prefix is delimited from the template by a slash per default, which can be changed by setting the delimiter argument to something else:

loader = PrefixLoader({
    &"" title="jinja2.Environment.compile_templates">Environment.compile_templates().

字节码缓存

Jinja 2.1 和更高的版本支持外部字节码缓存。字节码缓存使得在首次使用时把生成的字节码 存储到文件系统或其它位置来避免处理模板。

这在当你有一个在首个应用初始化的 web 应用， Jinja 一次性编译大量模板拖慢应用时尤其 有用。

要使用字节码缓存，把它实例化并传给 Environment 。

class jinja2.BytecodeCache

To implement your own bytecode cache you have to subclass this class and override load_bytecode() and dump_bytecode(). Both of these methods are passed a Bucket.

A very basic bytecode cache that saves the bytecode on the file system:

from os import path

class MyCache(BytecodeCache):

    def __init__(self, directory):
        self.directory = directory

    def load_bytecode(self, bucket):
        filename = path.join(self.directory, bucket.key)
        if path.exists(filename):
            with open(filename, &"" title="jinja2.Environment">Environment

key

该 bucket 的唯一键

code

如果已加载，则为字节码，否则为 None 。

bytecode_from_string(string)

Load bytecode from a string.

bytecode_to_string()

Return the bytecode as string.

load_bytecode(f)

Loads bytecode from a file or file like object.

reset()

Resets the bucket (unloads the bytecode).

write_bytecode(f)

Dump the bytecode into the file or file like object passed.

内建的字节码缓存:

class jinja2.FileSystemBytecodeCache(directory=None, pattern='__jinja2_%s.cache')

A bytecode cache that stores bytecode on the filesystem. It accepts two arguments: The directory where the cache items are stored and a pattern string that is used to build the filename.

If no directory is specified a default cache directory is selected. On Windows the user&"http://werkzeug.pocoo.org/" >werkzeug.contrib.cache

• python-memcached

• cmemcache

(Unfortunately the django cache interface is not compatible because it does not support storing binary data, only unicode. You can however pass the underlying cache client to the bytecode cache which is available as django.core.cache.cache._client.)

The minimal interface for the client passed to the constructor is this:

class MinimalClientInterface

set(key, value[, timeout])

Stores the bytecode in the cache. value is a string and timeout the timeout of the key. If timeout is not provided a default timeout or no timeout should be assumed, if it&"" title="jinja2.Environment">Environment is passed to the filter as first argument.

jinja2.contextfilter(f)

Decorator for marking context dependent filters. The current Context will be passed as first argument.

jinja2.evalcontextfilter(f)

Decorator for marking eval-context dependent filters. An eval context object is passed as first argument. For more information about the eval context, see 求值上下文.

2.4 新版功能.

jinja2.environmentfunction(f)

This decorator can be used to mark a function or method as environment callable. This decorator works exactly like the contextfunction() decorator just that the first argument is the active Environment and not context.

jinja2.contextfunction(f)

This decorator can be used to mark a function or method context callable. A context callable is passed the active Context as first argument when called from the template. This is useful if a function wants to get access to the context or functions provided on the context object. For example a function that returns a sorted list of template variables the current template exports could look like this:

@contextfunction
def get_exported_names(context):
    return sorted(context.exported_vars)

jinja2.evalcontextfunction(f)

This decorator can be used to mark a function or method as an eval
context callable. This is similar to the contextfunction()
but instead of passing the context, an evaluation context object is
passed. For more information about the eval context, see
求值上下文.2.4 新版功能.

jinja2.escape(s)

把字符串 s 中 & 、 < 、 > 、 ' 和 " 转换为 HTML 安
全的序列。如果你需要在 HTML 中显示可能包含这些字符的文本，可以使用它。这
个函数不会转义对象。这个函数不会转义含有 HTML 表达式比如已转义数据的对象。返回值是一个 Markup 字符串。

jinja2.clear_caches()

Jinja2 keeps internal caches for environments and lexers. These are
used so that Jinja2 doesn&"" title="jinja2.Undefined">Undefined but looks nicer.
This can be used for custom filters or tests that want to react to
undefined variables. For example a custom default filter can look like
this:

def default(var, default=&"" title="jinja2.Markup">Markup is a direct
subclass of unicode and provides all the methods of unicode just that
it escapes arguments passed and always returns Markup.

The escape function returns markup objects so that double escaping can&"" title="jinja2.Markup">Markup class can be used for three different things: When passed an unicode object it&"https://www.xnip.cn/doc/jinja-templates" title="escape">escape() classmethod to create a Markup object:

>>> Markup.escape("Hello <em>World</em>!")
Markup(u&"https://www.xnip.cn/doc/jinja-templates"  title="escape">escape() function:

>>> em = Markup("<em>%s</em>")
>>> em % "foo & bar"
Markup(u&"https://www.xnip.cn/doc/jinja-templates"  title="escape">escape() with the difference
that for subclasses of Markup this function would return the
correct subclass.

striptags()

Unescape markup into an text_type string and strip all tags. This also resolves known HTML4 and XHTML entities. Whitespace is normalized to one:

>>> Markup("Main »  <em>About</em>").striptags()
u&"" title="jinja2.Markup">Markup 类至少与 Pylons 和 Genshi 兼容。预计不久更多模板
引擎和框架会采用 __html__ 的概念。

异常

exception jinja2.TemplateError(message=None)

Baseclass for all template errors.

exception jinja2.UndefinedError(message=None)

Raised if a template tries to operate on Undefined.

exception jinja2.TemplateNotFound(name, message=None)

Raised if a template does not exist.

exception jinja2.TemplatesNotFound(names=(), message=None)

Like TemplateNotFound but raised if multiple templates are selected. This is a subclass of TemplateNotFound exception, so just catching the base exception will catch both.

2.2 新版功能.

exception jinja2.TemplateSyntaxError(message, lineno, name=None, filename=None)

Raised to tell the user that there is a problem with the template.

message

错误信息的 utf-8 字节串。

lineno

发生错误的行号。

name

模板的加载名的 unicode 字符串。

filename

加载的模板的文件名字节串，以文件系统的编码（多是 utf-8 ， Windows 是 mbcs ）。

文件名和错误消息是字节串而不是 unicode 字符串的原因是，在 Python 2.x 中，不对异常和回溯使用 unicode ，编译器同样。这会在 Python 3 改变。

exception jinja2.TemplateAssertionError(message, lineno, name=None, filename=None)

Like a template syntax error, but covers cases where something in the template caused an error at compile time that wasn&"" title="jinja2.TemplateSyntaxError">TemplateSyntaxError and has the same attributes.

自定义过滤器

自定义过滤器只是常规的 Python 函数，过滤器左边作为第一个参数，其余的参数作 为额外的参数或关键字参数传递到过滤器。

例如在过滤器 {{ 42|myfilter(23) }} 中，函数被以 myfilter(42, 23) 调 用。这里给出一个简单的过滤器示例，可以应用到 datetime 对象来格式化它们:

def datetimeformat(value, format=&"" title="jinja2.Environment.filters">filters 字典来把它注册到模板环境上:

environment.filters[&"" title="jinja2.environmentfilter">environmentfilter() 、 contextfilter() 和
evalcontextfilter() 。

这里是一个小例子，过滤器把一个文本在 HTML 中换行或分段，并标记返回值为安全 的 HTML 字符串，因为自动转义是启用的:

import re
from jinja2 import evalcontextfilter, Markup, escape

_paragraph_re = re.compile(r&"" title="jinja2.contextfilter">contextfilter() 从实际的上下文中访问求值上下
文，或用 evalcontextfilter() 直接把求值上下文传递给函数:

@contextfilter
def filter(context, value):
    result = do_something(value)
    if context.eval_ctx.autoescape:
        result = Markup(result)
    return result

@evalcontextfilter
def filter(eval_ctx, value):
    result = do_something(value)
    if eval_ctx.autoescape:
        result = Markup(result)
    return result

求值上下文一定不能在运行时修改。修改只能在扩展中的
用 nodes.EvalContextModifier 和
nodes.ScopedEvalContextModifier 发生，而不是通过求值上下文对
象本身。

class jinja2.nodes.EvalContext(environment, template_name=None)

Holds evaluation time information. Custom attributes can be attached
to it in extensions.

autoescape

True 或 False 取决于自动转义是否激活。

volatile

如果编译器不能在编译期求出某些表达式的值，为 True 。在运行时应该
始终为 False 。

自定义测试

测试像过滤器一样工作，只是测试不能访问环境或上下文，并且它们不能链式使用。
测试的返回值应该是 True 或 False 。测试的用途是让模板设计者运行类型和
一致性检查。

这里是一个简单的测试，检验一个变量是否是素数:

import math

def is_prime(n):
    if n == 2:
        return True
    for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1):
        if n % i == 0:
            return False
    return True

你可以通过更新环境上的 tests 字典来注册它:

environment.tests[&"" title="jinja2.Environment.globals">Environment.globals 字典中的变量是特殊的，它们对导入的模板也是可用的，
即使它们不通过上下文导入。这是你可以放置始终可访问的变量和函数的地方。此外，
Template.globals 是那些对特定模板可用的变量，即对所有的
render() 调用可用。

低层 API

低层 API 暴露的功能对理解一些实现细节、调试目的或高级 扩展 技巧是有用的。除非你准确地了解你在做什么，否则 不推荐使用这些 API 。

Environment.lex(source, name=None, filename=None)

Lex the given sourcecode and return a generator that yields tokens as tuples in the form (lineno, token_type, value). This can be useful for extension development and debugging templates.

This does not perform preprocessing. If you want the preprocessing of the extensions to be applied you have to filter source through the preprocess() method.

Environment.parse(source, name=None, filename=None)

Parse the sourcecode and return the abstract syntax tree. This tree of nodes is used by the compiler to convert the template into executable source- or bytecode. This is useful for debugging or to extract information from templates.

If you are developing Jinja2 extensions this gives you a good overview of the node tree generated.

Environment.preprocess(source, name=None, filename=None)

Preprocesses the source with all extensions. This is automatically called for all parsing and compiling methods but not for lex() because there you usually only want the actual source tokenized.

Template.new_context(vars=None, shared=False, locals=None)

Create a new Context for this template. The vars provided will be passed to the template. Per default the globals are added to the context. If shared is set to True the data is passed as it to the context without adding the globals.

locals can be a dict of local variables for internal usage.

Template.root_render_func(context)

这是低层的渲染函数。它接受一个必须由相同模板或兼容的模板的 new_context() 创建的 Context 。这个渲染函数由编译器从 模板代码产生，并返回一个生产 unicode 字符串的生成器。

如果模板代码中发生了异常，模板引擎不会重写异常而是直接传递原始的异常。 事实上，这个函数只在 render() / generate() / stream() 的调用里被调用。

Template.blocks

一个块渲染函数的字典。其中的每个函数与 root_render_func() 的工作 相同，并且有相同的限制。

Template.is_up_to_date

如果有可用的新版本模板，这个属性是 False ，否则是 True 。

注意

低层 API 是易碎的。未来的 Jinja2 的版本将不会试图以不向后兼容的方式修改它， 而是在 Jinja2 核心的修改中表现出来。比如如果 Jinja2 在之后的版本中引入一 个新的 AST 节点，它会由 parse() 返回。

元 API

2.2 新版功能.

元 API 返回一些关于抽象语法树的信息，这些信息能帮助应用实现更多的高级模板概 念。所有的元 API 函数操作一个 Environment.parse() 方法返回的抽象语法 树。

jinja2.meta.find_undeclared_variables(ast)

Returns a set of all variables in the AST that will be looked up from the context at runtime. Because at compile time it&"" title="jinja2.TemplateAssertionError">TemplateAssertionError during compilation and as a matter of fact this function can currently raise that exception as well.

jinja2.meta.find_referenced_templates(ast)

Finds all the referenced templates from the AST. This will return an iterator over all the hardcoded template extensions, inclusions and imports. If dynamic inheritance or inclusion is used, None will be yielded.

>>> from jinja2 import Environment, meta
>>> env = Environment()
>>> ast = env.parse('{% extends "layout.html" %}{% include helper %}')
>>> list(meta.find_referenced_templates(ast))
['layout.html', None]

This function is useful for dependency tracking. For example if you want
to rebuild parts of the website after a layout template has changed.