API?

本文描述的是Jinja的API,而不是模板語言(請參見 模板設計器文檔 ). 對于那些實現應用程序的模板接口的人,而不是那些創建Jinja模板的人來說,這將是最有用的參考。

基礎?

Jinja使用一個名為template的中心對象 Environment . 此類的實例用于存儲配置和全局對象,并用于從文件系統或其他位置加載模板。即使使用的構造函數從字符串創建模板, Template 類,將自動為您創建一個環境,盡管是共享的環境。

大多數應用程序將創建一個 Environment 應用程序初始化時的對象,并使用該對象加載模板。但是,在某些情況下,如果使用不同的配置,那么并排擁有多個環境是很有用的。

配置Jinja以加載應用程序模板的最簡單方法是使用 PackageLoader .

from jinja2 import Environment, PackageLoader, select_autoescape
env = Environment(
    loader=PackageLoader("yourapp"),
    autoescape=select_autoescape()
)

這將創建一個帶有在中查找模板的加載程序的模板環境 templates 文件夾 yourapp Python包(或旁邊的 yourapp.py Python模塊)。它還支持HTML文件的自動轉義。這個裝載機只需要這個 yourapp 是可導入的,它為您計算出文件夾的絕對路徑。

可以使用不同的加載程序以其他方式或從其他位置加載模板。它們列在 Loaders 以下章節。如果您想從一個對您的項目更專業的源加載模板,您也可以自己編寫。

若要從此環境加載模板,請調用 get_template() 方法,它返回加載的 Template .

template = env.get_template("mytemplate.html")

要用一些變量呈現它,請調用 render() 方法。

print(template.render(the="variables", go="here"))

使用模板加載程序而不是將字符串傳遞給 TemplateEnvironment.from_string() 具有多種優勢。除了更容易使用外,它還支持模板繼承。

自動轉義的注意事項

在Jinja的未來版本中,出于安全原因,我們可能會默認啟用自動轉義。因此,我們鼓勵您現在顯式地配置自動轉義,而不是依賴于默認值。

高級API?

高級API是您將在應用程序中用于加載和呈現Jinja模板的API。這個 低層API 另一方面是有用的,如果你想更深入地挖掘Jinja或 develop extensions .

class jinja2.Environment([options])?

Jinja的核心組成部分是 Environment . 它包含重要的共享變量,如配置、過濾器、測試、全局變量和其他變量。如果這個類的實例不是共享的,并且到目前為止還沒有加載模板,那么可以對它們進行修改。加載第一個模板后對環境的修改將導致驚人的效果和未定義的行為。

以下是可能的初始化參數:

block_start_string

標記塊開頭的字符串。默認為 '{{%' .

block_end_string

標記塊末端的字符串。默認為 '%}}' .

variable_start_string

標記打印語句開頭的字符串。默認為 '{{{{' .

variable_end_string

標記打印語句結束的字符串。默認為 '}}}}' .

comment_start_string

標記注釋開頭的字符串。默認為 '{{#' .

comment_end_string

標記注釋結尾的字符串。默認為 '#}}' .

line_statement_prefix

如果給定一個字符串,它將用作基于行的語句的前綴。也見 行語句 .

line_comment_prefix

如果給定和一個字符串,它將用作基于行的注釋的前綴。也見 行語句 .

Changelog

在 2.2 版本加入.

trim_blocks

如果設置為 True 刪除塊后的第一個換行符(block,而不是variable tag?。┠J為 False .

lstrip_blocks

如果設置為 True 行首空格和制表符從行首剝離到塊。默認為 False .

newline_sequence

開始換行的順序。一定是其中之一 '\r' , '\n''\r\n' . 默認值為 '\n' 對于Linux和OS X系統以及Web應用程序來說,這是一個有用的默認值。

keep_trailing_newline

呈現模板時保留尾隨換行符。默認值為 False ,這將導致從模板結尾剝離一條新行(如果存在)。

Changelog

在 2.7 版本加入.

extensions

要使用的Jinja擴展列表。這可以是作為字符串或擴展類導入路徑。有關更多信息,請查看 the extensions documentation .

optimized

是否應啟用優化器?默認是 True .

undefined

Undefined 或其子類,用于表示模板中未定義的值。

finalize

一種可調用文件,可用于在輸出變量表達式之前處理其結果。例如,可以轉換 None 在此處隱式轉換為空字符串。

autoescape

如果設置為 True 默認情況下,啟用XML/HTML自動轉義功能。有關自動轉義的詳細信息,請參閱 Markup . 從Jinja 2.4開始,這也可以是一個可調用的,它傳遞了模板名,必須返回 TrueFalse 根據自動轉義,默認情況下應啟用。

Changelog

在 2.4 版本發生變更: autoescape 現在可以是函數

loader

此環境的模板加載器。

cache_size

緩存的大小。默認情況下,這是 400 這意味著,如果加載的模板超過400個,加載程序將清除最近使用最少的模板。如果緩存大小設置為 0 如果緩存大小為 -1 不會清除緩存。

Changelog

在 2.8 版本發生變更: 緩存大小從低50增加到400。

auto_reload

一些加載程序從模板源可能更改的位置(例如:文件系統或數據庫)加載模板。如果 auto_reload 設置為 True (默認)每次請求模板時,加載程序都會檢查源是否更改,如果更改,則加載程序將重新加載模板。為了獲得更高的性能,可以禁用它。

bytecode_cache

如果設置為字節碼緩存對象,則此對象將為內部Jinja字節碼提供緩存,以便在不更改模板的情況下不必解析模板。

字節碼緩存 更多信息。

enable_async

如果設置為true,則啟用異步模板執行,從而允許使用異步函數和生成器。

shared?

如果模板是通過使用 Template 構造函數自動創建一個環境。這些環境創建為共享環境,這意味著多個模板可能具有相同的匿名環境。對于所有共享環境,此屬性是 True ,否則 False .

sandboxed?

如果環境是沙盒,則此屬性為 True . 對于沙盒模式,請查看 SandboxedEnvironment .

filters?

此環境的篩選器字典。只要沒有加載模板,就可以安全地添加新的篩選器或刪除舊的。有關自定義篩選器,請參見 自定義過濾器 . 對于有效的過濾器名稱,請查看 標識符說明 .

tests?

此環境的測試函數的dict。只要沒有加載模板,就可以安全地修改此dict。有關自定義測試,請參見 自定義測試 . 對于有效的測試名稱,請查看 標識符說明 .

globals?

全局變量的字典。這些變量在模板中始終可用。只要沒有加載模板,就可以安全地修改此dict。有關詳細信息,請參閱 超空間 . 對于有效的對象名稱,請查看 標識符說明 .

policies?

一本字典 政策 . 這些可以重新配置以更改運行時行為或某些模板功能。通常這些都與安全相關。

code_generator_class?

用于代碼生成的類。在大多數情況下,這不應該更改,除非您需要修改模板編譯到的Python代碼。

context_class?

用于模板的上下文。在大多數情況下,這不應該更改,除非您需要修改模板變量如何處理的內部。有關詳細信息,請參閱 Context .

overlay([options])?

創建一個新的覆蓋環境,該環境與當前環境共享除緩存和重寫屬性之外的所有數據。無法刪除覆蓋環境的擴展名。覆蓋的環境會自動獲取它所鏈接環境的所有擴展以及可選的額外擴展。

創建覆蓋應該在初始環境完全設置之后進行。并不是所有的屬性都是真正鏈接的,有些屬性只是復制過來的,所以對原始環境的修改可能不會發光。

在 3.1.2 版本發生變更: 添加了 newline_sequence ,, keep_trailing_newline ,以及 enable_async 要匹配的參數 __init__ 。

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

創建新的 Undefined 對象 name . 這對于某些操作可能返回未定義對象的篩選器或函數很有用。除以下參數外的所有參數 hint 應作為關鍵字參數提供,以提高可讀性。這個 hint 如果提供,則用作異常的錯誤消息,否則將從中生成錯誤消息 objname 自動。例外情況如下: exc 如果使用生成的未定義對象執行了未定義對象不允許的操作,則引發。默認的例外是 UndefinedError . 如果A hint 提供了 name 可以省略。

創建未定義對象的最常見方法是只提供名稱::

return environment.undefined(name='some_name')

這意味著這個名字 some_name 未定義。如果名稱來自對象的屬性,則有必要告訴未定義的對象holder對象以改進錯誤消息:

if not hasattr(obj, 'attr'):
    return environment.undefined(obj=obj, name='attr')

對于更復雜的示例,您可以提供提示。例如 first() 篩選器以這種方式創建未定義的對象::

return environment.undefined('no first item, sequence was empty')

如果它 nameobj 是已知的(例如,因為訪問了屬性),即使自定義 hint 提供。這使未定義的對象有可能增強錯誤消息。

add_extension(extension: Union[str, Type[Extension]]) None?

在創建環境后添加擴展。

Changelog

在 2.5 版本加入.

compile_expression(source: str, undefined_to_none: bool = True) TemplateExpression?

一個方便的助手方法,它返回一個接受關鍵字參數的可調用函數,關鍵字參數作為變量出現在表達式中。如果調用它,則返回表達式的結果。

如果應用程序希望在模板“配置文件”或類似情況中使用與Jinja相同的規則,則此功能非常有用。

示例用法:

>>> env = Environment()
>>> expr = env.compile_expression('foo == 42')
>>> expr(foo=23)
False
>>> expr(foo=42)
True

默認情況下,返回值轉換為 None 如果表達式返回未定義的值。這可以通過設置更改 undefined_to_noneFalse .

>>> env.compile_expression('var')() is None
True
>>> env.compile_expression('var', undefined_to_none=False)()
Undefined
Changelog

在 2.1 版本加入.

compile_templates(target: Union[str, PathLike], extensions: Optional[Collection[str]] = None, filter_func: Optional[Callable[[str], bool]] = None, zip: Optional[str] = 'deflated', log_function: Optional[Callable[[str], None]] = None, ignore_errors: bool = True) None?

查找加載程序可以找到的所有模板,編譯它們并將其存儲在 target . 如果 zipNone 而不是壓縮文件,模板將存儲在一個目錄中。默認情況下,使用放氣zip算法。要切換到存儲的算法, zip 可以設置為 'stored' .

extensionsfilter_func 被傳遞給 list_templates() . 返回的每個模板都將編譯到目標文件夾或zipfile中。

默認情況下,模板編譯錯誤被忽略。如果提供了日志函數,則會記錄錯誤。如果希望模板語法錯誤中止編譯,可以設置 ignore_errorsFalse 您將得到一個語法錯誤的異常。

Changelog

在 2.4 版本加入.

extend(**attributes: Any) None?

如果這些項尚不存在,請將它們添加到環境實例中。這是由 extensions 注冊回調和配置值而不破壞繼承。

from_string(source: Union[str, Template], globals: Optional[MutableMapping[str, Any]] = None, template_class: Optional[Type[Template]] = None) Template?

從源字符串加載模板,而不使用 loader 。

參數
  • source -- 金佳源碼編譯成模板。

  • globals -- 擴展環境 globals 這些額外變量可用于該模板的所有渲染。如果模板已經加載和緩存,則它的全局變量將使用任何新項目進行更新。

  • template_class -- 返回此實例的一個實例 Template 班級。

get_or_select_template(template_name_or_list: Union[str, Template, List[Union[str, Template]]], parent: Optional[str] = None, globals: Optional[MutableMapping[str, Any]] = None) Template?

使用 select_template() 如果給出了模板名稱的可迭代數,或者 get_template() 如果只給出一個名字的話。

Changelog

在 2.3 版本加入.

get_template(name: Union[str, Template], parent: Optional[str] = None, globals: Optional[MutableMapping[str, Any]] = None) Template?

使用按名稱加載模板 loader 并返回一個 Template 。如果模板不存在于 TemplateNotFound 引發異常。

參數
  • name -- 要加載的模板的名稱。從文件系統加載模板時,使用“/”作為路徑分隔符,即使在Windows上也是如此。

  • parent -- 導入此模板的父模板的名稱。 join_path() 可以用來實現名稱轉換。

  • globals -- 擴展環境 globals 這些額外變量可用于該模板的所有渲染。如果模板已經加載和緩存,則它的全局變量將使用任何新項目進行更新。

Changelog

在 3.0 版本發生變更: 如果從高速緩存加載模板, globals 將更新模板的全局值,而不是忽略新值。

在 2.4 版本發生變更: 如果 name 是一種 Template 對象,則原封不動地返回。

join_path(template: str, parent: str) str?

將模板與父模板聯接。默認情況下,所有查找都是相對于加載器根目錄的,因此此方法返回 template 參數不變,但如果路徑應該相對于父模板,則可以使用此函數計算實際模板名稱。

子類可以重寫此方法并在此處實現模板路徑連接。

list_templates(extensions: Optional[Collection[str]] = None, filter_func: Optional[Callable[[str], bool]] = None) List[str]?

返回此環境的模板列表。這要求加載器支持加載器的 list_templates() 方法。

如果模板文件夾中除實際模板外還有其他文件,則可以過濾返回的列表。有兩種方法:要么 extensions 設置為模板的文件擴展名列表,或 filter_func 可以提供,它是一個可調用的,傳遞模板名并應返回 True 如果它最終出現在結果列表中。

如果加載器不支持,a TypeError 提高了。

Changelog

在 2.4 版本加入.

select_template(names: Iterable[Union[str, Template]], parent: Optional[str] = None, globals: Optional[MutableMapping[str, Any]] = None) Template?

喜歡 get_template() ,但嘗試加載多個名稱。如果所有名稱都不能加載到 TemplatesNotFound 引發異常。

參數
  • names -- 要嘗試按順序加載的模板名稱列表。

  • parent -- 導入此模板的父模板的名稱。 join_path() 可以用來實現名稱轉換。

  • globals -- 擴展環境 globals 這些額外變量可用于該模板的所有渲染。如果模板已經加載和緩存,則它的全局變量將使用任何新項目進行更新。

Changelog

在 3.0 版本發生變更: 如果從高速緩存加載模板, globals 將更新模板的全局值,而不是忽略新值。

在 2.11 版本發生變更: 如果 namesUndefined ,一個 UndefinedError 反而被舉起了。如果未找到模板,并且 names 包含 Undefined ,信息更有幫助。

在 2.4 版本發生變更: 如果 names 包含一個 Template 對象,則原封不動地返回。

在 2.3 版本加入.

class jinja2.Template(source: ~typing.Union[str, ~jinja2.nodes.Template], block_start_string: str = '{%', block_end_string: str = '%}', variable_start_string: str = '{{', variable_end_string: str = '}}', comment_start_string: str = '{#', comment_end_string: str = '#}', line_statement_prefix: ~typing.Optional[str] = None, line_comment_prefix: ~typing.Optional[str] = None, trim_blocks: bool = False, lstrip_blocks: bool = False, newline_sequence: te.Literal['\n', '\r\n', '\r'] = '\n', keep_trailing_newline: bool = False, extensions: ~typing.Sequence[~typing.Union[str, ~typing.Type[Extension]]] = (), optimized: bool = True, undefined: ~typing.Type[~jinja2.runtime.Undefined] = <class 'jinja2.runtime.Undefined'>, finalize: ~typing.Optional[~typing.Callable[[...], ~typing.Any]] = None, autoescape: ~typing.Union[bool, ~typing.Callable[[~typing.Optional[str]], bool]] = False, enable_async: bool = False)?

可以呈現的已編譯模板。

使用上的方法 Environment 要創建或加載模板,請執行以下操作。該環境用于配置模板的編譯和行為方式。

也可以直接創建模板對象。通常不建議這樣做。構造函數接受的大部分參數與 Environment 。使用相同的環境參數創建的所有模板共享相同的臨時模板 Environment 實例在幕后。

模板對象應該被認為是不可變的。不支持對對象進行修改。

globals?

帶有該模板全局值的dict。修改此dict是不安全的,因為它可能與其他模板或加載模板的環境共享。

name?

模板的加載名稱。如果從字符串加載模板,則 None .

filename?

文件系統上模板的文件名(如果從中加載)。否則這是 None .

render([context])?

此方法接受與 dict 構造器:dict、dict子類或一些關鍵字參數。如果沒有提供參數,則上下文將為空。這兩個電話的作用相同:

template.render(knights='that say nih')
template.render({'knights': 'that say nih'})

這將以字符串形式返回呈現的模板。

generate([context])?

對于非常大的模板,不要一次呈現整個模板,而是逐個計算每個語句并逐個生成結果,這可能很有用。此方法基本上就是這樣做的,并返回一個生成器,該生成器以字符串的形式生成一個接一個的項目。

它接受與 render() .

stream([context])?

工作原理和 generate() 但返回A TemplateStream .

async render_async([context])?

這項工作類似于 render() 但返回一個協程,在等待時返回整個呈現的模板字符串。這需要啟用異步功能。

示例用法:

await template.render_async(knights='that say nih; asynchronously')
async generate_async([context])?

的異步版本 generate() . 工作原理非常相似,但返回異步迭代器。

make_module(vars: Optional[Dict[str, Any]] = None, shared: bool = False, locals: Optional[Mapping[str, Any]] = None) TemplateModule?

這種方法的工作原理與 module 屬性在沒有參數的情況下調用,但它將在每次調用時評估模板,而不是緩存模板。還可以提供一個dict,然后將其用作上下文。參數與 new_context() 方法。

property module: TemplateModule?

模板作為模塊。這用于模板運行時中的導入,但如果要訪問從python層導出的模板變量,這也很有用:

>>> t = Template('{% macro foo() %}42{% endmacro %}23')
>>> str(t.module)
'23'
>>> t.module.foo() == u'42'
True

如果啟用異步模式,則此屬性不可用。

class jinja2.environment.TemplateStream?

模板流的工作原理與普通Python生成器非常相似,但它可以緩沖多個項以減少總迭代次數。默認情況下,輸出是無緩沖的,這意味著對于模板中的每條未緩沖的指令,都會產生一個字符串。

如果在緩沖區大小為5的情況下啟用緩沖,則五個項目將合并到一個新字符串中。如果您通過每次迭代后刷新的WSGI將大模板流式傳輸到客戶端,這主要是有用的。

disable_buffering() None?

禁用輸出緩沖。

dump(fp: Union[str, IO], encoding: Optional[str] = None, errors: Optional[str] = 'strict') None?

將整個流轉儲到文件或類似文件的對象中。根據默認字符串寫入,如果要在寫入之前進行編碼,請指定 encoding 。

示例用法:

Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
enable_buffering(size: int = 5) None?

啟用緩沖。緩沖區 size 在生產之前。

自動逃逸?

Changelog

在 2.4 版本發生變更.

Jinja現在提供了自動轉義支持。從jinja2.9開始,autoescape擴展被刪除并內置。不過,自動轉義在默認情況下還沒有啟用,不過這很可能在將來發生變化。建議為自動轉義配置一個合理的默認值。這使得可以在每個模板的基礎上啟用和禁用自動轉義(例如,HTML與文本)。

jinja2.select_autoescape(enabled_extensions: Collection[str] = ('html', 'htm', 'xml'), disabled_extensions: Collection[str] = (), default_for_string: bool = True, default: bool = False) Callable[[Optional[str]], bool]?

根據模板的文件名智能地設置自動轉義的初始值。如果不想自己編寫自定義函數,建議使用此方法配置自動轉義。

如果要為從字符串創建的所有模板或使用 .html.xml 擴展:

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(
    enabled_extensions=('html', 'xml'),
    default_for_string=True,
))

除非模板以 .txt ::

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(
    disabled_extensions=('txt',),
    default_for_string=True,
    default=True,
))

這個 enabled_extensions 是應為其啟用自動轉義的所有擴展中的一個不可重復的。同樣地 disabled_extensions 是應為其禁用的所有模板的列表。如果從字符串加載模板,則默認值為 default_for_string 使用。如果沒有匹配的內容,則自動轉義的初始值將設置為 default .

出于安全原因,此函數不區分大小寫。

Changelog

在 2.9 版本加入.

這里是一個建議的設置,它為以 '.html' , '.htm''.xml' 默認情況下,對所有其他擴展都禁用它。你可以使用 select_autoescape() 功能:

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(['html', 'htm', 'xml']),
                  loader=PackageLoader('mypackage'))

這個 select_autoescape() 函數返回一個大致工作方式如下的函數:

def autoescape(template_name):
    if template_name is None:
        return False
    if template_name.endswith(('.html', '.htm', '.xml'))

在實現猜測自動轉義函數時,請確保您還接受 None 作為有效模板名。這將在從字符串生成模板時傳遞。您應該始終將自動轉義配置為將來可能更改的默認值。

在模板內,可以使用 autoescape 塊(見) 自動轉義重寫

標識符說明?

Jinja使用Python命名規則。有效標識符可以是Python接受的任何字符組合。

在單獨的名稱空間中查找過濾器和測試,并稍微修改了標識符語法。過濾器和測試可能包含點,用于按主題對過濾器和測試進行分組。例如,在filter dict中添加一個函數并調用它是完全有效的 to.str . 篩選器和測試標識符的正則表達式是 [a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)* '.

未定義類型?

這些類可以用作未定義的類型。這個 Environment 構造函數接受 undefined 參數,可以是這些類之一,也可以是 Undefined . 每當模板引擎無法查找名稱或訪問屬性時,就會創建并返回其中一個對象。然后允許對未定義的值執行某些操作,其他操作失敗。

最接近常規的python行為是 StrictUndefined 如果它是未定義的對象,則不允許測試之外的所有操作。

class jinja2.Undefined?

默認的未定義類型。這個未定義的類型可以被打印和迭代,但其他每個訪問都將引發 UndefinedError

>>> foo = Undefined(name='foo')
>>> str(foo)
''
>>> not foo
True
>>> foo + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
_undefined_hint?

要么 None 或包含未定義對象的錯誤消息的字符串。

_undefined_obj?

要么 None 或導致創建未定義對象的所有者對象(例如,因為屬性不存在)。

_undefined_name?

未定義的變量/屬性的名稱或 None 如果不存在此類信息。

_undefined_exception?

未定義對象要引發的異常。這通常是 UndefinedErrorSecurityError .

_fail_with_undefined_error(\*args, \**kwargs)?

當用任何參數調用時,此方法引發 _undefined_exception 從存儲在未定義對象上的未定義提示生成錯誤消息。

class jinja2.ChainableUndefined?

一個未定義的可鏈接的,其中 __getattr____getitem__ 回歸自己而不是提高 UndefinedError .

>>> foo = ChainableUndefined(name='foo')
>>> str(foo.bar['baz'])
''
>>> foo.bar['baz'] + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
Changelog

在 2.11.0 版本加入.

class jinja2.DebugUndefined?

打印時返回調試信息的未定義。

>>> foo = DebugUndefined(name='foo')
>>> str(foo)
'{{ foo }}'
>>> not foo
True
>>> foo + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
class jinja2.StrictUndefined?

一種在打印、迭代、布爾測試和各種比較中都會出現的未定義。換句話說:除了使用 defined 測試。

>>> foo = StrictUndefined(name='foo')
>>> str(foo)
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
>>> not foo
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
>>> foo + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined

還有一個工廠函數可以修飾未定義的對象以實現登錄失?。?/p>

jinja2.make_logging_undefined(logger: ~typing.Optional[logging.Logger] = None, base: ~typing.Type[~jinja2.runtime.Undefined] = <class 'jinja2.runtime.Undefined'>) Type[Undefined]?

給定logger對象,這將返回一個新的未定義類,該類將記錄某些失敗。它將記錄迭代和打印。如果沒有給定記錄器,則創建默認記錄器。

例子::

logger = logging.getLogger(__name__)
LoggingUndefined = make_logging_undefined(
    logger=logger,
    base=Undefined
)
Changelog

在 2.8 版本加入.

參數
  • logger -- 要使用的記錄器。如果未提供,將創建默認記錄器。

  • base -- 要添加日志功能的基類。默認為 Undefined .

未定義的對象是通過調用 undefined .

實施

Undefined 重寫由 __underscore__ 方法。例如默認值 Undefined 類實現 __str__ 返回一個空字符串,而 __int__ 其他人則例外地失敗了。通過返回 0 你可以實現你自己的子類。

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

    def __float__(self):
        return 0.0

若要禁止方法,請重寫它并引發 _undefined_exception . 因為這是非常常見的幫助方法 _fail_with_undefined_error() 這會產生錯誤,并提供正確的信息。這是一個像普通班一樣工作的班級 Undefined 但迭代失?。?/p>

class NonIterableUndefined(Undefined):
    def __iter__(self):
        self._fail_with_undefined_error()

語境?

class jinja2.runtime.Context?

模板上下文保存模板的變量。它存儲傳遞給模板的值以及模板導出的名稱。創建實例既不受支持也不有用,因為它是在模板評估的各個階段自動創建的,不應該手工創建。

The context is immutable. Modifications on parent must not happen and modifications on vars are allowed from generated template code only. Template filters and global functions marked as pass_context() get the active context passed as first argument and are allowed to access the context read-only.

模板上下文支持只讀dict操作 (get, keys, values, items, iterkeys, itervalues, iteritems, _ _getitem__, __contains__ )另外還有一個 resolve() 方法不會失敗 KeyError 但是返回 Undefined 缺少變量的對象。

parent?

模板查找的只讀全局變量的dict。這些要么來自另一個 Context ,從 Environment.globalsTemplate.globals 或者指向通過將全局變量與傳遞給呈現函數的變量組合而創建的dict。不得更改。

vars?

模板局部變量。此列表包含來自 parent 范圍以及本地修改和從模板導出的變量。模板將在模板評估期間修改此dict,但不允許篩選器和上下文函數修改它。

environment?

加載模板的環境。

exported_vars?

此集合包含模板導出的所有名稱。名稱的值位于 vars dict.為了得到導出變量的dict副本, get_exported() 可以使用。

name?

擁有此上下文的模板的加載名稱。

blocks?

模板中塊的當前映射的dict。此dict中的鍵是塊的名稱,值是已注冊的塊列表。每個列表中的最后一項是當前活動塊(繼承鏈中最新的)。

eval_ctx?

評估背景 .

call(callable, \*args, \**kwargs)?

使用提供的參數和關鍵字參數調用Callable,但如果Callable具有 pass_context()pass_environment() 。

get_all() Dict[str, Any]?

以dict的形式返回完整的上下文,包括導出的變量。出于優化原因,這可能不會返回實際副本,因此請小心使用它。

get_exported() Dict[str, Any]?

使用導出的變量獲取新的dict。

resolve(key: str) Union[Any, Undefined]?

按名稱查找變量,或返回 Undefined 如果找不到密鑰,則返回。

如果需要添加自定義行為,請重寫 resolve_or_missing() ,而不是這種方法。各種查找函數都使用該方法,而不是此方法。

參數

key -- 要查找的變量名稱。

實施

上下文是不可變的,原因與Python的幀局部變量在函數內部是不可變的一樣。Jinja和Python都沒有使用context/frame局部變量作為變量的數據存儲,而只是作為主要數據源。

當模板訪問模板未定義的變量時,Jinja在上下文中查找該變量,然后將該變量視為在模板中定義的變量。

加載器?

加載程序負責從文件系統等資源加載模板。環境將把編譯后的模塊保存在內存中,就像Python一樣 sys.modules . 不像 sys.modules 但是,默認情況下,此緩存的大小受到限制,模板將自動重新加載。所有加載器都是 BaseLoader . 如果您想創建自己的加載器,子類 BaseLoader 超馳 get_source .

class jinja2.BaseLoader?

get_source 實現自定義加載機制。環境提供了 get_template 調用加載程序的 load 方法獲取 Template 對象。

對于在文件系統上查找模板的加載器,一個非?;镜氖纠缦滤荆?/p>

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 open(path) as f:
            source = f.read()
        return source, path, lambda: mtime == getmtime(path)
get_source(environment: Environment, template: str) Tuple[str, Optional[str], Optional[Callable[[], bool]]]?

(source, filename, uptodate) 或提高 TemplateNotFound 找不到模板時出錯。

返回的元組的源部分必須是字符串形式的模板的源。如果文件系統是從那里加載的,則文件名應該是文件系統上的文件的名稱,否則 None 。如果未使用加載器擴展名,則Python將使用該文件名進行回溯。

元組中的最后一項是 uptodate 功能。如果啟用了自動重新加載,則始終調用它來檢查模板是否更改。沒有傳遞參數,因此函數必須將舊狀態存儲在某個位置(例如在閉包中)。如果它回來 False 將重新加載模板。

load(environment: Environment, name: str, globals: Optional[MutableMapping[str, Any]] = None) Template?

加載模板。此方法在緩存中查找模板或通過調用 get_source() . 子類不應將此方法重寫為處理其他加載器集合的加載器(例如 PrefixLoaderChoiceLoader )不會調用此方法,但 get_source 直接。

以下是Jinja提供的內置裝載機列表:

class jinja2.FileSystemLoader(searchpath: Union[str, PathLike, Sequence[Union[str, PathLike]]], encoding: str = 'utf-8', followlinks: bool = False)?

從文件系統中的目錄加載模板。

路徑可以是相對路徑,也可以是絕對路徑。相對路徑相對于當前工作目錄。

loader = FileSystemLoader("templates")

可以給出路徑列表。將按順序搜索目錄,并在第一個匹配的模板處停止。

loader = FileSystemLoader(["/override/templates", "/default/templates"])
參數
  • searchpath -- 指向包含模板的目錄的路徑或路徑列表。

  • encoding -- 使用此編碼從模板文件中讀取文本。

  • followlinks -- 跟隨路徑中的符號鏈接。

Changelog

在 2.8 版本發生變更: 添加了 followlinks 參數。

class jinja2.PackageLoader(package_name: str, package_path: str = 'templates', encoding: str = 'utf-8')?

從Python包中的目錄加載模板。

參數
  • package_name -- 包含模板目錄的包的導入名稱。

  • package_path -- 包含模板的導入包中的目錄。

  • encoding -- 模板文件的編碼。

下面的示例在 pages 目錄中的 project.ui 包裹。

loader = PackageLoader("project.ui", "pages")

僅支持作為目錄(標準pip行為)或zip/egg文件(不太常見)安裝的軟件包。用于內省包中數據的Python API太有限,無法支持此加載器所需的其他安裝方法。

對以下項目的支持有限 PEP 420 命名空間包。假定模板目錄僅位于一個命名空間貢獻器中。不支持對命名空間有貢獻的ZIP文件。

Changelog

在 3.0 版本發生變更: 不再使用 setuptools 作為一種依賴。

在 3.0 版本發生變更: 有限的PEP 420命名空間包支持。

class jinja2.DictLoader(mapping: Mapping[str, str])?

從將模板名稱映射到模板源的Python字典加載模板。此加載器對于單元測試非常有用:

>>> loader = DictLoader({'index.html': 'source here'})

因為自動重新加載很少有用,所以在默認情況下禁用。

class jinja2.FunctionLoader(load_func: Callable[[str], Optional[Union[str, Tuple[str, Optional[str], Optional[Callable[[], bool]]]]]])?

向其傳遞執行加載的函數的加載器。該函數接收模板的名稱,并且必須返回包含模板源的字符串或形式的元組 (source, filename, uptodatefunc)None 如果模板不存在。

>>> def load_template(name):
...     if name == 'index.html':
...         return '...'
...
>>> loader = FunctionLoader(load_template)

這個 uptodatefunc 是一個函數,如果啟用了autoreload并且必須返回 True 如果模板仍然是最新的。有關更多詳細信息,請查看 BaseLoader.get_source() 返回值相同。

class jinja2.PrefixLoader(mapping: Mapping[str, BaseLoader], delimiter: str = '/')?

一種加載器,它傳遞加載器的一個指令,其中每個加載器都綁定到一個前綴上。默認情況下,前綴與模板之間用斜線分隔,可以通過設置 delimiter 其他事情的論據:

loader = PrefixLoader({
    'app1':     PackageLoader('mypackage.app1'),
    'app2':     PackageLoader('mypackage.app2')
})

通過加載 'app1/index.html' 通過加載,將加載來自APP1包的文件 'app2/index.html' 第二個文件。

class jinja2.ChoiceLoader(loaders: Sequence[BaseLoader])?

這個加載器的工作原理是 PrefixLoader 只是沒有指定前綴。如果一個加載程序找不到模板,則嘗試下一個。

>>> loader = ChoiceLoader([
...     FileSystemLoader('/path/to/user/templates'),
...     FileSystemLoader('/path/to/system/templates')
... ])

如果您希望允許用戶覆蓋來自不同位置的內置模板,這將非常有用。

class jinja2.ModuleLoader(path: Union[str, PathLike, Sequence[Union[str, PathLike]]])?

此加載程序從預編譯的模板加載模板。

示例用法:

>>> loader = ChoiceLoader([
...     ModuleLoader('/path/to/compiled/templates'),
...     FileSystemLoader('/path/to/templates')
... ])

模板可以預編譯為 Environment.compile_templates() .

字節碼緩存?

Jinja2.1及更高版本支持外部字節碼緩存。字節碼緩存可以將生成的字節碼存儲在文件系統或其他位置,以避免在首次使用時解析模板。

如果有一個Web應用程序在第一次請求時被初始化,并且Jinja一次編譯許多模板,這會減慢應用程序的速度,那么這一點尤其有用。

要使用字節碼緩存,請將其實例化并傳遞給 Environment .

class jinja2.BytecodeCache?

要實現自己的字節碼緩存,必須將此類子類化并重寫 load_bytecode()dump_bytecode() . 這兩種方法都通過了 Bucket .

在文件系統中保存字節碼的非?;镜淖止澊a緩存:

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, 'rb') as f:
                bucket.load_bytecode(f)

    def dump_bytecode(self, bucket):
        filename = path.join(self.directory, bucket.key)
        with open(filename, 'wb') as f:
            bucket.write_bytecode(f)

jinteja是一個更高級的基于字節緩存的文件系統版本。

clear() None?

清除緩存。Jinja不使用此方法,但應實現該方法以允許應用程序清除特定環境使用的字節碼緩存。

dump_bytecode(bucket: Bucket) None?

子類必須重寫此方法才能將字節碼從存儲桶寫回緩存。如果它不能做到這一點,它就不能默默地失敗,而是引發一個異常。

load_bytecode(bucket: Bucket) None?

子類必須重寫此方法才能將字節碼加載到bucket中。如果他們在緩存中找不到bucket的代碼,那么它就不能做任何事情。

class jinja2.bccache.Bucket(environment: Environment, key: str, checksum: str)?

存儲桶用于存儲一個模板的字節碼。它由字節碼緩存創建和初始化,并傳遞給加載函數。

Buckets從分配的緩存中獲取內部校驗和,并使用該校驗和自動拒絕過期的緩存材料。單獨的字節碼緩存子類不必關心緩存的無效性。

environment?

這個 Environment 創造了這個桶。

key?

此bucket的唯一緩存密鑰

code?

如果加載了字節碼,則返回字節碼,否則 None .

bytecode_from_string(string: bytes) None?

從字節加載字節碼。

bytecode_to_string() bytes?

以字節形式返回字節碼。

load_bytecode(f: BinaryIO) None?

從文件或類似文件的對象加載字節碼。

reset() None?

重置存儲桶(卸載字節碼)。

write_bytecode(f: IO[bytes]) None?

將字節碼轉儲到傳遞的文件或類似文件的對象中。

內置字節碼緩存:

class jinja2.FileSystemBytecodeCache(directory: Optional[str] = None, pattern: str = '__jinja2_%s.cache')?

在文件系統上存儲字節碼的字節碼緩存。它接受兩個參數:存儲緩存項的目錄和用于構建文件名的模式字符串。

如果未指定目錄,則選擇默認緩存目錄。在Windows上,使用用戶的臨時目錄,在UNIX系統上,在系統臨時目錄中為用戶創建一個目錄。

該模式可用于在同一目錄上運行多個單獨的緩存。默認模式是 '__jinja2_%s.cache' . %s 替換為緩存鍵。

>>> bcc = FileSystemBytecodeCache('/tmp/jinja_cache', '%s.cache')

這個字節碼緩存支持使用clear方法清除緩存。

class jinja2.MemcachedBytecodeCache(client: _MemcachedClient, prefix: str = 'jinja2/bytecode/', timeout: Optional[int] = None, ignore_memcache_errors: bool = True)?

此類實現使用memcache緩存來存儲信息的字節碼緩存。它不強制執行特定的memcache庫(tummy的memcache或cmemcache),但將接受提供所需最小接口的任何類。

與此類兼容的庫:

(不幸的是,Django緩存接口不兼容,因為它不支持存儲二進制數據,只支持文本。但是,您可以將底層緩存客戶端傳遞到字節碼緩存,該緩存可作為 django.core.cache.cache._client 。)

傳遞給構造函數的客戶端的最小接口是:

class MinimalClientInterface?
set(key, value[, timeout])?

value 是一個字符串 timeout 鍵的超時。如果未提供超時,則應假定為默認超時或不超時;如果提供超時,則應假定為一個整數,其中包含緩存項應存在的秒數。

get(key)?

返回緩存鍵的值。如果緩存中不存在該項,則返回值必須為 None .

構造函數的其他參數是在實際緩存鍵之前添加的所有鍵的前綴,以及緩存系統中字節碼的超時。我們建議高(或無)超時。

此字節碼緩存不支持清除緩存中的已用項。clear方法是一個無操作函數。

Changelog

在 2.7 版本加入: 增加了對忽略memcache錯誤的支持 ignore_memcache_errors 參數。

異步支持?

Changelog

在 2.9 版本加入.

Jinja支持Python asyncawait 語法。對于模板設計器,此支持(啟用時)是完全透明的,模板看起來仍然完全相同。但是,開發人員應該了解實現,因為它會影響您可以使用的api類型。

默認情況下,異步支持被禁用。啟用它將導致環境在幕后編譯不同的代碼,以便在異步事件循環中處理異步和同步代碼。這有以下含義:

  • 模板呈現要求事件循環對當前線程可用。 asyncio.get_event_loop() 必須返回事件循環。

  • 編譯的代碼使用 await 函數、屬性和用途 async for 循環。為了支持在此上下文中同時使用異步和同步函數,在所有調用和訪問周圍放置了一個小包裝器,與純異步代碼相比,這增加了開銷。

  • 同步方法和過濾器在需要的地方成為其相應異步實現的包裝器。例如, render 調用 async_render|map 支持異步iterables。

可等待的對象可以從模板中的函數返回,模板中的任何函數調用都將自動等待結果。這個 await 通常情況下,Python是隱含的。例如,您可以提供一個從數據庫異步加載數據的方法,從模板設計器的角度來看,可以像調用任何其他函數一樣調用它。

政策?

從Jinja 2.9開始,可以在環境中配置策略,這對過濾器和其他模板構造的行為有輕微影響。它們可以配置為 policies 屬性。

例子::

env.policies['urlize.rel'] = 'nofollow noopener'
truncate.leeway

為配置leeway默認值 truncate 過濾器。2.9中介紹的leeway,但為了恢復與舊模板的兼容性,可以將其配置為 0 把以前的行為恢復過來。默認值為 5 .

urlize.rel

一個字符串,用于定義 rel 生成的鏈接的屬性 urlize 過濾器。始終添加這些項目。默認值為 noopener .

urlize.target

為來自的鏈接發出的默認目標 urlize 如果調用未顯式定義其他目標,則篩選。

json.dumps_function

如果將此值設置為 None 然后 tojson 過濾器將使用此函數而不是默認函數進行轉儲。注意,這個函數應該接受將來可能從過濾器傳遞的任意額外參數。當前唯一可以傳遞的參數是 indent . 默認轉儲函數為 json.dumps .

json.dumps_kwargs

要傳遞給dump函數的關鍵字參數。默認值為 {{'sort_keys': True}} .

ext.i18n.trimmed

如果設置為 True , {{% trans %}} 街區 i18n擴展 將始終統一換行符和周圍空白,就像 trimmed 使用了修飾符。

公用事業?

如果您向Jinja環境添加自定義過濾器或函數,這些helper函數和類非常有用。

jinja2.escape(s)?

轉換字符 & , < , > , '"s 到HTML安全序列。如果需要在HTML中顯示可能包含此類字符的文本,請使用此選項。此函數不會轉義具有HTML表示形式(如已轉義數據)的對象。

返回值為 Markup 字符串。

jinja2.clear_caches() None?

Jinja為環境和lexer保留內部緩存。這些都是為了使Jinja不必一直重新創建環境和Lexer。通常情況下,您不必關心這一點,但如果您正在測量內存消耗,您可能需要清理緩存。

jinja2.is_undefined(obj: Any) bool?

Undefined 但看起來好多了。這可用于想要對未定義變量做出反應的自定義篩選器或測試。例如,自定義默認篩選器可以如下所示:

def default(var, default=''):
    if is_undefined(var):
        return default
    return var

注意

金賈 Markup 類至少與掛架和Genshi兼容。預計更多的模板引擎和框架將 __html__ 概念很快。

例外情況?

exception jinja2.TemplateError(message: Optional[str] = None)?

所有模板錯誤的基類。

exception jinja2.UndefinedError(message: Optional[str] = None)?

在模板嘗試操作時引發 Undefined .

exception jinja2.TemplateNotFound(name: Optional[Union[str, Undefined]], message: Optional[str] = None)?

如果模板不存在則引發。

Changelog

在 2.11 版本發生變更: 如果名字是 Undefined 但沒有提供任何信息 UndefinedError 提高了。

exception jinja2.TemplatesNotFound(names: Sequence[Union[str, Undefined]] = (), message: Optional[str] = None)?

喜歡 TemplateNotFound TemplateNotFound 異常,因此只捕獲基本異常將同時捕獲這兩個異常。

Changelog

在 2.11 版本發生變更: 如果姓名列表中的姓名是 Undefined ,則會顯示有關未定義的消息,而不是空字符串。

在 2.2 版本加入.

exception jinja2.TemplateSyntaxError(message: str, lineno: int, name: Optional[str] = None, filename: Optional[str] = None)?

引發以告訴用戶模板有問題。

message?

錯誤消息。

lineno?

發生錯誤的行號。

name?

模板的加載名稱。

filename?

以文件系統編碼方式加載模板的文件名(很可能是utf-8,或Windows系統上的mbcs)。

exception jinja2.TemplateRuntimeError(message: Optional[str] = None)?

模板引擎中的一般運行時錯誤。在某些情況下,Jinja可能會提出這個例外。

exception jinja2.TemplateAssertionError(message: str, lineno: int, name: Optional[str] = None, filename: Optional[str] = None)?

類似于模板語法錯誤,但涵蓋了在編譯時模板中的某些內容導致了不一定是由語法錯誤引起的錯誤的情況。但是它是 TemplateSyntaxError 具有相同的屬性。

自定義過濾器?

自定義過濾器只是常規的python函數,它將過濾器的左側作為第一個參數,并將傳遞給過濾器的參數作為額外的參數或關鍵字參數。

例如在過濾器中 {{{{ 42|myfilter(23) }}}} 函數將用 myfilter(42, 23) . 例如,這里有一個簡單的過濾器,可以應用于日期時間對象來格式化它們:

def datetimeformat(value, format='%H:%M / %d-%m-%Y'):
    return value.strftime(format)

您可以通過更新 filters 環境問題:

environment.filters['datetimeformat'] = datetimeformat

在模板內,可以按如下方式使用:

written on: {{ article.pub_date|datetimeformat }}
publication date: {{ article.pub_date|datetimeformat('%d-%m-%Y') }}

還可以將篩選器傳遞給當前模板上下文或環境。如果過濾器想要返回未定義的值或檢查當前 autoescape 設置。為此,存在三個裝飾師: environmentfilter() , contextfilter()evalcontextfilter() .

這里有一個小示例過濾器,它將文本拆分為HTML換行符和段落,并在啟用自動轉義時將返回值標記為安全的HTML字符串:

import re
from jinja2 import evalcontextfilter, Markup, escape

_paragraph_re = re.compile(r"(?:\r\n|\r(?!\n)|\n){2,}")

@evalcontextfilter
def nl2br(eval_ctx, value):
    result = "\n\n".join(
        f"<p>{p.replace('\n', Markup('<br>\n'))}</p>"
        for p in _paragraph_re.split(escape(value))
    )
    if eval_ctx.autoescape:
        result = Markup(result)
    return result

上下文篩選器的工作方式與第一個參數是當前活動的相同 Context 而不是環境。

評估背景?

評估上下文(簡稱eval context或eval ctx)是jinja 2.4中引入的一個新對象,可以在運行時激活和停用已編譯的功能。

目前它只用于啟用和禁用自動轉義,但也可以用于擴展。

在以前的Jinja版本中,為了檢查環境中的自動轉義狀態,過濾器和函數被標記為環境可調用文件。在新版本中,我們鼓勵您從評估上下文中檢查設置。

以前的版本:

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

在新版本中,您可以使用 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.EvalContextModifiernodes.ScopedEvalContextModifier 來自擴展,而不是Eval上下文對象本身。

class jinja2.nodes.EvalContext(environment: Environment, template_name: Optional[str] = None)?

保存評估時間信息。自定義屬性可以在擴展中附加到它。

autoescape?

TrueFalse 取決于自動轉義是否處于活動狀態。

volatile?

True 如果編譯器在編譯時無法計算某些表達式。在運行時,這應該始終是 False .

自定義測試?

測試就像過濾器一樣工作,只是測試無法訪問環境或上下文,并且無法鏈接它們。測試的返回值應為 TrueFalse . 測試的目的是為模板設計者提供執行類型和一致性檢查的可能性。

這里是一個簡單的測試,檢查變量是否是質數:

import math

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

您可以通過更新 tests 環境問題:

environment.tests['prime'] = is_prime

然后,模板設計器可以使用如下測試:

{% if 42 is prime %}
    42 is a prime number
{% else %}
    42 is not a prime number
{% endif %}

超空間?

變量存儲在 Environment.globals dict是特殊的,因為它們也可用于導入的模板,即使它們是在沒有上下文的情況下導入的。這是一個可以放置變量和函數的地方,這些變量和函數應該隨時可用。另外 Template.globals 存在的變量可用于所有可用的特定模板 render() 電話。

低層API?

低級API公開了一些功能,這些功能對于理解一些實現細節、調試目的或高級功能很有用。 extension 技術。除非你確切知道你在做什么,否則我們不建議你使用這些。

Environment.lex(source: str, name: Optional[str] = None, filename: Optional[str] = None) Iterator[Tuple[int, str, str]]?

lex給定的源代碼并返回一個生成器,該生成器以元組的形式生成令牌 (lineno, token_type, value) . 這對 extension development 以及調試模板。

這不執行預處理。如果要應用擴展的預處理,則必須通過 preprocess() 方法。

Environment.parse(source: str, name: Optional[str] = None, filename: Optional[str] = None) Template?

分析源代碼并返回抽象語法樹。編譯器使用此節點樹將模板轉換為可執行源代碼或字節碼。這對于調試或從模板中提取信息很有用。

如果你是 developing Jinja extensions 這可以很好地概述生成的節點樹。

Environment.preprocess(source: str, name: Optional[str] = None, filename: Optional[str] = None) str?

用所有擴展名預處理源。對于所有的解析和編譯方法都會自動調用此函數,但是 not 對于 lex() 因為在那里,您通常只希望對實際的源進行標記化。

Template.new_context(vars: Optional[Dict[str, Any]] = None, shared: bool = False, locals: Optional[Mapping[str, Any]] = None) Context?

創建新的 Context 對于此模板。提供的var將傳遞到模板。默認情況下,全局變量被添加到上下文中。如果“共享”設置為 True 數據按原樣傳遞到上下文,而不添加全局變量。

locals 可以是局部變量的dict以供內部使用。

Template.root_render_func(context)?

這是低級渲染函數。它通過了 Context 必須由 new_context() 相同模板或兼容模板的。此呈現函數由編譯器根據模板代碼生成,并返回生成字符串的生成器。

如果模板代碼中發生異常,模板引擎將不會重寫異常,而是通過原始異常。實際上,只能從 render() / generate() / stream() 打電話。

Template.blocks?

塊渲染函數的指令。每個函數的工作方式與 root_render_func() 有同樣的限制。

Template.is_up_to_date?

這個屬性是 False 如果有更新版本的模板可用,否則 True .

注意

低級API是脆弱的。未來的Jinja版本將嘗試不以向后不兼容的方式更改它,但Jinja內核中的修改可能會閃耀光芒。例如,如果Jinja在以后的版本中引入了一個新的AST節點,則 parse() .

元API?

Changelog

在 2.2 版本加入.

metaAPI返回一些抽象語法樹的信息,這些信息可以幫助應用程序實現更高級的模板概念。meta api的所有函數都在抽象語法樹上操作,該抽象語法樹由 Environment.parse() 方法。

jinja2.meta.find_undeclared_variables(ast: Template) Set[str]?

返回AST中所有變量的集合,這些變量將在運行時從上下文中查找。因為在編譯時不知道哪些變量將根據運行時執行的路徑使用,所以返回所有變量。

>>> from jinja2 import Environment, meta
>>> env = Environment()
>>> ast = env.parse('{% set foo = 42 %}{{ bar + foo }}')
>>> meta.find_undeclared_variables(ast) == {'bar'}
True

實施

在內部,代碼生成器用于查找未聲明的變量。這很好知道,因為代碼生成器可能會引發 TemplateAssertionError 在編譯期間,實際上,此函數當前也可以引發該異常。

jinja2.meta.find_referenced_templates(ast: Template) Iterator[Optional[str]]?

從AST中查找所有引用的模板。這將返回所有硬編碼模板擴展、包含和導入的迭代器。如果使用動態繼承或包含, None 將屈服。

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

此函數對于依賴項跟蹤很有用。例如,如果要在布局模板更改后重建網站的部分內容。