API

このドキュメントでは、Jinja の API について説明します。テンプレート言語については説明しません（テンプレート言語については、テンプレートデザイナー向けドキュメント を参照してください）。このドキュメントは、アプリケーションにテンプレートインターフェースを実装する開発者にとって最も役立ち、Jinja テンプレートを作成する開発者にとってはそれほど役立ちません。

基本

Jinja は、テンプレート Environment と呼ばれる中心的なオブジェクトを使用します。このクラスのインスタンスは、設定とグローバルオブジェクトを格納するために使用され、ファイルシステムまたはその他の場所からテンプレートを読み込むために使用されます。 Template クラスのコンストラクタを使用して文字列からテンプレートを作成する場合でも、共有されたものであれ、環境が自動的に作成されます。

ほとんどのアプリケーションは、アプリケーションの初期化時に1つの Environment オブジェクトを作成し、それを使用してテンプレートを読み込みます。ただし、異なる設定が使用されている場合、複数の環境を並べて使用することが役立つ場合があります。

アプリケーションのテンプレートを読み込むように Jinja を設定する最も簡単な方法は、PackageLoader を使用することです。

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

これにより、yourapp Python パッケージ内の templates フォルダ（または yourapp.py Python モジュールの隣）にあるテンプレートを検索するローダーを使用してテンプレート環境が作成されます。また、HTML ファイルの自動エスケープも有効になります。このローダーは、yourapp がインポート可能であることだけを必要とし、フォルダへの絶対パスを自動的に判断します。

他の方法や他の場所からテンプレートを読み込むために、さまざまなローダーを使用できます。それらは、下記のローダーセクションに記載されています。プロジェクトに特化したソースからテンプレートを読み込む場合は、独自のローダーを作成することもできます。

この環境からテンプレートを読み込むには、get_template() メソッドを呼び出します。これにより、読み込まれた Template が返されます。

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

いくつかの変数を用いてレンダリングするには、render() メソッドを呼び出します。

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

Template または Environment.from_string() に文字列を渡すのではなく、テンプレートローダーを使用することには、多くの利点があります。使いやすさが向上するだけでなく、テンプレートの継承も有効になります。

自動エスケープに関する注記

今後のバージョンの Jinja では、セキュリティ上の理由から、自動エスケープをデフォルトで有効にする可能性があります。そのため、デフォルトに依存するのではなく、明示的に自動エスケープを設定することをお勧めします。

ハイレベルAPI

ハイレベルAPIは、アプリケーションでJinjaテンプレートを読み込んでレンダリングするために使用するAPIです。一方、ローレベルAPI は、Jinja をより深く掘り下げたい場合や 拡張機能を開発する 場合にのみ役立ちます。

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

指定された場合、文字列として、行ベースのコメントのプレフィックスとして使用されます。行ステートメント も参照してください。

変更履歴

バージョン 2.2 で追加。

trim_blocks

これを True に設定すると、ブロック（変数タグではなくブロック）の後の最初の改行が削除されます。デフォルトは False です。

lstrip_blocks

これを True に設定すると、ブロックの先頭にある先頭の空白とタブが削除されます。デフォルトは False です。

newline_sequence

改行を開始するシーケンス。'\r'、'\n'、または '\r\n' のいずれかでなければなりません。デフォルトは '\n' であり、Linux や OS X システム、および Web アプリケーションに適したデフォルトです。

keep_trailing_newline

テンプレートの末尾の改行を保持します。デフォルトは False で、テンプレートの末尾にある単一の改行（存在する場合）が削除されます。

変更履歴

バージョン 2.7 で追加。

extensions

使用する Jinja 拡張機能のリスト。これは、文字列としてのインポートパスまたは拡張機能クラスのいずれかになります。詳細については、拡張機能のドキュメント を参照してください。

optimized

最適化を有効にする必要がありますか？デフォルトは True です。

undefined

Undefined またはそのサブクラスで、テンプレート内の未定義の値を表すために使用されます。

finalize

変数式の結果を出力する前に処理するために使用できる呼び出し可能オブジェクトです。たとえば、ここで None を暗黙的に空文字列に変換できます。

autoescape

True に設定すると、XML/HTML の自動エスケープ機能がデフォルトで有効になります。自動エスケープの詳細については、Markup を参照してください。Jinja 2.4 以降、これはテンプレート名を渡される呼び出し可能オブジェクトでもあり、自動エスケープをデフォルトで有効にする必要があるかどうかに応じて True または False を返す必要があります。

変更履歴

バージョン 2.4 で変更: autoescape は関数になることができます。

loader

この環境のテンプレートローダー。

cache_size

キャッシュのサイズ。デフォルトは 400 で、400 以上のテンプレートが読み込まれると、ローダーは最近使用されていないテンプレートをクリアします。キャッシュサイズを 0 に設定すると、テンプレートは常に再コンパイルされ、キャッシュサイズを -1 に設定すると、キャッシュはクリアされません。

変更履歴

バージョン 2.8 で変更: キャッシュサイズは 50 から 400 に増加しました。

auto_reload

一部のローダーは、テンプレートソースが変更される可能性のある場所（ファイルシステムやデータベースなど）からテンプレートを読み込みます。 auto_reload を True （デフォルト）に設定すると、テンプレートが要求されるたびに、ローダーはソースが変更されたかどうかを確認し、変更されている場合はテンプレートを再読み込みします。パフォーマンスを向上させるために、これを無効にすることもできます。

bytecode_cache

バイトコードキャッシュオブジェクトに設定されている場合、このオブジェクトは内部 Jinja バイトコードのキャッシュを提供するため、テンプレートが変更されていない場合は解析する必要がありません。

バイトコードキャッシュ を参照してください。

enable_async

true に設定すると、非同期関数とジェネレータの使用を可能にする非同期テンプレート実行が有効になります。

パラメータ:
shared

Template コンストラクタを使用してテンプレートが作成された場合、環境は自動的に作成されます。これらの環境は共有環境として作成されるため、複数のテンプレートが同じ匿名環境を持つ可能性があります。すべての共有環境では、この属性は True であり、それ以外の場合は False です。

sandboxed

環境がサンドボックス化されている場合、この属性は True です。サンドボックスモードについては、SandboxedEnvironment のドキュメントを参照してください。

filters

この環境のフィルタの辞書です。テンプレートがロードされるまでは、新しいフィルタを追加したり、古いフィルタを削除したりしても安全です。カスタムフィルタについては、カスタムフィルタ を参照してください。有効なフィルタ名については、識別子の命名に関する注記 を参照してください。

tests

この環境のテスト関数の辞書です。テンプレートがロードされるまでは、この辞書を変更しても安全です。カスタムテストについては、カスタムテスト を参照してください。有効なテスト名については、識別子の命名に関する注記 を参照してください。

globals

環境によってロードされたすべてのテンプレートで使用可能な変数の辞書です。テンプレートがロードされるまでは、これを変更しても安全です。詳細については、グローバル名前空間 を参照してください。有効なオブジェクト名については、識別子の命名に関する注記 を参照してください。

policies

ポリシー を含む辞書です。これらを再構成して、ランタイムの動作や特定のテンプレート機能を変更できます。通常、これらはセキュリティ関連です。

code_generator_class

コード生成に使用されるクラスです。テンプレートがコンパイルするPythonコードを変更する必要がある場合を除き、ほとんどの場合、これは変更しないでください。

context_class

テンプレートに使用されるコンテキストです。テンプレート変数の処理方法の内蔵部分を変更する必要がある場合を除き、ほとんどの場合、これは変更しないでください。詳細については、Context を参照してください。

overlay([options])

キャッシュとオーバーライドされた属性を除いて、現在の環境とすべてのデータを共有する新しいオーバーレイ環境を作成します。オーバーレイされた環境では、拡張機能を削除することはできません。オーバーレイされた環境は、リンクされている環境のすべての拡張機能と、オプションの追加拡張機能を自動的に取得します。

オーバーレイの作成は、初期環境が完全に設定された後に行う必要があります。すべての属性が実際にリンクされているわけではなく、一部はコピーされるだけであるため、元の環境に対する変更が反映されない場合があります。

バージョン 3.1.2 で変更されました: __init__ と一致するように、newline_sequence、keep_trailing_newline、および enable_async パラメータが追加されました。

パラメータ:
戻り値:

Environment

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

name の新しい Undefined オブジェクトを作成します。これは、一部の操作で未定義のオブジェクトを返す可能性のあるフィルタや関数に役立ちます。hint を除くすべてのパラメータは、可読性を向上させるためにキーワードパラメータとして提供する必要があります。hint は、提供された場合に例外のエラーメッセージとして使用されます。それ以外の場合は、エラーメッセージは obj と name から自動的に生成されます。exc として提供された例外は、生成された未定義オブジェクトに対して、未定義オブジェクトが許可しない操作が行われた場合に発生します。デフォルトの例外は UndefinedError です。hint が提供されている場合、name は省略できます。

未定義のオブジェクトを作成する最も一般的な方法は、名前のみを指定することです。

return environment.undefined(name='some_name')

つまり、名前 some_name は定義されていません。名前がオブジェクトの属性からのものである場合、エラーメッセージを改善するために、未定義オブジェクトに保持オブジェクトを伝えることが理にかなっています。

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

より複雑な例として、ヒントを指定できます。たとえば、first() フィルタはその方法で未定義のオブジェクトを作成します。

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

name または obj がわかっている場合（たとえば、属性にアクセスしたため）、カスタム hint が提供されている場合でも、未定義オブジェクトに渡す必要があります。これにより、未定義オブジェクトはエラーメッセージを強化できます。

add_extension(extension)

環境の作成後に拡張機能を追加します。

変更履歴

バージョン 2.5 で追加されました。

パラメータ:

extension (str | Type[Extension])

戻り値:

None

extend(**attributes)

環境インスタンスに、まだ存在しない項目を追加します。拡張機能が、継承を壊すことなくコールバックと設定値を登録するために使用されます。

パラメータ:

attributes (Any)

戻り値:

None

compile_expression(source, undefined_to_none=True)

キーワード引数を受け付ける呼び出し可能なオブジェクトを返す便利なヘルパーメソッドです。この引数は、式内の変数として表示されます。呼び出されると、式の結果を返します。

これは、アプリケーションがテンプレート「設定ファイル」や同様の状況でJinjaと同じルールを使用する場合に役立ちます。

使用例

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

デフォルトでは、式が未定義の値を返す場合、戻り値はNoneに変換されます。undefined_to_noneをFalseに設定することで変更できます。

>>> env.compile_expression('var')() is None
True
>>> env.compile_expression('var', undefined_to_none=False)()
Undefined
変更履歴

バージョン2.1で追加。

パラメータ:

  • source (str)

  • undefined_to_none (bool)

戻り値:

TemplateExpression

compile_templates(target, extensions=None, filter_func=None, zip='deflated', log_function=None, ignore_errors=True)

ローダーが検出できるすべてのテンプレートを見つけ、コンパイルし、targetに格納します。zipがNoneの場合、zipファイルではなく、ディレクトリにテンプレートが格納されます。デフォルトでは、deflate zipアルゴリズムが使用されます。storedアルゴリズムに切り替えるには、zipを'stored'に設定できます。

extensionsとfilter_funcはlist_templates()に渡されます。返された各テンプレートは、ターゲットフォルダまたはzipファイルにコンパイルされます。

デフォルトでは、テンプレートコンパイルエラーは無視されます。ログ関数が提供されている場合、エラーがログに記録されます。テンプレート構文エラーでコンパイルを中止するには、ignore_errorsをFalseに設定できます。構文エラーが発生すると例外が発生します。

変更履歴

バージョン2.4で追加。

パラメータ:
戻り値:

None

list_templates(extensions=None, filter_func=None)

この環境のテンプレートのリストを返します。これには、ローダーがローダーのlist_templates()メソッドをサポートしている必要があります。

実際のテンプレート以外にもテンプレートフォルダにファイルがある場合、返されるリストをフィルタリングできます。2つの方法があります。 extensionsをテンプレートのファイル拡張子のリストに設定するか、filter_funcを提供します。これは、テンプレート名を渡される呼び出し可能な関数で、結果リストに含める場合はTrueを返す必要があります。

ローダーがそれをサポートしていない場合、TypeErrorが送出されます。

変更履歴

バージョン2.4で追加。

パラメータ:
戻り値:

List[str]

join_path(template, parent)

テンプレートと親を結合します。デフォルトでは、すべての検索はローダーのルートを基準としているため、このメソッドはtemplateパラメーターをそのまま返しますが、パスを親テンプレートを基準にする必要がある場合は、この関数を使用して実際のテンプレート名を計算できます。

サブクラスはこのメソッドをオーバーライドし、ここでテンプレートパスの結合を実装できます。

パラメータ:
戻り値:

str

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

loaderを使用して名前でテンプレートを読み込み、Templateを返します。テンプレートが存在しない場合、TemplateNotFound例外が送出されます。

パラメータ:

  • name (str | Template) – 読み込むテンプレートの名前。ファイルシステムからテンプレートを読み込む場合、Windowsでもパスセパレータとして「/」が使用されます。

  • parent (str | None) – このテンプレートをインポートする親テンプレートの名前。join_path()を使用して、これを使用して名前変換を実装できます。

  • globals (MutableMapping[str, Any] | None) – このテンプレートのすべてのレンダリングで使用できる追加の変数を使用して、環境globalsを拡張します。テンプレートが既に読み込まれてキャッシュされている場合、グローバルは新しい項目で更新されます。

戻り値:

Template

変更履歴

バージョン3.0での変更: テンプレートがキャッシュから読み込まれる場合、globalsは新しい値を無視するのではなく、テンプレートのグローバルを更新します。

バージョン2.4での変更: nameがTemplateオブジェクトの場合、変更せずに返されます。

select_template(names, parent=None, globals=None)

get_template()と同様ですが、複数の名前でテンプレートの読み込みを試みます。いずれの名前でも読み込みできない場合、TemplatesNotFound例外が発生します。

パラメータ:

  • names (Iterable[str | Template]) – 読み込みを試みるテンプレート名のリスト。順に読み込みを試みます。

  • parent (str | None) – このテンプレートをインポートする親テンプレートの名前。join_path()を使用して、これを使用して名前変換を実装できます。

  • globals (MutableMapping[str, Any] | None) – このテンプレートのすべてのレンダリングで使用できる追加の変数を使用して、環境globalsを拡張します。テンプレートが既に読み込まれてキャッシュされている場合、グローバルは新しい項目で更新されます。

戻り値:

Template

変更履歴

バージョン3.0での変更: テンプレートがキャッシュから読み込まれる場合、globalsは新しい値を無視するのではなく、テンプレートのグローバルを更新します。

バージョン 2.11 で変更: namesがUndefinedの場合、UndefinedError例外が発生します。namesにUndefinedが含まれ、テンプレートが見つからない場合、より分かりやすいメッセージが表示されます。

バージョン 2.4 で変更: namesにTemplateオブジェクトが含まれている場合、変更せずに返されます。

バージョン 2.3 で追加。

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

テンプレート名のイテラブルが指定されている場合はselect_template()を、1つの名前が指定されている場合はget_template()を使用します。

変更履歴

バージョン 2.3 で追加。

パラメータ:
戻り値:

Template

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

loaderを使用せずに、ソース文字列からテンプレートを読み込みます。

パラメータ:

  • source (str | Template) – テンプレートにコンパイルするJinjaソース。

  • globals (MutableMapping[str, Any] | None) – このテンプレートのすべてのレンダリングで使用できる追加の変数を使用して、環境globalsを拡張します。テンプレートが既に読み込まれてキャッシュされている場合、グローバルは新しい項目で更新されます。

  • template_class (Type[Template] | None) – このTemplateクラスのインスタンスを返します。

戻り値:

Template

class jinja2.Template(source, block_start_string=BLOCK_START_STRING, block_end_string=BLOCK_END_STRING, variable_start_string=VARIABLE_START_STRING, variable_end_string=VARIABLE_END_STRING, comment_start_string=COMMENT_START_STRING, comment_end_string=COMMENT_END_STRING, line_statement_prefix=LINE_STATEMENT_PREFIX, line_comment_prefix=LINE_COMMENT_PREFIX, trim_blocks=TRIM_BLOCKS, lstrip_blocks=LSTRIP_BLOCKS, newline_sequence=NEWLINE_SEQUENCE, keep_trailing_newline=KEEP_TRAILING_NEWLINE, extensions=(), optimized=True, undefined=Undefined, finalize=None, autoescape=False, enable_async=False)

レンダリング可能なコンパイル済みテンプレート。

テンプレートの作成または読み込みには、Environmentのメソッドを使用します。環境は、テンプレートのコンパイル方法と動作方法を構成するために使用されます。

テンプレートオブジェクトを直接作成することもできますが、通常は推奨されません。コンストラクタはEnvironmentとほぼ同じ引数を取ります。同じ環境引数で作成されたすべてのテンプレートは、背後で同じ一時的なEnvironmentインスタンスを共有します。

テンプレートオブジェクトは不変とみなすべきです。オブジェクトの変更はサポートされていません。

パラメータ:
戻り値:

任意

globals

テンプレートがレンダリングされるたびに、レンダリング中に渡す必要なく利用可能な変数の辞書。テンプレートの読み込み方法によっては、環境や他のテンプレートと共有されている可能性があるため、変更しないでください。

Environment.globalsに追加の値がEnvironment.get_template()に渡されない限り、デフォルトになります。

グローバル変数は、テンプレートのすべてのレンダリングで共通するデータのみを対象としています。特定のデータはrender()に渡す必要があります。

グローバル名前空間を参照してください。

name

テンプレートの読み込み名。文字列からテンプレートを読み込んだ場合はNone。

filename

ファイルシステムから読み込んだ場合のテンプレートのファイル名。それ以外の場合はNone。

render([context])

このメソッドは、dictコンストラクタと同じ引数を受け付けます。辞書、辞書のサブクラス、またはいくつかのキーワード引数です。引数が指定されていない場合、コンテキストは空になります。以下の2つの呼び出しは同じ動作をします。

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

レンダリングされたテンプレートを文字列として返します。

パラメータ:
戻り値:

str

generate([context])

非常に大きなテンプレートの場合、テンプレート全体を一度にレンダリングするのではなく、個々のステートメントを順番に評価し、少しずつ出力する方が効率的です。このメソッドはまさにそれを行い、文字列を一つずつ返すジェネレータを返します。

render()と同じ引数を受け付けます。

パラメータ:
戻り値:

Iterator[str]

stream([context])

generate()とまったく同じように動作しますが、TemplateStreamを返します。

パラメータ:
戻り値:

TemplateStream

async render_async([context])

render()と同様に動作しますが、awaitされるとレンダリングされたテンプレート文字列全体を返すコルーチンを返します。これには、非同期機能が有効になっている必要があります。

使用例

await template.render_async(knights='that say nih; asynchronously')
パラメータ:
戻り値:

str

async generate_async([context])

generate()の非同期バージョンです。非常に似たように動作しますが、非同期イテレータを返します。

パラメータ:
戻り値:

AsyncGenerator[str, object]

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

このメソッドは、引数なしで呼び出された場合、module属性と同様に動作しますが、キャッシュするのではなく、毎回テンプレートを評価します。辞書を提供してコンテキストとして使用することもできます。引数はnew_context()メソッドと同じです。

パラメータ:
戻り値:

TemplateModule

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ジェネレータとほぼ同様に動作しますが、イテレーションの総数を減らすために複数のアイテムをバッファリングできます。デフォルトでは、出力はバッファリングされません。つまり、テンプレート内のバッファリングされていない命令ごとに、1つの文字列が出力されます。

バッファサイズ5でバッファリングを有効にすると、5つのアイテムが新しい文字列に結合されます。これは、各イテレーション後にフラッシュするWSGI経由でクライアントに大きなテンプレートをストリーミングする場合に主に役立ちます。

パラメータ:

gen (Iterator[str])

dump(fp, encoding=None, errors='strict')

ストリーム全体をファイルまたはファイルのようなオブジェクトにダンプします。デフォルトでは文字列が書き込まれます。書き込み前にエンコードする場合は、encodingを指定します。

使用例

Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
パラメータ:
戻り値:

None

disable_buffering()

出力バッファリングを無効にします。

戻り値:

None

enable_buffering(size=5)

バッファリングを有効にします。 size個のアイテムをバッファリングしてから出力します。

パラメータ:

size (int)

戻り値:

None

自動エスケープ

変更履歴

バージョン2.4で変更されました。

Jinjaは、自動エスケープ機能を備えています。Jinja 2.9以降、autoescape拡張機能は削除され、組み込みとなりました。ただし、自動エスケープはまだデフォルトでは有効になっていませんが、将来的には変更される可能性があります。自動エスケープの適切なデフォルトを設定することをお勧めします。これにより、テンプレートごとに自動エスケープを有効および無効にすることができます（たとえば、HTMLとテキスト）。

jinja2.select_autoescape(enabled_extensions=('html', 'htm', 'xml'), disabled_extensions=(), default_for_string=True, default=False)

テンプレートのファイル名に基づいて、自動エスケープの初期値をインテリジェントに設定します。カスタム関数を作成したくない場合は、自動エスケープを設定する推奨方法です。

文字列から作成されたすべてのテンプレート、または.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の値に設定されます。

セキュリティ上の理由から、この関数は大文字と小文字を区別しません。

変更履歴

バージョン2.9で追加されました。

パラメータ:
戻り値:

Callable[[str | None], bool]

ここでは、'.html'、'.htm'、'.xml'で終わるテンプレートに対して自動エスケープを有効にし、その他の拡張子についてはデフォルトで無効にする推奨設定を示します。select_autoescape()関数をこれに使用できます。

from jinja2 import Environment, PackageLoader, 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ブロックを使用して、動作を一時的に変更できます（Autoescape Overridesを参照）。

識別子に関する注意事項

JinjaはPythonの命名規則を使用します。有効な識別子は、Pythonで受け入れられる文字の任意の組み合わせにすることができます。

フィルターとテストは、個別の名前空間で検索され、識別子の構文がわずかに修正されています。フィルターとテストには、トピック別にフィルターとテストをグループ化するためのドットを含めることができます。たとえば、フィルター辞書に関数を追加して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

未定義オブジェクトが発生させようとする例外。通常はUndefinedErrorまたはSecurityErrorのいずれかです。

_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
変更履歴

バージョン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
パラメータ:

また、失敗時にロギングを実装するために未定義オブジェクトをデコレートできるファクトリ関数もあります。

jinja2.make_logging_undefined(logger=None, base=Undefined)

ロガーオブジェクトが与えられると、特定の失敗をログに記録する新しい未定義クラスを返します。反復処理と出力をログに記録します。ロガーが指定されていない場合は、デフォルトのロガーが作成されます。

例

logger = logging.getLogger(__name__)
LoggingUndefined = make_logging_undefined(
    logger=logger,
    base=Undefined
)
変更履歴

バージョン2.8で追加。

パラメータ:

  • logger (logging.Logger | None) – 使用するロガー。指定されていない場合は、デフォルトのロガーが作成されます。

  • base (Type[Undefined]) – ロギング機能を追加する基底クラス。デフォルトはUndefinedです。

戻り値:

Type[Undefined]

未定義オブジェクトは、undefinedを呼び出すことで作成されます。

実装

Undefinedは、特殊な__underscore__メソッドをオーバーライドすることで実装されます。たとえば、デフォルトのUndefinedクラスは__str__を実装して空文字列を返し、一方__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):
    def __iter__(self):
        self._fail_with_undefined_error()

コンテキスト

class jinja2.runtime.Context

テンプレートコンテキストは、テンプレートの変数を保持します。テンプレートに渡された値と、テンプレートがエクスポートする名前も格納します。インスタンスの作成はサポートされておらず、役に立ちません。これは、テンプレート評価のさまざまな段階で自動的に作成され、手動で作成する必要はありません。

コンテキストは不変です。parentに対する変更は**行ってはなりません**。また、生成されたテンプレートコードからのみvarsに対する変更が許可されます。pass_context()としてマークされたテンプレートフィルターとグローバル関数は、最初の引数としてアクティブなコンテキストを受け取り、コンテキストへの読み取り専用アクセスが許可されます。

テンプレートコンテキストは、読み取り専用の辞書操作（get、keys、values、items、iterkeys、itervalues、iteritems、__getitem__、__contains__）をサポートしています。さらに、resolve()メソッドがあり、KeyErrorで失敗するのではなく、存在しない変数に対してUndefinedオブジェクトを返します。

パラメータ:
parent

テンプレートが参照する、読み取り専用のグローバル変数の辞書です。これらは、別のContext、Environment.globalsまたはTemplate.globals、あるいはグローバル変数とrender関数に渡された変数を組み合わせた辞書から取得されます。変更してはなりません。

vars

テンプレートのローカル変数です。このリストには、parentスコープからの環境およびコンテキスト関数、ローカルな変更、テンプレートからエクスポートされた変数が含まれます。テンプレートはテンプレート評価中にこの辞書を変更しますが、フィルタとコンテキスト関数は変更できません。

environment

テンプレートをロードした環境です。

exported_vars

このセットには、テンプレートがエクスポートするすべての名前が含まれています。名前の値はvars辞書にあります。エクスポートされた変数を辞書としてコピーするには、get_exported()を使用できます。

name

このコンテキストを所有するテンプレートのロード名です。

blocks

テンプレートにおけるブロックの現在のマッピングを含む辞書です。この辞書のキーはブロックの名前、値は登録されたブロックのリストです。各リストの最後の項目は、現在の有効なブロック（継承チェーンにおける最新のもの）です。

eval_ctx

現在の評価コンテキストです。

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

指定された引数とキーワード引数を使用して呼び出し可能オブジェクトを呼び出しますが、呼び出し可能オブジェクトがpass_context()またはpass_environment()を持つ場合、アクティブなコンテキストまたは環境を最初の引数として挿入します。

パラメータ:
戻り値:

Any | Undefined

get(key, default=None)

名前で変数を検索するか、キーが見つからない場合はデフォルト値を返します。

パラメータ:

  • key（str） – 検索する変数名。

  • default（Any） – キーが見つからない場合に返す値。

戻り値:

任意

resolve(key)

名前で変数を検索するか、キーが見つからない場合はUndefinedオブジェクトを返します。

カスタムの動作を追加する必要がある場合は、このメソッドではなくresolve_or_missing()をオーバーライドしてください。さまざまな検索関数は、このメソッドではなくそのメソッドを使用します。

パラメータ:

key（str） – 検索する変数名。

戻り値:

Any | Undefined

resolve_or_missing(key)

名前で変数を検索するか、キーが見つからない場合はmissingセンティネルを返します。

カスタムの検索動作を追加するには、このメソッドをオーバーライドします。resolve()、get()、および__getitem__()はこのメソッドを使用します。このメソッドを直接呼び出さないでください。

パラメータ:

key（str） – 検索する変数名。

戻り値:

任意

get_exported()

エクスポートされた変数を含む新しい辞書を取得します。

戻り値:

Dict[str, Any]

get_all()

エクスポートされた変数を含む辞書として完全なコンテキストを返します。最適化のため、実際の複製ではない可能性があるため、使用には注意してください。

戻り値:

Dict[str, Any]

コンテキストは不変であり、変更を防ぎます。変更されたとしても、それらの変更が表示されない場合があります。パフォーマンスのため、Jinjaはコンテキストをデータストレージとしてではなく、主にデータソースとして使用します。テンプレートで定義されていない変数はコンテキストで検索されますが、テンプレートで定義されている変数はローカルに格納されます。

コンテキストを直接変更する代わりに、関数はテンプレート自体内の変数に割り当てることができる値を返す必要があります。

{% set comments = get_latest_comments() %}

ローダー

ローダーは、ファイルシステムなどのリソースからテンプレートをロードする役割を担います。環境は、Pythonのsys.modulesのように、コンパイル済みモジュールをメモリに保持します。ただし、sys.modulesとは異なり、このキャッシュはデフォルトでサイズが制限されており、テンプレートは自動的に再ロードされます。すべてのローダーはBaseLoaderのサブクラスです。独自のローダーを作成する場合は、BaseLoaderをサブクラス化し、get_sourceをオーバーライドします。

class jinja2.BaseLoader

すべてのローダーの基底クラスです。これをサブクラス化し、get_sourceをオーバーライドして、カスタムのロードメカニズムを実装します。環境は、ローダーのloadメソッドを呼び出してTemplateオブジェクトを取得するget_templateメソッドを提供します。

ファイルシステム上のテンプレートを検索するローダーの非常に基本的な例を以下に示します。

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, template)

テンプレートのソース、ファイル名、およびリロードヘルパーを取得します。環境とテンプレート名が渡され、(source, filename, uptodate) の形式のタプルを返すか、テンプレートが見つからない場合は TemplateNotFound エラーを発生させる必要があります。

返されるタプルの source 部分は、テンプレートのソースを文字列として含む必要があります。filename は、ファイルシステムからロードされた場合はファイルのファイルシステム上の名前でなければなりません。そうでない場合は None です。ローダー拡張子が使用されていない場合、filename は Python によってトレースバックに使用されます。

タプルの最後の項目は uptodate 関数です。自動リロードが有効になっている場合、常にテンプレートが変更されたかどうかをチェックするために呼び出されます。引数は渡されないので、関数は何らかの場所に古い状態を保存する必要があります（例えばクロージャ内）。False を返すと、テンプレートがリロードされます。

パラメータ:
戻り値:

Tuple[str, str | None, Callable[[], bool] | None]

load(environment, name, globals=None)

テンプレートをロードします。このメソッドはキャッシュ内のテンプレートを検索するか、get_source() を呼び出してロードします。他のローダーのコレクションで動作するローダー（PrefixLoader や ChoiceLoader など）は、このメソッドをオーバーライドするべきではありません。get_source を直接呼び出します。

パラメータ:
戻り値:

Template

Jinja が提供する組み込みローダーの一覧を以下に示します。

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

ファイルシステムのディレクトリからテンプレートをロードします。

パスは相対パスでも絶対パスでもかまいません。相対パスは現在の作業ディレクトリからの相対パスです。

loader = FileSystemLoader("templates")

複数のパスをリストで指定できます。最初のマッチするテンプレートが見つかるまで、ディレクトリが順番に検索されます。

loader = FileSystemLoader(["/override/templates", "/default/templates"])
パラメータ:

  • searchpath (str | os.PathLike[str] | Sequence[str | os.PathLike[str]]) – テンプレートを含むディレクトリへのパス、またはパスのリスト。

  • encoding (str) – テンプレートファイルからテキストを読み取る際のエンコーディング。

  • followlinks (bool) – パス内のシンボリックリンクをたどるかどうか。

変更履歴

バージョン 2.8 で変更: followlinks パラメータが追加されました。

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

Python パッケージ内のディレクトリからテンプレートをロードします。

パラメータ:

  • package_name (str) – テンプレートディレクトリを含むパッケージのインポート名。

  • package_path (str) – インポートされたパッケージ内でテンプレートを含むディレクトリ。

  • encoding (str) – テンプレートファイルのエンコーディング。

次の例では、project.ui パッケージ内の pages ディレクトリにあるテンプレートを検索します。

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

ディレクトリとしてインストールされたパッケージ（標準的な pip の動作）または zip/egg ファイル（あまり一般的ではない）のみがサポートされます。パッケージ内のデータのイントロスペクションのための Python API は、このローダーに必要な方法で他のインストール方法をサポートするには制限が多すぎます。

PEP 420 名前空間パッケージのサポートは限定的です。テンプレートディレクトリは、1つの名前空間コントリビューターにのみ存在すると仮定されます。名前空間に貢献する zip ファイルはサポートされていません。

変更履歴

バージョン 3.0 で変更: setuptools を依存関係として使用しなくなりました。

バージョン 3.0 で変更: PEP 420 名前空間パッケージのサポートが限定されました。

class jinja2.DictLoader(mapping)

テンプレート名をテンプレートソースにマッピングする Python の辞書からテンプレートをロードします。このローダーは単体テストに役立ちます。

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

自動リロードはほとんど役に立たないので、デフォルトで無効になっています。

パラメータ:

mapping (Mapping[str, str])

class jinja2.FunctionLoader(load_func)

ローディングを行う関数を渡されるローダー。関数はテンプレート名を受け取り、テンプレートソースを含む文字列、(source, filename, uptodatefunc) の形式のタプル、またはテンプレートが存在しない場合は None を返す必要があります。

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

uptodatefunc は、自動リロードが有効になっている場合に呼び出される関数であり、テンプレートが最新の状態である場合は True を返す必要があります。詳細については、同じ戻り値を持つ BaseLoader.get_source() を参照してください。

パラメータ:

load_func (Callable[[str], str | Tuple[str, str | None, Callable[[], bool] | None] | None])

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

ローダーに、各ローダーが接頭辞にバインドされているローダーの辞書を渡します。接頭辞はデフォルトでスラッシュでテンプレートから区切られていますが、delimiter 引数を他のものに設定することで変更できます。

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

'app1/index.html' をロードすると app1 パッケージのファイルがロードされ、'app2/index.html' をロードすると 2 番目のファイルがロードされます。

パラメータ:
class jinja2.ChoiceLoader(loaders)

このローダーは、PrefixLoaderと同様に動作しますが、プレフィックスを指定しません。あるローダーでテンプレートが見つからない場合、次のローダーが試されます。

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

これは、ユーザーが異なる場所から組み込みテンプレートを上書きできるようにする場合に役立ちます。

パラメータ:

loaders (Sequence[BaseLoader])

class jinja2.ModuleLoader(path)

このローダーは、プリコンパイルされたテンプレートからテンプレートを読み込みます。

使用例

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

テンプレートは、Environment.compile_templates()を使用してプリコンパイルできます。

パラメータ:

path (str | os.PathLike[str] | Sequence[str | os.PathLike[str]])

バイトコードキャッシュ

Jinja 2.1以降は、外部バイトコードキャッシュをサポートしています。バイトコードキャッシュにより、生成されたバイトコードをファイルシステムまたは別の場所に保存し、初回使用時のテンプレートの解析を回避できます。

これは、最初のリクエストで初期化されるWebアプリケーションがあり、Jinjaが多くのテンプレートを一度にコンパイルしてアプリケーションの速度を低下させる場合に特に役立ちます。

バイトコードキャッシュを使用するには、それをインスタンス化してEnvironmentに渡します。

class jinja2.BytecodeCache

独自のバイトコードキャッシュを実装するには、このクラスをサブクラス化し、load_bytecode()とdump_bytecode()をオーバーライドする必要があります。これらのメソッドにはどちらもBucketが渡されます。

ファイルシステムにバイトコードを保存する非常に基本的なバイトコードキャッシュ

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)

ファイルシステムベースのバイトコードキャッシュのより高度なバージョンは、Jinjaに含まれています。

load_bytecode(bucket)

サブクラスは、このメソッドをオーバーライドしてバイトコードをバケットに読み込む必要があります。キャッシュ内にバケットのコードが見つからない場合、何も実行してはなりません。

パラメータ:

bucket (Bucket)

戻り値:

None

dump_bytecode(bucket)

サブクラスは、このメソッドをオーバーライドして、バケットからキャッシュにバイトコードを書き込む必要があります。書き込みに失敗した場合は、サイレントに失敗するのではなく、例外を発生させる必要があります。

パラメータ:

bucket (Bucket)

戻り値:

None

clear()

キャッシュをクリアします。このメソッドはJinjaでは使用されませんが、アプリケーションが特定の環境で使用されるバイトコードキャッシュをクリアできるように実装する必要があります。

戻り値:

None

class jinja2.bccache.Bucket(environment, key, checksum)

バケットは、1つのテンプレートのバイトコードを格納するために使用されます。バイトコードキャッシュによって作成および初期化され、読み込み関数に渡されます。

バケットには、キャッシュから内部チェックサムが割り当てられ、これを使用して期限切れのキャッシュ素材を自動的に拒否します。個々のバイトコードキャッシュサブクラスは、キャッシュの無効化について考慮する必要はありません。

パラメータ:
environment

バケットを作成したEnvironmentです。

key

このバケットの一意のキャッシュキーです。

code

ロードされている場合はバイトコード、そうでない場合はNoneです。

reset()

バケットをリセットします（バイトコードをアンロードします）。

戻り値:

None

load_bytecode(f)

ファイルまたはファイルのようなオブジェクトからバイトコードを読み込みます。

パラメータ:

f (BinaryIO)

戻り値:

None

write_bytecode(f)

バイトコードを渡されたファイルまたはファイルのようなオブジェクトにダンプします。

パラメータ:

f (IO[bytes])

戻り値:

None

bytecode_from_string(string)

バイトからバイトコードを読み込みます。

パラメータ:

string (bytes)

戻り値:

None

bytecode_to_string()

バイトコードをバイトとして返します。

戻り値:

bytes

組み込みバイトコードキャッシュ

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

ファイルシステムにバイトコードを保存するバイトコードキャッシュです。キャッシュアイテムが保存されるディレクトリと、ファイル名を構築するために使用されるパターン文字列の2つの引数を受け入れます。

ディレクトリが指定されていない場合、デフォルトのキャッシュディレクトリが選択されます。Windowsではユーザーの一時ディレクトリが使用され、UNIXシステムではシステムの一時ディレクトリにユーザーのディレクトリが作成されます。

パターンを使用して、同じディレクトリで複数の個別のキャッシュを操作できます。デフォルトのパターンは'__jinja2_%s.cache'です。%sはキャッシュキーに置き換えられます。

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

このバイトコードキャッシュは、clearメソッドを使用してキャッシュのクリアをサポートしています。

パラメータ:

  • directory (str | None)

  • pattern (str)

class jinja2.MemcachedBytecodeCache(client, prefix='jinja2/bytecode/', timeout=None, ignore_memcache_errors=True)

このクラスは、情報を保存するためにmemcacheキャッシュを使用するバイトコードキャッシュを実装します。特定のmemcacheライブラリ（tummyのmemcacheやcmemcache）を強制するものではなく、必要な最小限のインターフェースを提供するクラスであればどれでも受け付けます。

このクラスと互換性のあるライブラリ

(残念ながら、Djangoのキャッシュインターフェースはバイナリデータではなくテキストしか保存できないため、互換性がありません。ただし、バイトコードキャッシュに渡すことができる基礎となるキャッシュクライアントは、django.core.cache.cache._clientとして利用可能です。)

コンストラクタに渡されるクライアントの最小限のインターフェースは次のとおりです。

パラメータ:

  • **client** (_MemcachedClient)

  • **prefix** (str)

  • **timeout** (int | None)

  • **ignore_memcache_errors** (bool)

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

バイトコードをキャッシュに保存します。valueは文字列であり、timeoutはキーのタイムアウトです。タイムアウトが指定されていない場合は、デフォルトのタイムアウトまたはタイムアウトなしとみなされます。指定されている場合は、キャッシュアイテムが存在する秒数を表す整数です。

get(key)

キャッシュキーの値を返します。アイテムがキャッシュに存在しない場合、戻り値はNoneでなければなりません。

コンストラクタへの他の引数は、実際のキャッシュキーの前に追加されるすべてのキーのプレフィックスと、キャッシュシステム内のバイトコードのタイムアウトです。高い（またはなし）タイムアウトを推奨します。

このバイトコードキャッシュは、キャッシュ内で使用済みのアイテムのクリアをサポートしていません。clearメソッドは、何もしない関数です。

変更履歴

バージョン 2.7 で追加: ignore_memcache_errorsパラメータを使用して、memcacheエラーの無視をサポートしました。

非同期サポート

変更履歴

バージョン2.9で追加されました。

JinjaはPythonのasyncおよびawait構文をサポートしています。テンプレートデザイナーにとって、このサポート（有効になっている場合）は完全に透過的であり、テンプレートはまったく同じように見えます。ただし、開発者は、非同期APIと同期APIの両方を処理するために、実装方法を理解する必要があります。

デフォルトでは、非同期サポートは無効になっています。有効にすると、asyncioイベントループで非同期コードと同期コードを処理するために、環境は異なるコードをコンパイルします。これには、次の影響があります。

  • コンパイルされたコードは、関数と属性にawaitを使用し、async forループを使用します。このコンテキストで非同期関数と同期関数の両方の使用をサポートするために、すべての呼び出しとアクセスには小さなラッパーが配置され、純粋に非同期コードと比較してオーバーヘッドが増加します。

  • 必要に応じて、同期メソッドとフィルターは対応する非同期実装のラッパーになります。たとえば、renderはasync_renderを呼び出し、|mapは非同期イテラブルをサポートします。

待機可能なオブジェクトは、テンプレート内の関数から返され、テンプレート内の関数呼び出しはすべて自動的に結果を待機します。通常Pythonで追加するawaitは暗黙的に含まれます。たとえば、データベースから非同期的にデータを読み込むメソッドを提供でき、テンプレートデザイナーの観点からは、他の関数と同様に呼び出すことができます。

ポリシー

Jinja 2.9以降、環境でポリシーを設定できるようになり、フィルターやその他のテンプレート構造の動作にわずかな影響を与えることができます。policies属性で設定できます。

例

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

truncateフィルターの許容範囲のデフォルトを設定します。許容範囲は2.9で導入されましたが、古いテンプレートとの互換性を復元するために、古い動作を復元するために0に設定できます。デフォルトは5です。

urlize.rel:

urlizeフィルターで生成されたリンクのrel属性の項目を定義する文字列です。これらの項目は常に追加されます。デフォルトはnoopenerです。

urlize.target:

呼び出しで他のターゲットが明示的に定義されていない場合、urlizeフィルターからのリンクに発行されるデフォルトのターゲットです。

urlize.extra_schemes:

デフォルトのhttp://、https://、およびmailto:に加えて、これらのスキームで始まるURLを認識します。

json.dumps_function:

これがNone以外の値に設定されている場合、tojsonフィルターはデフォルトのものではなく、この関数を使用してダンプします。この関数は、将来フィルターから渡される可能性のある任意の追加の引数を受け入れる必要があることに注意してください。現在、渡される可能性のある引数はindentだけです。デフォルトのダンプ関数はjson.dumpsです。

json.dumps_kwargs:

ダンプ関数に渡されるキーワード引数です。デフォルトは{'sort_keys': True}です。

ext.i18n.trimmed:

これがTrueに設定されている場合、i18n Extensionの{% trans %}ブロックは、trimmed修飾子が使用されているかのように、常に改行と周囲の空白を統一します。

ユーティリティ

これらのヘルパー関数とクラスは、Jinja環境にカスタムフィルターまたは関数を追加する場合に役立ちます。

jinja2.pass_context(f)

テンプレートのレンダリング中に呼び出された場合、デコレートされた関数に最初の引数としてContextを渡します。

関数、フィルター、およびテストで使用できます。

Context.eval_contextのみが必要な場合は、pass_eval_context()を使用します。Context.environmentのみが必要な場合は、pass_environment()を使用します。

変更履歴

バージョン 3.0.0 で追加: contextfunctionとcontextfilterに取って代わります。

パラメータ:

**f** (F)

戻り値:

F

jinja2.pass_eval_context(f)

テンプレートのレンダリング中に呼び出された場合、デコレートされた関数に最初の引数としてEvalContextを渡します。評価コンテキストを参照してください。

関数、フィルター、およびテストで使用できます。

EvalContext.environmentのみが必要な場合は、pass_environment()を使用します。

変更履歴

バージョン 3.0.0 で追加: evalcontextfunctionとevalcontextfilterに取って代わります。

パラメータ:

**f** (F)

戻り値:

F

jinja2.pass_environment(f)

テンプレートのレンダリング中に呼び出された場合、デコレートされた関数に最初の引数としてEnvironmentを渡します。

関数、フィルター、およびテストで使用できます。

変更履歴

バージョン 3.0.0 で追加: environmentfunction と environmentfilter を置き換えます。

パラメータ:

**f** (F)

戻り値:

F

jinja2.clear_caches()

Jinja は、環境とレキサーのために内部キャッシュを保持します。これらは、Jinja が環境とレキサーを常に再作成する必要がないようにするために使用されます。通常、気に掛ける必要はありませんが、メモリ消費量を測定している場合は、キャッシュをクリアする必要があるかもしれません。

戻り値:

None

jinja2.is_undefined(obj)

渡されたオブジェクトが未定義かどうかを確認します。これは Undefined に対するインスタンスチェックを実行する以上のことは行いませんが、より見栄えが良くなります。これは、未定義の変数に反応したいカスタムフィルターまたはテストに使用できます。たとえば、カスタムのデフォルトフィルターは次のようになります。

def default(var, default=''):
    if is_undefined(var):
        return default
    return var
パラメータ:

obj (Any)

戻り値:

bool

例外

exception jinja2.TemplateError(message=None)

すべてのテンプレートエラーの基本クラスです。

パラメータ:

**message** (str | None)

戻り値:

None

exception jinja2.UndefinedError(message=None)

テンプレートが Undefined で操作しようとすると発生します。

パラメータ:

**message** (str | None)

戻り値:

None

exception jinja2.TemplateNotFound(name, message=None)

テンプレートが存在しない場合に発生します。

変更履歴

バージョン 2.11 で変更: 指定された名前が Undefined であり、メッセージが提供されていない場合、UndefinedError が発生します。

パラメータ:
戻り値:

None

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

TemplateNotFound と似ていますが、複数のテンプレートが選択されている場合に発生します。これは TemplateNotFound 例外のサブクラスであるため、基本例外のみをキャッチすれば、両方をキャッチできます。

変更履歴

バージョン 2.11 で変更: 名前のリスト内の名前が Undefined の場合、空文字列ではなく、未定義であることを示すメッセージが表示されます。

バージョン 2.2 で追加。

パラメータ:
戻り値:

None

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

ユーザーにテンプレートに問題があることを伝えるために発生します。

パラメータ:

  • **message** (str)

  • **lineno** (int)

  • name (str | None)

  • **filename** (str | None)

戻り値:

None

message

エラーメッセージ。

lineno

エラーが発生した行番号。

name

テンプレートのロード名。

filename

ファイルシステムのエンコーディングでテンプレートをロードしたファイル名（ほとんどの場合 utf-8、または Windows システムでは mbcs）。

exception jinja2.TemplateRuntimeError(message=None)

テンプレートエンジンにおける一般的なランタイムエラー。状況によっては、Jinja がこの例外を発生させる可能性があります。

パラメータ:

**message** (str | None)

戻り値:

None

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

テンプレート構文エラーに似ていますが、コンパイル時にテンプレート内の何かがエラーを引き起こした（構文エラーによって必ずしも引き起こされたわけではない）場合をカバーしています。ただし、TemplateSyntaxError の直接的なサブクラスであり、同じ属性を持っています。

パラメータ:

  • **message** (str)

  • **lineno** (int)

  • name (str | None)

  • **filename** (str | None)

戻り値:

None

カスタムフィルター

フィルターは、フィルターの左側の値を最初の引数として受け取り、新しい値を生成する Python 関数です。フィルターに渡される引数は、値の後に渡されます。

たとえば、フィルター {{ 42|myfilter(23) }} は、内部的に myfilter(42, 23) として呼び出されます。

Jinja には、いくつかの 組み込みフィルター が付属しています。カスタムフィルターを使用するには、少なくとも value 引数を受け取る関数を作成し、Environment.filters に登録します。

datetime オブジェクトをフォーマットするフィルターを次に示します。

def datetime_format(value, format="%H:%M %d-%m-%y"):
    return value.strftime(format)

environment.filters["datetime_format"] = datetime_format

これで、テンプレートで使用できます。

{{ article.pub_date|datetimeformat }}
{{ article.pub_date|datetimeformat("%B %Y") }}

Jinja にフィルターに追加情報を渡すように指示するいくつかのデコレーターが用意されています。オブジェクトは最初の引数として渡され、フィルタリングされる値は2番目の引数になります。

改行をHTMLの<br>および<p>タグに変換するフィルターを次に示します。これは、入力のエスケープと出力の安全なマークを行う前に、自動エスケープが現在有効になっているかどうかを確認するために、評価コンテキストを使用します。

import re
from jinja2 import pass_eval_context
from markupsafe import Markup, escape

@pass_eval_context
def nl2br(eval_ctx, value):
    br = "<br>\n"

    if eval_ctx.autoescape:
        value = escape(value)
        br = Markup(br)

    result = "\n\n".join(
        f"<p>{br.join(p.splitlines())}<\p>"
        for p in re.split(r"(?:\r\n|\r(?!\n)|\n){2,}", value)
    )
    return Markup(result) if autoescape else result

カスタムテスト

テストは、テストの左側の値を最初の引数として受け取り、TrueまたはFalseを返すPython関数です。テストに渡される引数は、値の後に渡されます。

たとえば、テスト{{ 42 is even }}は、内部的にis_even(42)として呼び出されます。

Jinjaにはいくつかの組み込みテストが付属しています。カスタムテストを使用するには、少なくともvalue引数を受け取る関数を作成し、Environment.testsに登録します。

値が素数かどうかをチェックするテストを次に示します。

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

environment.tests["prime"] = is_prime

これで、テンプレートで使用できます。

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

Jinja にテストに追加情報を渡すように指示するいくつかのデコレーターが用意されています。オブジェクトは最初の引数として渡され、テストされる値は2番目の引数になります。

評価コンテキスト

評価コンテキスト（略して eval コンテキストまたは eval ctx）により、コンパイル済みの機能をランタイムで有効化および無効化することができます。

現在、これは自動エスケープの有効化と無効化のみに使用されていますが、拡張機能でも使用できます。

autoescapeの設定は、環境ではなく、評価コンテキストで確認する必要があります。評価コンテキストには、現在のテンプレートの計算済み値が保持されます。

pass_environmentの代わりに

@pass_environment
def filter(env, value):
    result = do_something(value)

    if env.autoescape:
        result = Markup(result)

    return result

設定のみが必要な場合は、pass_eval_contextを使用してください。

@pass_eval_context
def filter(eval_ctx, value):
    result = do_something(value)

    if eval_ctx.autoescape:
        result = Markup(result)

    return result

他のコンテキストの動作も必要であれば、pass_contextを使用してください。

@pass_context
def filter(context, value):
    result = do_something(value)

    if context.eval_ctx.autoescape:
        result = Markup(result)

    return result

評価コンテキストは実行時に変更してはなりません。変更は、評価コンテキストオブジェクト自体ではなく、拡張機能からのnodes.EvalContextModifierとnodes.ScopedEvalContextModifierを使用してのみ行う必要があります。

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

評価時の情報を保持します。拡張機能でカスタム属性を付加できます。

パラメータ:
autoescape

自動エスケープが有効かどうかを示すTrueまたはFalse。

volatile

コンパイラがコンパイル時に一部の式を評価できない場合にTrue。実行時では常にFalseである必要があります。

グローバル名前空間

グローバル名前空間は、Template.render()に渡す必要なく使用できる変数と関数を格納します。コンテキストなしでインポートまたはインクルードされたテンプレートからも使用できます。ほとんどのアプリケーションでは、Environment.globalsのみを使用する必要があります。

Environment.globalsは、その環境によってロードされたすべてのテンプレートで共通のデータ向けです。Template.globalsはそのテンプレートのすべてのレンダリングで共通のデータ向けであり、Environment.get_template()などで指定しない限りEnvironment.globalsをデフォルト値として使用します。レンダリング固有のデータは、Template.render()にコンテキストとして渡す必要があります。

特定のレンダリング時には、グローバル変数のセットは1つのみ使用されます。テンプレートAとBの両方にテンプレートグローバル変数があり、BがAを拡張する場合、b.render()を使用すると、両方でBのグローバル変数のみが使用されます。

環境グローバル変数は、テンプレートのロード後には変更しないでください。テンプレートグローバル変数は、テンプレートのロード後には変更しないでください。テンプレートのロード後にグローバル変数を変更すると、環境や他のテンプレートと共有されている可能性があるため、予期しない動作が発生します。

低レベルAPI

低レベルAPIは、実装の詳細、デバッグ目的、または高度な拡張機能テクニックを理解するのに役立つ機能を提供します。何が起こっているのか正確に理解していない限り、これらのAPIの使用はお勧めしません。

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

指定されたソースコードを字句解析し、(lineno, token_type, value)という形式のタプルとしてトークンを生成するジェネレータを返します。拡張機能の開発やテンプレートのデバッグに役立ちます。

これは前処理を実行しません。拡張機能の前処理を適用する場合は、ソースをpreprocess()メソッドでフィルタリングする必要があります。

パラメータ:

  • source (str)

  • name (str | None)

  • **filename** (str | None)

戻り値:

Iterator[Tuple[int, str, str]]

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

ソースコードを解析し、抽象構文木を返します。このノードツリーは、コンパイラによってテンプレートを実行可能なソースコードまたはバイトコードに変換するために使用されます。これは、デバッグやテンプレートからの情報の抽出に役立ちます。

Jinja拡張機能を開発している場合、これにより生成されるノードツリーの概要を把握できます。

パラメータ:

  • source (str)

  • name (str | None)

  • **filename** (str | None)

戻り値:

Template

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

すべての拡張機能を使用してソースを前処理します。これは、すべての解析およびコンパイルメソッドに対して自動的に呼び出されますが、lex()に対しては呼び出されません。通常、lex()では実際のソースのトークン化のみが必要だからです。

パラメータ:

  • source (str)

  • name (str | None)

  • **filename** (str | None)

戻り値:

str

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

このテンプレートの新しいContextを作成します。提供されたvarsはテンプレートに渡されます。デフォルトでは、グローバル変数はコンテキストに追加されます。sharedをTrueに設定すると、グローバル変数を追加せずに、データがそのままコンテキストに渡されます。

localsは、内部使用のためのローカル変数の辞書です。

パラメータ:
戻り値:

コンテキスト

Template.root_render_func(context)

これは低レベルのレンダリング関数です。これは、同じテンプレートまたは互換性のあるテンプレートのnew_context()によって作成する必要があるContextが渡されます。このレンダリング関数は、テンプレートコードからコンパイラによって生成され、文字列を生成するジェネレータを返します。

テンプレートコード内で例外が発生した場合、テンプレートエンジンは例外を書き換えず、元の例外をそのまま渡します。実際、この関数はrender() / generate() / stream() の呼び出し内からのみ呼び出す必要があります。

Template.blocks

ブロックレンダリング関数の辞書です。これらの関数はそれぞれ、同じ制限を持つroot_render_func()と全く同じように動作します。

Template.is_up_to_date

この属性は、テンプレートの新しいバージョンが存在する場合はFalse、存在しない場合はTrueになります。

注記

低レベルAPIは脆弱です。将来のJinjaバージョンでは、後方互換性を損なう変更を加えないようにしますが、Jinjaコアの変更が反映される可能性があります。たとえば、Jinjaで新しいASTノードが導入された場合、parse()によって返される可能性があります。

メタAPI

変更履歴

バージョン 2.2 で追加。

メタAPIは、抽象構文ツリーに関する情報を返し、アプリケーションがより高度なテンプレート概念を実装するのに役立ちます。メタAPIのすべての関数は、Environment.parse()メソッドによって返される抽象構文ツリーを操作します。

jinja2.meta.find_undeclared_variables(ast)

実行時にコンテキストから参照されるAST内のすべての変数の集合を返します。コンパイル時には実行パスに応じてどの変数が使用されるかが不明なため、すべての変数が返されます。

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

実装

内部的には、未宣言変数の検索にコードジェネレーターが使用されます。これは重要な情報です。コードジェネレーターはコンパイル時にTemplateAssertionErrorを発生させる可能性があり、実際、この関数は現在でもその例外を発生させる可能性があります。

パラメータ:

**ast** (Template)

戻り値:

Set[str]

jinja2.meta.find_referenced_templates(ast)

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]

この関数は、依存関係の追跡に役立ちます。たとえば、レイアウトテンプレートが変更された後にWebサイトの一部を再構築する場合などです。

パラメータ:

**ast** (Template)

戻り値:

Iterator[str | None]