擴充功能

Jinja 支援可新增額外篩選器、測試、全域變數，甚至擴充解析器的擴充功能。擴充功能的主要動機是將經常使用的程式碼移至可重複使用的類別中，例如新增國際化支援。

新增擴充功能

擴充功能會在建立 Jinja 環境時新增。若要新增擴充功能，請將擴充功能類別或匯入路徑的清單傳遞至 Environment 建構函式的 extensions 參數。以下範例建立了一個載入 i18n 擴充功能的 Jinja 環境

jinja_env = Environment(extensions=['jinja2.ext.i18n'])

若要在建立環境後新增擴充功能，請使用 add_extension() 方法

jinja_env.add_extension('jinja2.ext.debug')

i18n 擴充功能

匯入名稱： jinja2.ext.i18n

i18n 擴充功能可以與 gettext 或 Babel 搭配使用。啟用後，Jinja 會提供一個 trans 語句，將區塊標記為可翻譯，並呼叫 gettext。

啟用後，應用程式必須提供 gettext、ngettext 以及可選的 pgettext 和 npgettext 函數，無論是全域還是渲染時。 _() 函數會被新增為 gettext 函數的別名。

環境方法

啟用擴充功能後，環境會提供以下額外方法

jinja2.Environment.install_gettext_translations(translations, newstyle=False)

為環境全域安裝翻譯。 translations 物件必須實作 gettext、ngettext，以及可選的 pgettext 和 npgettext。支援 gettext.NullTranslations、gettext.GNUTranslations 以及 Babel 的 Translations。

更新日誌

在版本 3.0 中變更： 新增 pgettext 和 npgettext。

在版本 2.5 中變更： 新增新式 gettext 支援。

jinja2.Environment.install_null_translations(newstyle=False)

安裝無操作的 gettext 函數。如果您想讓應用程式準備好進行國際化，但還不想實作完整系統，這會很有用。

更新日誌

在版本 2.5 中變更： 新增新式 gettext 支援。

jinja2.Environment.install_gettext_callables(gettext, ngettext, newstyle=False, pgettext=None, npgettext=None)

將指定的 gettext、ngettext、pgettext 和 npgettext 可呼叫物件安裝到環境中。它們的行為應與 gettext.gettext()、gettext.ngettext()、gettext.pgettext() 和 gettext.npgettext() 完全相同。

如果啟用 newstyle，則會包裝可呼叫物件，使其像新式可呼叫物件一樣運作。如需詳細資訊，請參閱 新式 Gettext。

更新日誌

在版本 3.0 中變更： 新增 pgettext 和 npgettext。

在版本 2.5 中新增： 新增新式 gettext 支援。

jinja2.Environment.uninstall_gettext_translations()

解除安裝環境的全域安裝翻譯。

jinja2.Environment.extract_translations(source)

從指定的範本節點或來源中擷取可本地化的字串。

對於找到的每個字串，此函數會產生一個 (lineno, function, message) 元組，其中

  • lineno 是找到字串的行號。

  • function 是使用的 gettext 函數的名稱（如果字串是從嵌入式 Python 程式碼中擷取的）。

  • message 是字串本身，或針對具有多個參數的函數，則為字串元組。

如果安裝了 Babel，請參閱 Babel 以擷取字串。

對於一個提供多種語言但所有使用者都使用相同語言的 Web 應用程式（例如，為法國社群安裝的多語言論壇軟體），可以在建立環境時安裝翻譯。

translations = get_gettext_translations()
env = Environment(extensions=["jinja2.ext.i18n"])
env.install_gettext_translations(translations)

get_gettext_translations 函數會傳回目前配置的翻譯器，例如使用 gettext.find。

模板設計師使用 i18n 擴充功能的說明，請參閱 模板文件。

空白修剪

更新日誌

新增於 2.10 版。

在 {% trans %} 區塊中，修剪換行和空白可能很有用，這樣文本區塊在翻譯檔案中看起來就像一個帶有單個空格的簡單字串。

透過啟用 ext.i18n.trimmed 策略，可以自動修剪換行和周圍的空白。

新式 Gettext

更新日誌

新增於 2.5 版。

新式 gettext 呼叫的輸入量較少、較不容易出錯，並且更好地支援自動跳脫。

您可以透過設定 env.newstyle_gettext = True 或將 newstyle=True 傳遞給 env.install_translations 來使用「新式」gettext 呼叫。它們完全受 Babel 提取工具支援，但可能無法與其他提取工具一起正常使用。

使用標準 gettext 呼叫，字串格式化是透過 |format 篩選器完成的獨立步驟。這需要為 ngettext 呼叫重複工作。

{{ gettext("Hello, World!") }}
{{ gettext("Hello, %(name)s!")|format(name=name) }}
{{ ngettext(
       "%(num)d apple", "%(num)d apples", apples|count
   )|format(num=apples|count) }}
{{ pgettext("greeting", "Hello, World!") }}
{{ npgettext(
       "fruit", "%(num)d apple", "%(num)d apples", apples|count
   )|format(num=apples|count) }}

新式 gettext 使格式化成為呼叫的一部分，並在幕後強制執行更多一致性。

{{ gettext("Hello, World!") }}
{{ gettext("Hello, %(name)s!", name=name) }}
{{ ngettext("%(num)d apple", "%(num)d apples", apples|count) }}
{{ pgettext("greeting", "Hello, World!") }}
{{ npgettext("fruit", "%(num)d apple", "%(num)d apples", apples|count) }}

新式 gettext 的優點是

  • 沒有單獨的格式化步驟，您不必記住使用 |format 篩選器。

  • 只允許使用命名佔位符。這解決了翻譯人員面臨的一個常見問題，因為位置佔位符無法有意義地切換位置。命名佔位符始終攜帶關於哪個值放在哪裡的語義資訊。

  • 即使未使用佔位符，也會使用字串格式化，這使得所有字串都使用一致的格式。請記住將任何原始百分號跳脫為 %%，例如 100%%。

  • 翻譯後的字串被標記為安全，格式化會根據需要執行跳脫。如果參數已經跳脫，則將其標記為 |safe。

表達式語句

**匯入名稱：** jinja2.ext.do

「do」又稱表達式語句擴充功能，它在模板引擎中新增了一個簡單的 do 標籤，其工作方式類似於變數表達式，但會忽略傳回值。

迴圈控制

**匯入名稱：** jinja2.ext.loopcontrols

此擴充功能新增了對迴圈中 break 和 continue 的支援。啟用後，Jinja 會提供這兩個關鍵字，它們的功能與 Python 中的完全相同。

With 語句

**匯入名稱：** jinja2.ext.with_

更新日誌

在 2.9 版中變更： 此擴充功能現在是內建的，不再執行任何操作。

自動跳脫擴充功能

**匯入名稱：** jinja2.ext.autoescape

更新日誌

在 2.9 版中變更： 此擴充功能已被移除，現在是內建的。啟用擴充功能不再執行任何操作。

除錯擴充功能

**匯入名稱：** jinja2.ext.debug

新增 {% debug %} 標籤以傾印目前的上下文以及可用的篩選器和測試。這對於查看在模板中可以使用哪些內容而不需設定除錯器很有用。

撰寫擴充功能

透過撰寫擴充功能，您可以將自訂標籤新增到 Jinja。這是一項非比尋常的任務，通常不需要，因為預設標籤和表達式涵蓋了所有常見的使用案例。i18n 擴充功能就是擴充功能為何有用的好例子。另一個例子是片段快取。

撰寫擴充功能時，您必須記住，您正在使用 Jinja 模板編譯器，它不會驗證您傳遞給它的節點樹。如果 AST 格式錯誤，您將遇到各種難以除錯的編譯器或執行階段錯誤。始終確保您正確使用您建立的節點。以下的 API 文件顯示了存在哪些節點以及如何使用它們。

擴充功能範例

快取

以下範例透過使用 cachelib 程式庫為 Jinja 實作 cache 標籤

from jinja2 import nodes
from jinja2.ext import Extension


class FragmentCacheExtension(Extension):
    # a set of names that trigger the extension.
    tags = {"cache"}

    def __init__(self, environment):
        super().__init__(environment)

        # add the defaults to the environment
        environment.extend(fragment_cache_prefix="", fragment_cache=None)

    def parse(self, parser):
        # the first token is the token that started the tag.  In our case
        # we only listen to ``'cache'`` so this will be a name token with
        # `cache` as value.  We get the line number so that we can give
        # that line number to the nodes we create by hand.
        lineno = next(parser.stream).lineno

        # now we parse a single expression that is used as cache key.
        args = [parser.parse_expression()]

        # if there is a comma, the user provided a timeout.  If not use
        # None as second parameter.
        if parser.stream.skip_if("comma"):
            args.append(parser.parse_expression())
        else:
            args.append(nodes.Const(None))

        # now we parse the body of the cache block up to `endcache` and
        # drop the needle (which would always be `endcache` in that case)
        body = parser.parse_statements(["name:endcache"], drop_needle=True)

        # now return a `CallBlock` node that calls our _cache_support
        # helper method on this extension.
        return nodes.CallBlock(
            self.call_method("_cache_support", args), [], [], body
        ).set_lineno(lineno)

    def _cache_support(self, name, timeout, caller):
        """Helper callback."""
        key = self.environment.fragment_cache_prefix + name

        # try to load the block from the cache
        # if there is no fragment in the cache, render it and store
        # it in the cache.
        rv = self.environment.fragment_cache.get(key)
        if rv is not None:
            return rv
        rv = caller()
        self.environment.fragment_cache.add(key, rv, timeout)
        return rv

以下是如何在環境中使用它

from jinja2 import Environment
from cachelib import SimpleCache

env = Environment(extensions=[FragmentCacheExtension])
env.fragment_cache = SimpleCache()

在模板內，可以將區塊標記為可快取。以下範例將側邊欄快取 300 秒

{% cache 'sidebar', 300 %}
<div class="sidebar">
    ...
</div>
{% endcache %}

內嵌 gettext

以下範例示範如何使用 Extension.filter_stream() 來解析對 _() gettext 函數的呼叫，該函數與靜態資料內嵌，而無需 Jinja 區塊。

<h1>_(Welcome)</h1>
<p>_(This is a paragraph)</p>

它需要載入和配置 i18n 擴充功能。

import re

from jinja2.exceptions import TemplateSyntaxError
from jinja2.ext import Extension
from jinja2.lexer import count_newlines
from jinja2.lexer import Token

_outside_re = re.compile(r"\\?(gettext|_)\(")
_inside_re = re.compile(r"\\?[()]")


class InlineGettext(Extension):
    """This extension implements support for inline gettext blocks::

        <h1>_(Welcome)</h1>
        <p>_(This is a paragraph)</p>

    Requires the i18n extension to be loaded and configured.
    """

    def filter_stream(self, stream):
        paren_stack = 0

        for token in stream:
            if token.type != "data":
                yield token
                continue

            pos = 0
            lineno = token.lineno

            while True:
                if not paren_stack:
                    match = _outside_re.search(token.value, pos)
                else:
                    match = _inside_re.search(token.value, pos)
                if match is None:
                    break
                new_pos = match.start()
                if new_pos > pos:
                    preval = token.value[pos:new_pos]
                    yield Token(lineno, "data", preval)
                    lineno += count_newlines(preval)
                gtok = match.group()
                if gtok[0] == "\\":
                    yield Token(lineno, "data", gtok[1:])
                elif not paren_stack:
                    yield Token(lineno, "block_begin", None)
                    yield Token(lineno, "name", "trans")
                    yield Token(lineno, "block_end", None)
                    paren_stack = 1
                else:
                    if gtok == "(" or paren_stack > 1:
                        yield Token(lineno, "data", gtok)
                    paren_stack += -1 if gtok == ")" else 1
                    if not paren_stack:
                        yield Token(lineno, "block_begin", None)
                        yield Token(lineno, "name", "endtrans")
                        yield Token(lineno, "block_end", None)
                pos = match.end()

            if pos < len(token.value):
                yield Token(lineno, "data", token.value[pos:])

        if paren_stack:
            raise TemplateSyntaxError(
                "unclosed gettext expression",
                token.lineno,
                stream.name,
                stream.filename,
            )

擴充功能 API

擴充功能

擴充功能始終必須擴充 jinja2.ext.Extension 類別

class jinja2.ext.Extension(environment)

擴充功能可用於在解析器級別向 Jinja 模板系統新增額外功能。自訂擴充功能繫結到環境，但可能不會在 self 上儲存特定於環境的資料。這樣做的原因是，透過建立副本並重新分配 environment 屬性，可以將擴充功能繫結到另一個環境（用於覆蓋）。

由於擴展是由環境創建的，因此它們不能接受任何配置參數。您可能希望通過使用工廠函數來解決這個問題，但這是不可能的，因為擴展是通過它們的導入名稱來識別的。配置擴展的正確方法是將配置值存儲在環境中。因為這種方式會讓環境最終充當中央配置存儲，所以屬性可能會發生衝突，這就是為什麼擴展必須確保它們為配置選擇的名稱不會太過通用的原因。例如，prefix 是一個糟糕的名稱，而 fragment_cache_prefix 則是一個好名稱，因為它包含了擴展的名稱（片段緩存）。

參數：

environment (Environment)

identifier

擴展的標識符。這始終是擴展類的真正導入名稱，並且不得更改。

tags

如果擴展實現了自定義標籤，則這是一個擴展正在偵聽的標籤名稱集。

preprocess(source, name, filename=None)

此方法在實際詞法分析之前調用，可用於預處理源代碼。 filename 是可選的。返回值必須是預處理後的源代碼。

參數：

  • source (str)

  • name (str | None)

  • filename (str | None)

返回類型：

str

filter_stream(stream)

它會傳遞一個 TokenStream，可用於過濾返回的標記。此方法必須返回一個 Tokens 的可迭代對象，但它不必返回一個 TokenStream。

參數：

stream (TokenStream)

返回類型：

TokenStream | Iterable[Token]

parse(parser)

如果任何 tags 匹配，則會調用此方法，並將解析器作為第一個參數。解析器流指向的標記是匹配的名稱標記。此方法必須返回一個或多個節點的列表。

參數：

parser (Parser)

返回類型：

Node | List[Node]

attr(name, lineno=None)

返回當前擴展的屬性節點。這對於將擴展上的常量傳遞給生成的模板代碼很有用。

self.attr('_my_attribute', lineno=lineno)
參數：

  • name (str)

  • lineno (int | None)

返回類型：

ExtensionAttribute

call_method(name, args=None, kwargs=None, dyn_args=None, dyn_kwargs=None, lineno=None)

調用擴展的方法。這是 attr() + jinja2.nodes.Call 的捷徑。

參數：
返回類型：

Call

解析器

傳遞給 Extension.parse() 的解析器提供了解析不同類型表達式的方法。擴展可以使用以下方法

class jinja2.parser.Parser(environment, source, name=None, filename=None, state=None)

這是 Jinja 使用的核心解析類別。它會被傳遞給擴充功能，並且可以用於解析表達式或語句。

參數：
filename

解析器處理的模板檔名。這不是模板的載入名稱。有關載入名稱，請參閱 name。對於未從檔案系統載入的模板，此值為 None。

name

模板的載入名稱。

stream

目前的 TokenStream

fail(msg, lineno=None, exc=TemplateSyntaxError)

方便的方法，它會引發 exc 並傳遞訊息、傳遞的行號或最後一行號，以及目前的 Name 和 Filename。

參數：
返回類型：

te.NoReturn

free_identifier(lineno=None)

以 InternalName 的形式傳回新的自由識別符號。

參數：

lineno (int | None)

返回類型：

InternalName

parse_statements(end_tokens, drop_needle=False)

將多個語句解析成一個列表，直到到達其中一個結束標記為止。這用於解析語句主體，因為它也會在適當的情況下解析模板資料。解析器會先檢查目前的標記是否為冒號，如果是，則跳過它。然後它會檢查區塊結束，並解析直到到達其中一個 end_tokens 為止。預設情況下，呼叫結束時串流中的作用中標記是匹配的結束標記。如果不需要這樣，可以將 drop_needle 設為 True，並移除結束標記。

參數：
返回類型：

List[Node]

parse_assign_target(with_tuple=True, name_only=False, extra_end_rules=None, with_namespace=False)

解析指定目標。由於 Jinja 允許指定給 Tuple，因此此函數可以解析所有允許的指定目標。預設情況下會解析指定給 Tuple 的值，但是可以透過將 with_tuple 設為 False 來停用此功能。如果只需要指定給 Name 的值，可以將 name_only 設為 True。 extra_end_rules 參數會被轉發給 Tuple 解析函數。如果啟用了 with_namespace，則可以解析命名空間指定。

參數：
返回類型：

NSRef | Name | Tuple

parse_expression(with_condexpr=True)

解析表達式。預設情況下會解析所有表達式，如果將可選的 with_condexpr 參數設為 False，則不會解析條件表達式。

參數：

with_condexpr (bool)

返回類型：

Expr

parse_tuple(simplified=False, with_condexpr=True, extra_end_rules=None, explicit_parentheses=False)

與 parse_expression 的運作方式類似，但如果多個表達式以逗號分隔，則會建立一個 Tuple 節點。如果沒有找到逗號，此方法也可以返回一個正規表達式而不是一個 tuple。

預設的解析模式是一個完整的 tuple。如果 simplified 為 True，則只會解析名稱和字面值。 no_condexpr 參數會被轉發到 parse_expression()。

由於 tuple 不需要分隔符號，並且可能以一個虛假的逗號結尾，因此需要一個額外的提示來標記 tuple 的結束。例如，for 迴圈支援 for 和 in 之間的 tuple。在這種情況下， extra_end_rules 會被設定為 ['name:in']。

如果解析是由括號中的表達式觸發的，則 explicit_parentheses 為 true。這用於判斷一個空的 tuple 是否是一個有效的表達式。

參數：
返回類型：

Tuple | Expr

類別 jinja2.lexer.TokenStream(generator, name, filename)

一個 token 串流是一個可迭代的物件，它會產生 Token。然而，解析器不會迭代它，而是呼叫 next() 來前進一個 token。目前活動的 token 會被儲存為 current。

參數：
current

目前的 Token。

屬性 eos: 布林值

我們是否在串流的結尾？

push(token)

將一個 token 推回串流。

參數：

token (Token)

返回類型：

無

look()

查看下一個 token。

返回類型：

Token

skip(n=1)

前進 n 個 token。

參數：

n (整數)

返回類型：

無

next_if(expr)

執行 token 測試，如果匹配則返回 token。否則，返回值為 None。

參數：

expr (字串)

返回類型：

Token | None

skip_if(expr)

類似於 next_if()，但只返回 True 或 False。

參數：

expr (字串)

返回類型：

布林值

__next__()

前進一個 token 並返回舊的 token。

使用內建的 next() 而不是直接呼叫這個方法。

返回類型：

Token

expect(expr)

期望一個給定的 token 類型並返回它。這接受與 jinja2.lexer.Token.test() 相同的參數。

參數：

expr (字串)

返回類型：

Token

類別 jinja2.lexer.Token(lineno, type, value)
參數：
lineno

token 的行號

type

權杖的類型。此字串是內部化的，因此您可以使用 is 運算符將其與任意字串進行比較。

value

權杖的值。

test(expr)

根據權杖表達式測試權杖。這可以是權杖類型或 'token_type:token_value'。這只能針對字串值和類型進行測試。

參數：

expr (字串)

返回類型：

布林值

test_any(*iterable)

針對多個權杖表達式進行測試。

參數：

iterable (str)

返回類型：

布林值

lexer 模組中還有一個實用函數，可以計算字串中的換行符號數量

jinja2.lexer.count_newlines(value)

計算字串中換行符號的數量。這對於過濾串流的擴充功能很有用。

參數：

value (字串)

返回類型：

int

AST

AST（抽象語法樹）用於表示解析後的模板。它由編譯器轉換為可執行 Python 程式碼物件的節點構建而成。提供自定義語句的擴充功能可以返回節點以執行自定義 Python 程式碼。

以下列表描述了目前可用的所有節點。AST 可能會在 Jinja 版本之間發生變化，但會保持向後相容。

有關更多資訊，請查看 jinja2.Environment.parse() 的 repr。

class jinja2.nodes.Node

所有 Jinja 節點的基類。有許多不同類型的節點可用。主要有四種類型

所有節點都有欄位和屬性。欄位可以是其他節點、列表或任意值。欄位作為常規位置參數傳遞給建構函數，屬性作為關鍵字參數傳遞。每個節點都有兩個屬性：lineno（節點的行號）和 environment。environment 屬性會在解析過程結束時自動為所有節點設置。

參數：

  • fields (Any)

  • attributes (Any)

iter_fields(exclude=None, only=None)

此方法會迭代所有已定義的欄位，並產生 (key, value) 元組。預設情況下會返回所有欄位，但可以通過提供 only 參數將其限制為某些欄位，或使用 exclude 參數排除某些欄位。兩者都應該是欄位名稱的集合或元組。

參數：
返回類型：

Iterator[Tuple[str, Any]]

iter_child_nodes(exclude=None, only=None)

迭代節點的所有直接子節點。這會迭代所有欄位，並產生它們是節點的值。如果欄位的值是一個列表，則會返回該列表中的所有節點。

參數：
返回類型：

Iterator[Node]

find(node_type)

查找給定類型的第一個節點。如果不存在這樣的節點，則返回值為 None。

參數：

node_type (Type[_NodeBound])

返回類型：

_NodeBound | None

find_all(node_type)

查找給定類型的所有節點。如果類型是元組，則會對任何元組項目執行檢查。

參數：

node_type（Type[_NodeBound] | Tuple[Type[_NodeBound], ...]）

返回類型：

Iterator[_NodeBound]

set_ctx(ctx)

重置節點及其所有子節點的上下文。預設情況下，解析器會生成所有具有「載入」上下文的節點，因為這是最常見的上下文。此方法在解析器中用於將賦值目標和其他節點設置為儲存上下文。

參數：

ctx（str）

返回類型：

節點

set_lineno(lineno, override=False)

設置節點和子節點的行號。

參數：
返回類型：

節點

set_environment(environment)

為所有節點設置環境。

參數：

environment (Environment)

返回類型：

節點

class jinja2.nodes.Expr

所有表達式的基類。

節點類型：

節點

參數：

  • fields (Any)

  • attributes (Any)

as_const(eval_ctx=None)

將表達式的值作為常數返回，如果無法做到，則引發 Impossible。

可以提供一個 EvalContext，如果未提供，則會創建一個預設上下文，要求節點具有附加的環境。

更新日誌

在版本 2.4 中更改： 添加了 eval_ctx 參數。

參數：

eval_ctx（EvalContext | None）

返回類型：

任何

can_assign()

檢查是否可以將某些內容賦值給此節點。

返回類型：

布林值

class jinja2.nodes._FilterTestCommon(node, name, args, kwargs, dyn_args, dyn_kwargs)
節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Filter(node, name, args, kwargs, dyn_args, dyn_kwargs)

將篩選器應用於表達式。name 是篩選器的名稱，其他欄位與 Call 相同。

如果 node 是 None，則篩選器正在篩選器區塊中使用，並應用於區塊的內容。

節點類型：

_FilterTestCommon

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Test(node, name, args, kwargs, dyn_args, dyn_kwargs)

將測試應用於表達式。name 是測試的名稱，其他欄位與 Call 相同。

更新日誌

在版本 3.0 中更改： as_const 共用篩選器和測試的相同邏輯。測試會檢查 volatile、async 和 @pass_context 等裝飾器。

節點類型：

_FilterTestCommon

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.BinExpr(left, right)

所有二元表達式的基類。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Add(left, right)

將左側節點加到右側節點。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.And(left, right)

短路 AND。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Div(left, right)

將左側節點除以右側節點。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.FloorDiv(left, right)

將左節點除以右節點，並透過截斷將結果轉換為整數。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Mod(left, right)

左節點模除右節點。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Mul(left, right)

將左節點與右節點相乘。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Or(left, right)

短路或運算。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Pow(left, right)

左節點的右節點次方。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Sub(left, right)

從左節點減去右節點。

節點類型：

BinExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Call(node, args, kwargs, dyn_args, dyn_kwargs)

呼叫一個表達式。 args 是一個參數列表，kwargs 是一個關鍵字參數列表（Keyword 節點列表），而 dyn_args 和 dyn_kwargs 必須是 None 或用作動態位置參數 (*args) 或關鍵字參數 (**kwargs) 的節點。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Compare(expr, ops)

將一個表達式與其他表達式進行比較。 ops 必須是 Operand 的列表。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Concat(nodes)

將提供的表達式列表在轉換為字串後進行串接。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.CondExpr(test, expr1, expr2)

條件表達式（行內 if 表達式）。 ({{ foo if bar else baz }})

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.ContextReference

傳回目前的範本上下文。它可以像 Name 節點一樣使用，使用 'load' 上下文，並將傳回目前的 Context 物件。

以下是一個將目前範本名稱指派給名為 foo 的變數的範例

Assign(Name('foo', ctx='store'),
       Getattr(ContextReference(), 'name'))

這基本上等同於在使用高階 API 時使用 pass_context() 裝飾器，這會導致上下文參考作為第一個參數傳遞給函數。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.DerivedContextReference

傳回目前的範本上下文，包括區域變數。行為與 ContextReference 完全相同，但包含區域變數，例如來自 for 迴圈的變數。

更新日誌

新增於 2.11 版。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.EnvironmentAttribute(name)

從環境物件載入屬性。這對於想要呼叫儲存在環境中的回呼函數的擴充功能很有用。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.ExtensionAttribute(identifier, name)

傳回繫結到環境的擴充功能屬性。識別碼是 Extension 的識別碼。

這個節點通常是透過呼叫擴充功能上的 attr() 方法來建構的。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Getattr(node, attr, ctx)

從僅限 ASCII 字節字串的表達式中獲取屬性或項目，並優先選擇屬性。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Getitem(node, arg, ctx)

從表達式中獲取屬性或項目，並優先選擇項目。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.ImportedName(importname)

如果使用導入名稱創建，則在節點訪問時返回導入名稱。例如，ImportedName('cgi.escape') 會在評估時從 cgi 模組返回 escape 函數。導入會被編譯器優化，因此無需將它們分配給局部變數。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.InternalName(name)

編譯器中的內部名稱。您無法自行創建這些節點，但解析器提供了一個 free_identifier() 方法，可以為您創建一個新的識別碼。此識別碼無法從模板中獲取，並且編譯器不會對其進行特殊處理。

節點類型：

Expr

類別 jinja2.nodes.Literal

字面量的基類。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Const(value)

所有常數值。解析器會針對簡單的常數（例如 42 或 "foo"）返回此節點，但它也可以用於存儲更複雜的值，例如列表。僅限具有安全表示形式的常數（滿足 eval(repr(x)) == x 的物件）。

節點類型：

字面量

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Dict(items)

任何字典字面量，例如 {1: 2, 3: 4}。項目必須是 Pair 節點的列表。

節點類型：

字面量

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.List(items)

任何列表字面量，例如 [1, 2, 3]

節點類型：

字面量

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.TemplateData(data)

常數模板字串。

節點類型：

字面量

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Tuple(items, ctx)

用於迴圈拆包和一些其他用途，例如子腳本的多個參數。與 Name 類似，ctx 指定元組是用於加載名稱還是存儲名稱。

節點類型：

字面量

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.MarkSafe(expr)

將包裝的表達式標記為安全（將其包裝為 Markup）。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.MarkSafeIfAutoescape(expr)

將包裝的表達式標記為安全（將其包裝為 Markup），但僅在自動轉義處於活動狀態時才如此。

更新日誌

新增於 2.5 版。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Name(name, ctx)

查找名稱或將值存儲在名稱中。節點的 ctx 可以是以下值之一

  • store：將值存儲在名稱中

  • load：加載該名稱

  • param：類似於 store，但如果名稱被定義為函數參數。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.NSRef(name, attr)

命名空間值賦值的參考

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Slice(start, stop, step)

表示切片物件。這只能用作 Subscript 的參數。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.UnaryExpr(node)

所有一元表達式的基類。

節點類型：

Expr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Neg(node)

使表達式變為負數。

節點類型：

UnaryExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Not(node)

否定表達式。

節點類型：

UnaryExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Pos(node)

使表達式變為正數（對大多數表達式而言無效）

節點類型：

UnaryExpr

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Helper

僅存在於特定上下文中的節點。

節點類型：

節點

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Keyword(key, value)

關鍵字參數的鍵值對，其中鍵是字串。

節點類型：

Helper

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Operand(op, expr)

保存運算符和表達式。

節點類型：

Helper

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Pair(key, value)

字典的鍵值對。

節點類型：

Helper

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Stmt

所有語句的基底節點。

節點類型：

節點

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Assign(target, node)

將表達式賦值給目標。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.AssignBlock(target, filter, body)

將區塊賦值給目標。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Block(name, body, scoped, required)

表示區塊的節點。

更新日誌

在 3.0.0 版中變更: 新增了 required 欄位。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Break

跳出迴圈。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.CallBlock(call, args, defaults, body)

就像沒有名稱但有呼叫的巨集。此節點保存的 call 會以未命名的巨集作為 caller 參數被呼叫。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Continue

繼續迴圈。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.EvalContextModifier(options)

修改評估上下文。對於每個應修改的選項，必須將 Keyword 添加到 options 列表中。

更改 autoescape 設定的範例

EvalContextModifier(options=[Keyword('autoescape', Const(True))])
節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.ScopedEvalContextModifier(options, body)

修改 eval 上下文並在稍後恢復它。其工作原理與 EvalContextModifier 完全相同，但只會修改 body 中節點的 EvalContext。

節點類型：

EvalContextModifier

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.ExprStmt(node)

一個評估表達式並捨棄結果的語句。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Extends(template)

表示一個 extends 語句。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.FilterBlock(body, filter)

過濾器區塊的節點。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.For(target, iter, body, else_, test, recursive)

for 迴圈。 target 是迭代的目標（通常是 Name 或 Tuple）， iter 是可迭代對象。 body 是用作迴圈主體的節點列表，而 else_ 是 else 區塊的節點列表。如果沒有 else 節點，則它必須是一個空列表。

對於已過濾的節點，可以將表達式儲存為 test，否則為 None。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.FromImport(template, names, with_context)

表示 from import 標籤的節點。重要的是不要將不安全的名稱傳遞給 name 屬性。編譯器會將屬性查找直接轉換為 getattr 呼叫，並且 *不會* 使用介面的下標回調。由於匯出的變數不能以雙底線開頭（解析器會斷言），因此對於常規 Jinja 程式碼來說這不是問題，但如果在擴充功能中使用此節點，則必須格外小心。

如果需要別名，則名稱列表可以包含元組。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.If(test, body, elif_, else_)

如果 test 為真，則呈現 body，否則呈現 else_。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Import(template, target, with_context)

表示 import 標籤的節點。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Include(template, with_context, ignore_missing)

表示 include 標籤的節點。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Macro(name, args, defaults, body)

巨集定義。 name 是巨集的名稱， args 是參數列表， defaults 是預設值列表（如果有）。 body 是巨集主體的節點列表。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Output(nodes)

一個包含多個表達式的節點，這些表達式會被印出。這用於 print 語句和常規模板資料。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.OverlayScope(context, body)

擴充功能的覆蓋範圍。這是一個很大程度上未經最佳化的範圍，但是可以用於將完全任意的變數從字典或類似字典的物件引入到子範圍中。 context 欄位必須評估為字典物件。

使用範例

OverlayScope(context=self.call_method('get_context'),
             body=[...])
更新日誌

新增於 2.10 版。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

類別 jinja2.nodes.Scope(body)

一個人造範圍。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.With(targets, values, body)

with 語句的特定節點。在舊版本的 Jinja 中，with 語句是在 Scope 節點的基礎上實現的。

更新日誌

新增於版本 2.9.3。

節點類型：

Stmt

參數：

  • fields (Any)

  • attributes (Any)

class jinja2.nodes.Template(body)

表示模板的節點。這必須是傳遞給編譯器的最外層節點。

節點類型：

節點

參數：

  • fields (Any)

  • attributes (Any)

exception jinja2.nodes.Impossible

如果節點無法執行請求的操作，則會引發此異常。