minijinja 2.2.0

Python的MiniJinja：Rust和Python的强大模板引擎

minijinja-py是MiniJinja的Python绑定实验版本。与Rust版本相比，功能有限。这些绑定使用maturin和pyo3。

当不需要Jinja2的全部功能，且希望Rust和Python之间具有相同的数据集渲染体验时，可以考虑使用MiniJinja代替Jinja2。

使用这些绑定，MiniJinja可以渲染传递给模板的一些Python对象和值，但在可执行方面存在明显限制。

要安装Python的MiniJinja，可以从PyPI 获取 软件包。

$ pip install minijinja

基本API

基本API隐藏在Environment对象后面。它的行为几乎与minijinja相同，但有一些Python特定的更改。例如，您可以使用env.debug = True而不是env.set_debug(True)。此外，您可以直接将模板的字典传递给环境，或者传递一个loader函数，而不是使用add_template或附加source。

from minijinja import Environment

env = Environment(templates={
    "template_name": "Template source"
})

要渲染模板，可以使用render_template方法

result = env.render_template('template_name', var1="value 1", var2="value 2")
print(result)

目的

MiniJinja试图与Jinja2达到相当高的兼容性，但并不试图以任何代价来实现这一点。因此，您会发现相当多的模板在MiniJinja中无法渲染，尽管它们可能看起来相当无害。然而，您可以编写在Jinja2和MiniJinja中渲染相同结果的模板。这引发了一个问题，为什么您可能想使用MiniJinja。

主要好处是在Rust和Python中达到完全相同的结果。此外，MiniJinja比Jinja2拥有更强的沙盒功能，在某些情况下可能表现得更好。但是，您应该意识到，由于在任一方向上都需要进行序列化，因此会损失一定程度的信息。

动态模板加载

MiniJinja的Python绑定继承了MiniJinja加载模板的底层行为。模板在首次使用时加载，然后进行缓存。模板通过加载器加载。要触发重新加载，您可以调用env.reload()，或者将env.reload_before_render设置为True。

def my_loader(name):
    segments = []
    for segment in name.split("/"):
        if "\\" in segment or segment in (".", ".."):
            return None
        segments.append(segment)
    try:
        with open(os.path.join(TEMPLATES, *segments)) as f:
            return f.read()
    except (IOError, OSError):
        pass

env = Environment(loader=my_loader)
env.reload_before_render = True
print(env.render_template("index.html"))

或者，可以使用env.add_template和env.remove_template手动加载和卸载模板。

自动转义

默认行为是在文件名以.html结尾时使用自动转义。您可以通过重写auto_escape_callback来定制此行为。

env = Environment(auto_escape_callback=lambda x: x.endswith((".html", ".foo")))

如果Python端可用，MiniJinja将使用markupsafe。它将尊重__html__。

终结器

与MiniJinja中的自定义格式化程序不同，您可以定义一个终结器，这与Jinja2中的工作方式相似。它传递一个值（或者如果使用pass_state，还可以作为第一个参数传递可选的状态），并可以返回一个新值。如果返回特殊的NotImplemented值，则将渲染原始值而无需任何修改。

from minijinja import Environment

def finalizer(value):
    if value is None:
	return ""
    return NotImplemented

env = Environment(finalizer=finalizer)
assert env.render_str("{{ none }}") == ""

状态访问

传递给环境的函数，如过滤器或全局函数，可以选择使用pass_state参数传递模板状态。这与Jinja2中的pass_context类似。它可以用来查看模板的名称或查找上下文中的变量。

from minijinja import pass_state

@pass_state
def my_filter(state, value):
    return state.lookup("a_variable") + value

env.add_filter("add_a_variable", my_filter)

运行时行为

MiniJinja使用自己的运行时模型，这与Python运行时模型不匹配。因此，两者之间存在行为差异，但已做出了有限的努力来弥合这些差异。例如，您将能够调用一些类型的某些方法，但对于像dict和list这样的内置类型，MiniJinja在所有情况下都不会在其一侧公开它们的方法。一个本地产生的MiniJinja映射（例如，使用dict全局函数）将没有.items()方法，而传递给MiniJinja的Python字典将会有。

以下是这对于一些基本类型的意义

• Python字典和列表（以及其他作为序列行为的对象）在MiniJinja一侧的表示与在Python中非常相似。
• 在MiniJinja一侧，元组表示为列表，但如果将其传递回Python，将再次作为元组出现。
• 在MiniJinja中，Python对象以类似dict的方式表示，但保留了所有有意义的Python API。这意味着它们通过__str__进行字符串化，并允许MiniJinja代码调用它们的非下划线方法。请注意，目前没有使用额外的安全层，因此请小心处理传递的内容。
• 当字符串子类存在__html__属性时，MiniJinja的Python绑定可以理解它。这意味着markupsafe.Markup对象在MiniJinja中会显示为安全字符串。这些信息也可以反向流回Python。
• 对象的字符串化使用__str__，这就是为什么混合Python和MiniJinja对象有时会有些令人困惑。
• 在Jinja2中，foo["bar"]和foo.bar之间存在差异，这可以用来区分属性和键，但在MiniJinja中没有这种差异。但是，方法是可以区分的，所以foo.items()是有效的，并且会在所有情况下正确调用该方法。

赞助商

如果您喜欢这个项目并觉得它很有用，您可以通过成为赞助商。

许可证和链接

• 文档
• 示例
• 问题跟踪器
• MiniJinja游乐场
• 许可证： Apache-2.0