API —Jinjaドキュメント
API
このドキュメントでは、テンプレート言語ではなく、JinjaへのAPIについて説明します(これについては、 Template Designerのドキュメントを参照してください)。 これは、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パッケージ内(またはyourapp.py
Pythonモジュールの隣)のtemplates
フォルダーでテンプレートを検索するローダーを備えたテンプレート環境が作成されます。 また、HTMLファイルの自動エスケープも有効にします。 このローダーは、yourapp
がインポート可能である必要があるだけで、フォルダーへの絶対パスを計算します。
他の方法または他の場所からテンプレートをロードするために、さまざまなローダーを使用できます。 それらは、以下のローダーセクションにリストされています。 プロジェクトに特化したソースからテンプレートをロードする場合は、独自に作成することもできます。
この環境からテンプレートをロードするには、get_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のコアコンポーネントは環境です。 これには、構成、フィルター、テスト、グローバルなどの重要な共有変数が含まれています。 このクラスのインスタンスは、共有されておらず、これまでにテンプレートがロードされていない場合に変更される可能性があります。 最初のテンプレートがロードされた後の環境の変更は、驚くべき効果と未定義の動作につながります。
可能な初期化パラメータは次のとおりです。
- 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の新機能。
- 拡張機能
使用するJinja拡張機能のリスト。 これは、文字列または拡張クラスとしてのインポートパスのいずれかです。 詳細については、拡張機能のドキュメントをご覧ください。
- 最適化
オプティマイザーを有効にする必要がありますか? デフォルトは
True
です。- 未定義
Undefined またはそのサブクラス。テンプレート内の未定義の値を表すために使用されます。
- ファイナライズ
変数式の結果を出力前に処理するために使用できる呼び出し可能オブジェクト。 たとえば、ここで
None
を暗黙的に空の文字列に変換できます。- 自動エスケープ
True
に設定すると、XML / HTML自動エスケープ機能がデフォルトで有効になります。 自動エスケープの詳細については、Markup
を参照してください。 Jinja 2.4以降、これはテンプレート名が渡される呼び出し可能オブジェクトである可能性があり、自動エスケープに応じてTrue
またはFalse
を返す必要があります。デフォルトで有効になっている必要があります。バージョン2.4で変更: autoescape を関数にできるようになりました
- ローダ
この環境のテンプレートローダー。
- cache_size
キャッシュのサイズ。 デフォルトでは、これは
400
です。これは、400を超えるテンプレートがロードされた場合、ローダーが最も使用頻度の低いテンプレートをクリーンアップすることを意味します。 キャッシュサイズが0
に設定されている場合、テンプレートは常に再コンパイルされます。キャッシュサイズが-1
の場合、キャッシュはクリーンアップされません。バージョン2.8で変更:キャッシュサイズが50から400に増加しました。
- auto_reload
一部のローダーは、テンプレートソースが変更される可能性のある場所(ファイルシステムまたはデータベースなど)からテンプレートをロードします。
auto_reload
がTrue
(デフォルト)に設定されている場合、テンプレートが要求されるたびに、ローダーはソースが変更されたかどうかを確認し、変更された場合はテンプレートを再読み込みします。 より高いパフォーマンスのために、それを無効にすることが可能です。- bytecode_cache
バイトコードキャッシュオブジェクトに設定されている場合、このオブジェクトは内部Jinjaバイトコードのキャッシュを提供するため、テンプレートが変更されていない場合に解析する必要はありません。
詳細については、バイトコードキャッシュを参照してください。
- enable_async
trueに設定すると、非同期テンプレートの実行が有効になり、非同期関数とジェネレーターを使用できるようになります。
- パラメーター
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 (オプション [ str ] )–
line_comment_prefix (オプション [ str ] )–
trim_blocks ( bool )–
lstrip_blocks ( bool )–
'newline_sequence ( te.Literal [ \ n 、 [X94X ] \ r \ n 、 \ r ] )–
keep_trailing_newline ( bool )–
拡張機能(シーケンス [ ユニオン [ str 、 タイプ [ 拡張機能 ] ] ] )–
最適化( bool )–
undefined ( Type [ jinja2.runtime.Undefined ] )–
finalize (オプション [ 呼び出し可能 [ [ ... [ X90X] ] 、 Any ] ] )–
autoescape ( Union [ bool 、 Callable [ [ オプション [ str ] ] 、 [ X184X] bool ] ] )–
ローダー(オプション [ BaseLoader ] )–
cache_size ( int )–
auto_reload ( bool )–
bytecode_cache (オプション [ BytecodeCache ] )–
enable_async ( bool )–
- shared
Template コンストラクターを使用してテンプレートが作成された場合、環境は自動的に作成されます。 これらの環境は共有環境として作成されます。つまり、複数のテンプレートが同じ匿名環境を持つ場合があります。 すべての共有環境で、この属性は True 、それ以外の場合は False です。
- sandboxed
環境がサンドボックス化されている場合、この属性は True です。 サンドボックスモードについては、 SandboxedEnvironment のドキュメントをご覧ください。
- filters
この環境のフィルターの辞書。 テンプレートがロードされていない限り、新しいフィルターを追加したり、古いフィルターを削除したりしても安全です。 カスタムフィルターについては、カスタムフィルターを参照してください。 有効なフィルター名については、識別子に関する注意事項を参照してください。
- tests
この環境のテスト機能の指示。 テンプレートがロードされていない限り、このdictを変更しても安全です。 カスタムテストについては、カスタムテストを参照してください。 有効なテスト名については、識別子に関する注意事項を参照してください。
- globals
環境によってロードされたすべてのテンプレートで使用可能な変数の辞書。 テンプレートがロードされていない限り、これを変更しても安全です。 詳細については、グローバル名前空間を参照してください。 有効なオブジェクト名については、識別子に関する注意事項を参照してください。
- policies
ポリシーの辞書。 これらを再構成して、ランタイムの動作や特定のテンプレート機能を変更できます。 通常、これらはセキュリティに関連しています。
- code_generator_class
コード生成に使用されるクラス。 テンプレートのコンパイル先のPythonコードを変更する必要がない限り、ほとんどの場合、これを変更しないでください。
- context_class
テンプレートに使用されるコンテキスト。 テンプレート変数の処理方法の内部を変更する必要がない限り、これはほとんどの場合変更しないでください。 詳細については、コンテキストを参照してください。
- overlay([options])
キャッシュとオーバーライドされた属性を除くすべてのデータを現在の環境と共有する新しいオーバーレイ環境を作成します。 オーバーレイ環境の拡張機能は削除できません。 オーバーレイされた環境は、リンク先の環境のすべての拡張機能に加えて、オプションの追加の拡張機能を自動的に取得します。
オーバーレイの作成は、初期環境が完全にセットアップされた後に行う必要があります。 すべての属性が実際にリンクされているわけではありません。一部はコピーされているだけなので、元の環境での変更が反映されない場合があります。
- パラメーター
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 (オプション [ str ] )–
line_comment_prefix (オプション [ str ] )–
trim_blocks ( bool )–
lstrip_blocks ( bool )–
拡張機能(シーケンス [ ユニオン [ str 、 タイプ [ 拡張機能 ] ] ] )–
最適化( bool )–
undefined ( Type [ jinja2.runtime.Undefined ] )–
finalize (オプション [ 呼び出し可能 [ [ ... [ X90X] ] 、 Any ] ] )–
autoescape ( Union [ bool 、 Callable [ [ オプション [ str ] ] 、 [ X184X] bool ] ] )–
ローダー(オプション [ BaseLoader ] )–
cache_size ( int )–
auto_reload ( bool )–
bytecode_cache (オプション [ BytecodeCache ] )–
- リターンタイプ
- undefined([hint, obj, name, exc])
name の新しい Undefined オブジェクトを作成します。 これは、一部の操作で未定義のオブジェクトを返す可能性のあるフィルターまたは関数に役立ちます。 ヒントを除くすべてのパラメーターは、読みやすくするためにキーワードパラメーターとして指定する必要があります。 ヒントは、提供されている場合は例外のエラーメッセージとして使用されます。指定されていない場合、エラーメッセージは obj および name から自動的に生成されます。 exc として提供される例外は、生成された未定義オブジェクトで、未定義オブジェクトが許可しない処理が実行された場合に発生します。 デフォルトの例外は UndefinedError です。 ヒントが指定されている場合、名前は省略できます。
未定義のオブジェクトを作成する最も一般的な方法は、名前のみを指定することです。
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 がわかっている場合(たとえば、属性がアクセスされたため)、カスタムヒントが既知であっても、未定義のオブジェクトに渡す必要があります。提供された。 これにより、未定義のオブジェクトがエラーメッセージを強調する可能性があります。
- add_extension(extension)
環境の作成後に拡張機能を追加します。
バージョン2.5の新機能。
- パラメーター
拡張機能(ユニオン [ str 、 タイプ [ 拡張機能 ] ] )–
- リターンタイプ
なし
- compile_expression(source, undefined_to_none=True)
式の変数として表示されるキーワード引数を受け入れるcallableを返す便利なヘルパーメソッド。 呼び出されると、式の結果を返します。
これは、アプリケーションがテンプレートの「構成ファイル」または同様の状況で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の新機能。
- パラメーター
ソース( str )–
undefined_to_none ( bool )–
- リターンタイプ
jinja2.environment.TemplateExpression
- compile_templates(target, extensions=None, filter_func=None, zip='deflated', log_function=None, ignore_errors=True)
ローダーが検索できるすべてのテンプレートを検索し、コンパイルして target に保存します。 zip が None の場合、zipファイルではなく、テンプレートがディレクトリに保存されます。 デフォルトでは、deflatezipアルゴリズムが使用されます。 保存されたアルゴリズムに切り替えるには、 zip を
'stored'
に設定できます。拡張機能および filter_func は list_templates()に渡されます。 返された各テンプレートは、ターゲットフォルダーまたはzipファイルにコンパイルされます。
デフォルトでは、テンプレートのコンパイルエラーは無視されます。 ログ機能が提供されている場合、エラーがログに記録されます。 テンプレート構文エラーでコンパイルを中止する場合は、 ignore_errors を False に設定すると、構文エラーで例外が発生します。
バージョン2.4の新機能。
- パラメーター
target ( Union [ str 、 os.PathLike ] [ X89X])–
拡張機能(オプション [ コレクション [ str ] ] )–
filter_func (オプション [ 呼び出し可能 [ [ str ] 、 bool ] ] )–
zip (オプション [ str ] )–
log_function (オプション [ 呼び出し可能 [ [ str ] 、 なし ] ] )–
ignore_errors ( bool )–
- リターンタイプ
なし
- extend(**attributes)
アイテムがまだ存在しない場合は、環境のインスタンスにアイテムを追加します。 これは extensions によって使用され、継承を壊すことなくコールバックと構成値を登録します。
- パラメーター
属性(任意)–
- リターンタイプ
なし
- from_string(source, globals=None, template_class=None)
loader
を使用せずにソース文字列からテンプレートをロードします。- パラメーター
ソース(ユニオン [ str 、 jinja2.nodes.Template ] )–テンプレートにコンパイルするためのJinjaソース。
グローバル(オプション [ マッピング [ str 、 Any ] ] )–このテンプレートのすべてのレンダリングで使用できるこれらの追加の変数を使用して、環境 globals を拡張します。 テンプレートがすでにロードおよびキャッシュされている場合、そのグローバルは新しいアイテムで更新されます。
template_class (オプション [ Type [ jinja2.environment.Template ] ] )–この Template クラスのインスタンスを返します。
- リターンタイプ
- get_or_select_template(template_name_or_list, parent=None, globals=None)
反復可能なテンプレート名が指定されている場合は select_template()を使用し、1つの名前が指定されている場合は get_template()を使用します。
バージョン2.3の新機能。
- パラメーター
template_name_or_list ( Union [ str 、 jinja2.environment.Template 、 List [ Union [ str 、 jinja2 .environment.Template ] ] ] )–
親(オプション [ str ] )–
グローバル(オプション [ マッピング [ str 、 任意 ] ] )–
- リターンタイプ
- get_template(name, parent=None, globals=None)
loader
を使用して名前でテンプレートをロードし、 Template を返します。 テンプレートが存在しない場合、 TemplateNotFound 例外が発生します。- パラメーター
名前(ユニオン [ str 、 jinja2.environment.Template ] )–ロードするテンプレートの名前。
親(オプション [ str ] )–このテンプレートをインポートする親テンプレートの名前。 join_path()を使用して、これを使用して名前変換を実装できます。
グローバル(オプション [ マッピング [ str 、 Any ] ] )–このテンプレートのすべてのレンダリングで使用できるこれらの追加の変数を使用して、環境 globals を拡張します。 テンプレートがすでにロードおよびキャッシュされている場合、そのグローバルは新しいアイテムで更新されます。
- リターンタイプ
バージョン3.0で変更:テンプレートがキャッシュからロードされると、
globals
は新しい値を無視するのではなく、テンプレートのグローバルを更新します。バージョン2.4で変更:
name
が Template オブジェクトの場合、変更されずに返されます。
- join_path(template, parent)
親と一緒にテンプレートを結合します。 デフォルトでは、すべてのルックアップはローダールートに相対的であるため、このメソッドは template パラメーターを変更せずに返しますが、パスが親テンプレートに相対的である必要がある場合は、この関数を使用して実際のテンプレート名を計算できます。
サブクラスはこのメソッドをオーバーライドし、ここで結合するテンプレートパスを実装できます。
- パラメーター
テンプレート( str )–
親( str )–
- リターンタイプ
str
- list_templates(extensions=None, filter_func=None)
この環境のテンプレートのリストを返します。 これには、ローダーがローダーの
list_templates()
メソッドをサポートしている必要があります。テンプレートフォルダに実際のテンプレート以外のファイルがある場合は、返されるリストをフィルタリングできます。 2つの方法があります。 extensions をテンプレートのファイル拡張子のリストに設定するか、 filter_func を提供できます。これは、テンプレート名が渡され、[を返す必要がある呼び出し可能オブジェクトです。結果リストに表示される場合は、X209X] True 。
ローダーがそれをサポートしていない場合、
TypeError
が発生します。バージョン2.4の新機能。
- パラメーター
拡張機能(オプション [ コレクション [ str ] ] )–
filter_func (オプション [ 呼び出し可能 [ [ str ] 、 bool ] ] )–
- リターンタイプ
リスト[str]
- select_template(names, parent=None, globals=None)
get_template()と同様ですが、複数の名前を読み込もうとします。 どの名前もロードできない場合、 TemplatesNotFound 例外が発生します。
- パラメーター
名前( Iterable [ Union [ str 、 jinja2.environment.Template ] ] )–順番にロードを試みるテンプレート名のリスト。
親(オプション [ str ] )–このテンプレートをインポートする親テンプレートの名前。 join_path()を使用して、これを使用して名前変換を実装できます。
グローバル(オプション [ マッピング [ str 、 Any ] ] )–このテンプレートのすべてのレンダリングで使用できるこれらの追加の変数を使用して、環境 globals を拡張します。 テンプレートがすでにロードおよびキャッシュされている場合、そのグローバルは新しいアイテムで更新されます。
- リターンタイプ
バージョン3.0で変更:テンプレートがキャッシュからロードされると、
globals
は新しい値を無視するのではなく、テンプレートのグローバルを更新します。バージョン2.11で変更:
names
が Undefined の場合、代わりに UndefinedError が発生します。 テンプレートが見つからず、names
に Undefined が含まれている場合、メッセージはさらに役立ちます。バージョン2.4で変更:
names
に Template オブジェクトが含まれている場合、変更されずに返されます。バージョン2.3の新機能。
- class jinja2.Template(source, block_start_string='{%', block_end_string='%}', variable_start_string='{{', variable_end_string='}}', comment_start_string='{#', comment_end_string='#}', line_statement_prefix=None, line_comment_prefix=None, trim_blocks=False, lstrip_blocks=False, newline_sequence='\n', keep_trailing_newline=False, extensions=(), optimized=True, undefined=<class 'jinja2.runtime.Undefined'>, finalize=None, autoescape=False, enable_async=False)
中央のテンプレートオブジェクト。 このクラスはコンパイルされたテンプレートを表し、それを評価するために使用されます。
通常、テンプレートオブジェクトは Environment から生成されますが、コンストラクターを使用して直接テンプレートインスタンスを作成できるようにするコンストラクターもあります。 環境コンストラクターと同じ引数を取りますが、ローダーを指定することはできません。
すべてのテンプレートオブジェクトには、存在が保証されているいくつかのメソッドとメンバーがあります。 ただし、テンプレートオブジェクトは不変であると見なすことが重要です。 オブジェクトの変更はサポートされていません。
環境ではなくコンストラクターから作成されたテンプレートオブジェクトには、コンストラクターと互換性のある設定で作成された他のテンプレートとおそらく共有される一時的な環境を指す environment 属性があります。
>>> template = Template('Hello {{ name }}!') >>> template.render(name='John Doe') == u'Hello John Doe!' True >>> stream = template.stream(name='John Doe') >>> next(stream) == u'Hello John Doe!' True >>> next(stream) Traceback (most recent call last): ... StopIteration
- パラメーター
ソース(ユニオン [ 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 (オプション [ str ] )–
line_comment_prefix (オプション [ str ] )–
trim_blocks ( bool )–
lstrip_blocks ( bool )–
'newline_sequence ( te.Literal [ \ n 、 [X94X ] \ r \ n 、 \ r ] )–
keep_trailing_newline ( bool )–
拡張機能(シーケンス [ ユニオン [ str 、 タイプ [ 拡張機能 ] ] ] )–
最適化( bool )–
undefined ( Type [ jinja2.runtime.Undefined ] )–
finalize (オプション [ 呼び出し可能 [ [ ... [ X90X] ] 、 Any ] ] )–
autoescape ( Union [ bool 、 Callable [ [ オプション [ str ] ] 、 [ X184X] bool ] ] )–
enable_async ( bool )–
- リターンタイプ
どれでも
- globals
テンプレートをレンダリングするたびに使用できる変数の辞書。レンダリング中に変数を渡す必要はありません。 テンプレートのロード方法によっては、環境や他のテンプレートと共有される可能性があるため、これは変更しないでください。
追加の値が Environment.get_template()に渡されない限り、デフォルトは Environment.globals です。
グローバルは、テンプレートのすべてのレンダリングに共通のデータのみを対象としています。 特定のデータを render()に渡す必要があります。
グローバル名前空間を参照してください。
- name
テンプレートのロード名。 テンプレートが文字列からロードされた場合、これは None です。
- filename
そこからロードされた場合のファイルシステム上のテンプレートのファイル名。 それ以外の場合、これはなしです。
- render([context])
このメソッドは、 dict コンストラクターと同じ引数(dict、dictサブクラス、またはいくつかのキーワード引数)を受け入れます。 引数が指定されていない場合、コンテキストは空になります。 これらの2つの呼び出しは同じことを行います。
template.render(knights='that say nih') template.render({'knights': 'that say nih'})
これにより、レンダリングされたテンプレートが文字列として返されます。
- パラメーター
args ( Any )–
kwargs ( Any )–
- リターンタイプ
str
- generate([context])
非常に大きなテンプレートの場合、テンプレート全体を一度にレンダリングするのではなく、各ステートメントを次々に評価して、ピースごとに生成すると便利な場合があります。 このメソッドは基本的にそれを正確に実行し、文字列として次々にアイテムを生成するジェネレーターを返します。
render()と同じ引数を受け入れます。
- パラメーター
args ( Any )–
kwargs ( Any )–
- リターンタイプ
イテレータ[str]
- stream([context])
generate()とまったく同じように機能しますが、
TemplateStream
を返します。- パラメーター
args ( Any )–
kwargs ( Any )–
- リターンタイプ
- async render_async([context])
これは render()と同様に機能しますが、待機するとレンダリングされたテンプレート文字列全体を返すコルーチンを返します。 これには、非同期機能を有効にする必要があります。
使用例:
await template.render_async(knights='that say nih; asynchronously')
- パラメーター
args ( Any )–
kwargs ( Any )–
- リターンタイプ
str
- generate_async([context])
generate()の非同期バージョン。 非常によく似た動作をしますが、代わりに非同期イテレータを返します。
- パラメーター
args ( Any )–
kwargs ( Any )–
- リターンタイプ
AsyncIterator [str]
- make_module(vars=None, shared=False, locals=None)
このメソッドは、引数なしで呼び出された場合、 module 属性のように機能しますが、テンプレートをキャッシュするのではなく、すべての呼び出しで評価します。 コンテキストとして使用されるdictを提供することも可能です。 引数は new_context()メソッドの場合と同じです。
- パラメーター
vars (オプション [ Dict [ str 、 任意 ] ] )–
共有( bool )–
ローカル(オプション [ マッピング [ str 、 任意 ] ] )–
- リターンタイプ
jinja2.environment.TemplateModule
- property module: jinja2.environment.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 (イテレータ [ str ] )–
- リターンタイプ
なし
- disable_buffering()
出力バッファリングを無効にします。
- リターンタイプ
なし
- dump(fp, encoding=None, errors='strict')
ストリーム全体をファイルまたはファイルのようなオブジェクトにダンプします。 デフォルトでは文字列が書き込まれます。書き込む前にエンコードする場合は、 encoding を指定してください。
使用例:
Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
- パラメーター
fp ( Union [ str 、 IO ] )–
エンコーディング(オプション [ str ] )–
エラー(オプション [ str ] )–
- リターンタイプ
なし
- enable_buffering(size=5)
バッファリングを有効にします。 サイズのアイテムを生成する前にバッファリングします。
- パラメーター
サイズ( int )–
- リターンタイプ
なし
自動エスケープ
バージョン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の新機能。
- パラメーター
enabled_extensions ( Collection [ str ] )–
disabled_extensions (コレクション [ str ] )–
default_for_string ( bool )–
デフォルト( bool )–
- リターンタイプ
Callable [[../Optional [str]]、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で受け入れられる文字の任意の組み合わせにすることができます。
フィルタとテストは別々の名前空間で検索され、識別子の構文がわずかに変更されています。 フィルタとテストには、フィルタとテストをトピックごとにグループ化するためのドットが含まれる場合があります。 たとえば、フィルターdictに関数を追加し、それを to.str と呼ぶことは完全に有効です。 フィルタおよびテスト識別子の正規表現は[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*`
です。
未定義のタイプ
これらのクラスは、未定義の型として使用できます。 Environment コンストラクターは、 undefined パラメーターを取ります。このパラメーターは、これらのクラスの1つ、または Undefined のカスタムサブクラスにすることができます。 テンプレートエンジンが名前を検索したり属性にアクセスしたりできない場合は常に、それらのオブジェクトの1つが作成されて返されます。 その後、未定義の値に対する一部の操作が許可され、その他の操作は失敗します。
通常の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
- パラメーター
ヒント(オプション [ str ] )–
obj ( Any )–
名前(オプション [ str ] )–
exc ( Type [ jinja2.exceptions.TemplateRuntimeError ] )–
- リターンタイプ
なし
- _undefined_hint
None または未定義オブジェクトのエラーメッセージを含む文字列。
- _undefined_obj
None または未定義オブジェクトの作成の原因となった所有者オブジェクト(たとえば、属性が存在しないため)。
- _undefined_name
未定義の変数/属性の名前、またはそのような情報が存在しない場合は None のみ。
- _undefined_exception
未定義のオブジェクトが発生させたい例外。 これは通常、 UndefinedError または
SecurityError
のいずれかです。
- _fail_with_undefined_error(\*args, \**kwargs)
このメソッドを引数を指定して呼び出すと、 _undefined_exception が発生し、未定義のオブジェクトに格納されている未定義のヒントからエラーメッセージが生成されます。
- class jinja2.ChainableUndefined
UndefinedError を発生させるのではなく、
__getattr__
と__getitem__
の両方が自身を返す、連鎖可能な未定義。>>> 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の新機能。
- パラメーター
ヒント(オプション [ str ] )–
obj ( Any )–
名前(オプション [ str ] )–
exc ( Type [ jinja2.exceptions.TemplateRuntimeError ] )–
- リターンタイプ
なし
- 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
- パラメーター
ヒント(オプション [ str ] )–
obj ( Any )–
名前(オプション [ str ] )–
exc ( Type [ jinja2.exceptions.TemplateRuntimeError ] )–
- リターンタイプ
なし
- 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
- パラメーター
ヒント(オプション [ str ] )–
obj ( Any )–
名前(オプション [ str ] )–
exc ( Type [ jinja2.exceptions.TemplateRuntimeError ] )–
- リターンタイプ
なし
未定義のオブジェクトを装飾して、失敗時のログを実装できるファクトリ関数もあります。
- jinja2.make_logging_undefined(logger=None, base=<class 'jinja2.runtime.Undefined'>)
ロガーオブジェクトが与えられると、これは特定の失敗をログに記録する新しい未定義のクラスを返します。 反復と印刷をログに記録します。 ロガーが指定されていない場合、デフォルトのロガーが作成されます。
例:
logger = logging.getLogger(__name__) LoggingUndefined = make_logging_undefined( logger=logger, base=Undefined )
バージョン2.8の新機能。
- パラメーター
ロガー(オプション [ logging.Logger ] )–使用するロガー。 指定しない場合、デフォルトのロガーが作成されます。
base ( Type [ jinja2.runtime.Undefined ] )–ロギング機能を追加する基本クラス。 これはデフォルトで Undefined になります。
- リターンタイプ
タイプ[ jinja2.runtime.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
テンプレートコンテキストは、テンプレートの変数を保持します。 テンプレートに渡された値と、テンプレートがエクスポートする名前も格納されます。 インスタンスの作成は、テンプレート評価のさまざまな段階で自動的に作成されるため、サポートも有用でもありません。手動で作成することはできません。
コンテキストは不変です。 親 の変更はが発生してはならず、 vars の変更は生成されたテンプレートコードからのみ許可されます。
pass_context()
としてマークされたテンプレートフィルターとグローバル関数は、最初の引数として渡されたアクティブコンテキストを取得し、読み取り専用のコンテキストへのアクセスを許可されます。テンプレートコンテキストは、読み取り専用のdict操作( get 、 keys 、 values 、 items 、 iterkeys 、[ X138X] itervalues 、 iteritems 、 __ getitem __ 、 __ contains __ )。 さらに、 resolve()メソッドがあります。このメソッドは KeyError で失敗しませんが、欠落している変数に対して Undefined オブジェクトを返します。
- パラメーター
- parent
テンプレートが検索する読み取り専用のグローバル変数の辞書。 これらは、別のコンテキスト、
Environment.globals
またはTemplate.globals
から取得するか、グローバルとレンダリング関数に渡される変数を組み合わせて作成されたdictを指します。 変更してはなりません。
- vars
テンプレートのローカル変数。 このリストには、 parent スコープの環境関数とコンテキスト関数、およびテンプレートからのローカル変更とエクスポートされた変数が含まれています。 テンプレートは、テンプレートの評価中にこのdictを変更しますが、フィルターとコンテキスト関数はそれを変更することを許可されていません。
- environment
テンプレートをロードした環境。
- exported_vars
このセットには、テンプレートがエクスポートするすべての名前が含まれています。 名前の値は、 vars 辞書にあります。 エクスポートされた変数のコピーをdictとして取得するには、 get_exported()を使用できます。
- name
このコンテキストを所有するテンプレートのロード名。
- blocks
テンプレート内のブロックの現在のマッピングを含むdict。 このdictのキーはブロックの名前であり、値は登録されたブロックのリストです。 各リストの最後の項目は、現在アクティブなブロック(継承チェーンの最新)です。
- eval_ctx
現在の評価コンテキスト。
- call(callable, \*args, \**kwargs)
提供された引数とキーワード引数を使用して呼び出し可能オブジェクトを呼び出しますが、呼び出し可能オブジェクトに
pass_context()
またはpass_environment()
がある場合は、最初の引数としてアクティブなコンテキストまたは環境を挿入します。- パラメーター
_Context__obj ( Callable )–
args ( Any )–
kwargs ( Any )–
- リターンタイプ
Union [Any、 jinja2.runtime.Undefined ]
- get(key, default=None)
名前で変数を検索するか、キーが見つからない場合はデフォルトを返します。
- パラメーター
key ( str )–検索する変数名。
default (オプション [ Any ] )–キーが見つからない場合に返される値。
- リターンタイプ
どれでも
- get_all()
エクスポートされた変数を含む完全なコンテキストをdictとして返します。 最適化の理由から、これは実際のコピーを返さない可能性があるため、使用には注意してください。
- リターンタイプ
Dict [str、Any]
- get_exported()
エクスポートされた変数を使用して新しいdictを取得します。
- リターンタイプ
Dict [str、Any]
- resolve(key)
名前で変数を検索するか、キーが見つからない場合は Undefined オブジェクトを返します。
カスタム動作を追加する必要がある場合は、このメソッドではなく、 resolve_or_missing()をオーバーライドしてください。 さまざまなルックアップ関数は、このメソッドではなく、そのメソッドを使用します。
- パラメーター
key ( str )–検索する変数名。
- リターンタイプ
Union [Any、 jinja2.runtime.Undefined ]
実装
Pythonのフレームローカルが関数内で不変であるのと同じ理由で、コンテキストは不変です。 JinjaとPythonはどちらも、コンテキスト/フレームローカルを変数のデータストレージとして使用せず、プライマリデータソースとしてのみ使用しています。
テンプレートがテンプレートで定義されていない変数にアクセスすると、Jinjaはコンテキストで変数を検索し、その後、変数はテンプレートで定義されているかのように扱われます。
ローダー
ローダーは、ファイルシステムなどのリソースからテンプレートをロードする役割を果たします。 環境は、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 エラーを発生させる必要があります。返されるタプルのソース部分は、文字列としてのテンプレートのソースである必要があります。 ファイル名は、ファイルシステムからロードされた場合はファイルシステム上のファイルの名前である必要があり、そうでない場合は
None
である必要があります。 ローダー拡張子が使用されていない場合、ファイル名はトレースバックのためにPythonによって使用されます。タプルの最後の項目は uptodate 関数です。 自動再読み込みが有効になっている場合は、テンプレートが変更されたかどうかを確認するために常に呼び出されます。 引数は渡されないため、関数は古い状態をどこかに(たとえばクロージャに)格納する必要があります。 False が返されると、テンプレートが再ロードされます。
- パラメーター
環境(環境)–
テンプレート( str )–
- リターンタイプ
タプル[str、オプション[str]、オプション[呼び出し可能[[]、bool]]]
- load(environment, name, globals=None)
テンプレートをロードします。 このメソッドは、キャッシュ内のテンプレートを検索するか、 get_source()を呼び出してテンプレートをロードします。 他のローダーのコレクションで動作するローダー( PrefixLoader や ChoiceLoader など)はこのメソッドを呼び出さず、 get_source を直接呼び出すため、サブクラスはこのメソッドをオーバーライドしないでください。
Jinjaが提供する組み込みローダーのリストは次のとおりです。
- class jinja2.FileSystemLoader(searchpath, encoding='utf-8', followlinks=False)
ファイルシステムのディレクトリからテンプレートをロードします。
パスは相対パスでも絶対パスでもかまいません。 相対パスは、現在の作業ディレクトリからの相対パスです。
loader = FileSystemLoader("templates")
パスのリストを指定できます。 ディレクトリは、最初に一致するテンプレートで停止して、順番に検索されます。
loader = FileSystemLoader(["/override/templates", "/default/templates"])
- パラメーター
searchpath ( Union [ str 、 os.PathLike 、[ X94X] シーケンス [ ユニオン [ str 、 os.PathLike ] ] ] )–テンプレートを含むディレクトリへのパスまたはパスのリスト。
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ファイル(あまり一般的ではない)としてインストールされたパッケージのみがサポートされます。 パッケージ内のデータをイントロスペクトするためのPythonAPIは、このローダーが必要とする方法で他のインストール方法をサポートするには制限が多すぎます。
PEP 420 名前空間パッケージのサポートは制限されています。 テンプレートディレクトリは、1人の名前空間寄稿者にのみ存在すると想定されています。 名前空間に寄与するZipファイルはサポートされていません。
バージョン3.0で変更:依存関係として
setuptools
を使用しなくなりました。バージョン3.0で変更: PEP420名前空間パッケージのサポートが制限されています。
- class jinja2.DictLoader(mapping)
テンプレート名をテンプレートソースにマッピングするPythondictからテンプレートをロードします。 このローダーは、ユニットテストに役立ちます。
>>> loader = DictLoader({'index.html': 'source here'})
自動リロードが役立つことはめったにないため、これはデフォルトで無効になっています。
- パラメーター
マッピング(マッピング [ 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 、 タプル [ X186X] [ str 、 オプション [ str ] [X282X ]、 オプション [ 呼び出し可能 [ [ ] 、 bool ] ] ] ] ] ] )–
- リターンタイプ
なし
- class jinja2.PrefixLoader(mapping, delimiter='/')
各ローダーがプレフィックスにバインドされているローダーのdictが渡されるローダー。 プレフィックスは、デフォルトごとにスラッシュでテンプレートから区切られます。スラッシュは、 delimiter 引数を別の引数に設定することで変更できます。
loader = PrefixLoader({ 'app1': PackageLoader('mypackage.app1'), 'app2': PackageLoader('mypackage.app2') })
'app1/index.html'
をロードすると、app1パッケージからファイルがロードされ、'app2/index.html'
をロードすると、2番目からファイルがロードされます。- パラメーター
マッピング(マッピング [ str 、 jinja2.loaders.BaseLoader ] )–
区切り文字( str )–
- リターンタイプ
なし
- class jinja2.ChoiceLoader(loaders)
このローダーは PrefixLoader のように機能しますが、プレフィックスが指定されていない点が異なります。 あるローダーでテンプレートが見つからなかった場合は、次のローダーが試行されます。
>>> loader = ChoiceLoader([ ... FileSystemLoader('/path/to/user/templates'), ... FileSystemLoader('/path/to/system/templates') ... ])
これは、ユーザーが別の場所から組み込みテンプレートをオーバーライドできるようにする場合に役立ちます。
- パラメーター
ローダー(シーケンス [ jinja2.loaders.BaseLoader ] )–
- リターンタイプ
なし
- class jinja2.ModuleLoader(path)
このローダーは、プリコンパイルされたテンプレートからテンプレートをロードします。
使用例:
>>> loader = ChoiceLoader([ ... ModuleLoader('/path/to/compiled/templates'), ... FileSystemLoader('/path/to/templates') ... ])
テンプレートは、 Environment.compile_templates()を使用してプリコンパイルできます。
- パラメーター
パス(ユニオン [ str 、 os.PathLike 、[ X88X] Sequence [ Union [ str 、 os.PathLike ] ] ] )–
- リターンタイプ
なし
バイトコードキャッシュ
Jinja 2.1以降は、外部バイトコードキャッシングをサポートしています。 バイトコードキャッシュを使用すると、生成されたバイトコードをファイルシステムまたは別の場所に保存して、最初の使用時にテンプレートが解析されないようにすることができます。
これは、最初のリクエストで初期化されるWebアプリケーションがあり、Jinjaが一度に多くのテンプレートをコンパイルしてアプリケーションの速度を低下させる場合に特に便利です。
バイトコードキャッシュを使用するには、それをインスタンス化して Environment に渡します。
- class jinja2.BytecodeCache
独自のバイトコードキャッシュを実装するには、このクラスをサブクラス化し、 load_bytecode()および dump_bytecode()をオーバーライドする必要があります。 これらのメソッドは両方ともバケットに渡されます。
ファイルシステムにバイトコードを保存する非常に基本的なバイトコードキャッシュ:
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の一部です。
- clear()
キャッシュをクリアします。 このメソッドはJinjaでは使用されませんが、アプリケーションが特定の環境で使用されているバイトコードキャッシュをクリアできるように実装する必要があります。
- リターンタイプ
なし
- dump_bytecode(bucket)
サブクラスは、バケットからキャッシュにバイトコードを書き戻すために、このメソッドをオーバーライドする必要があります。 それができない場合は、黙って失敗してはならず、例外を発生させてはなりません。
- パラメーター
バケット( jinja2.bccache.Bucket )–
- リターンタイプ
なし
- load_bytecode(bucket)
サブクラスは、バイトコードをバケットにロードするためにこのメソッドをオーバーライドする必要があります。 バケットのキャッシュでコードを見つけることができない場合は、何もしてはいけません。
- パラメーター
バケット( jinja2.bccache.Bucket )–
- リターンタイプ
なし
- class jinja2.bccache.Bucket(environment, key, checksum)
バケットは、1つのテンプレートのバイトコードを格納するために使用されます。 バイトコードキャッシュによって作成および初期化され、ロード関数に渡されます。
バケットは、割り当てられたキャッシュから内部チェックサムを取得し、これを使用して古いキャッシュマテリアルを自動的に拒否します。 個々のバイトコードキャッシュサブクラスは、キャッシュの無効化を気にする必要はありません。
- パラメーター
環境(環境)–
キー( str )–
チェックサム( str )–
- リターンタイプ
なし
- environment
バケットを作成した
Environment
。
- key
このバケットの一意のキャッシュキー
- code
ロードされている場合はバイトコード、それ以外の場合は None 。
- bytecode_from_string(string)
バイトからバイトコードをロードします。
- パラメーター
文字列(バイト)–
- リターンタイプ
なし
- bytecode_to_string()
バイトコードをバイトとして返します。
- リターンタイプ
バイト
- load_bytecode(f)
ファイルまたはオブジェクトのようなファイルからバイトコードをロードします。
- パラメーター
f ( BinaryIO )–
- リターンタイプ
なし
- reset()
バケットをリセットします(バイトコードをアンロードします)。
- リターンタイプ
なし
- write_bytecode(f)
渡されたオブジェクトのようなファイルまたはファイルにバイトコードをダンプします。
- パラメーター
f ( BinaryIO )–
- リターンタイプ
なし
組み込みのバイトコードキャッシュ:
- class jinja2.FileSystemBytecodeCache(directory=None, pattern='__jinja2_%s.cache')
ファイルシステムにバイトコードを格納するバイトコードキャッシュ。 キャッシュアイテムが保存されるディレクトリと、ファイル名の作成に使用されるパターン文字列の2つの引数を受け入れます。
ディレクトリが指定されていない場合は、デフォルトのキャッシュディレクトリが選択されます。 Windowsでは、ユーザーの一時ディレクトリが使用されます。UNIXシステムでは、システム一時ディレクトリにユーザー用のディレクトリが作成されます。
このパターンを使用して、複数の個別のキャッシュを同じディレクトリで動作させることができます。 デフォルトのパターンは
'__jinja2_%s.cache'
です。%s
はキャッシュキーに置き換えられます。>>> bcc = FileSystemBytecodeCache('/tmp/jinja_cache', '%s.cache')
このバイトコードキャッシュは、clearメソッドを使用したキャッシュのクリアをサポートします。
- パラメーター
ディレクトリ(オプション [ str ] )–
パターン( str )–
- リターンタイプ
なし
- class jinja2.MemcachedBytecodeCache(client, prefix='jinja2/bytecode/', timeout=None, ignore_memcache_errors=True)
このクラスは、情報を格納するためにmemcacheキャッシュを使用するバイトコードキャッシュを実装します。 特定のmemcacheライブラリ(おなかのmemcacheまたはcmemcache)を強制しませんが、必要な最小限のインターフェイスを提供するすべてのクラスを受け入れます。
このクラスと互換性のあるライブラリ:
(残念ながら、djangoキャッシュインターフェイスは、バイナリデータの保存をサポートしておらず、テキストのみをサポートしているため、互換性がありません。 ただし、基になるキャッシュクライアントを django.core.cache.cache._client として利用可能なバイトコードキャッシュに渡すことができます。)
コンストラクターに渡されるクライアントの最小インターフェースは次のとおりです。
- パラメーター
クライアント( _MemcachedClient )–
プレフィックス( str )–
タイムアウト(オプション [ int ] )–
ignore_memcache_errors ( bool )–
- class MinimalClientInterface
- set(key, value[, timeout])
バイトコードをキャッシュに保存します。 value は文字列で、 timeout はキーのタイムアウトです。 タイムアウトが指定されていない場合、デフォルトのタイムアウトが指定されていないか、タイムアウトが想定されていない場合、タイムアウトが指定されている場合は、キャッシュアイテムが存在する必要がある秒数の整数です。
- get(key)
キャッシュキーの値を返します。 アイテムがキャッシュに存在しない場合、戻り値は None である必要があります。
コンストラクターに対する他の引数は、実際のキャッシュキーの前に追加されるすべてのキーのプレフィックスと、キャッシュシステムのバイトコードのタイムアウトです。 タイムアウトを高くする(またはしない)ことをお勧めします。
このバイトコードキャッシュは、キャッシュ内の使用済みアイテムのクリアをサポートしていません。 クリアメソッドは無操作機能です。
バージョン2.7の新機能: ignore_memcache_errors パラメーターを介してmemcacheエラーを無視するためのサポートが追加されました。
非同期サポート
バージョン2.9の新機能。
Jinjaは、Python async
およびawait
構文をサポートしています。 テンプレートデザイナの場合、このサポート(有効になっている場合)は完全に透過的であり、テンプレートは引き続きまったく同じように見えます。 ただし、使用できるAPIのタイプに影響するため、開発者は実装に注意する必要があります。
デフォルトでは、非同期サポートは無効になっています。 これを有効にすると、asyncioイベントループで非同期コードと同期コードを処理するために、環境がバックグラウンドでさまざまなコードをコンパイルします。 これには、次の意味があります。
- テンプレートレンダリングでは、現在のスレッドでイベントループを使用できるようにする必要があります。
asyncio.get_running_loop()
はイベントループを返す必要があります。 - コンパイルされたコードは、関数と属性に
await
を使用し、async for
ループを使用します。 このコンテキストで非同期関数と同期関数の両方の使用をサポートするために、すべての呼び出しとアクセスの周りに小さなラッパーが配置されます。これにより、純粋な非同期コードと比較してオーバーヘッドが追加されます。 - 同期メソッドとフィルターは、必要に応じて、対応する非同期実装のラッパーになります。 たとえば、
render
はasync_render
を呼び出し、|map
は非同期イテラブルをサポートします。
待機可能なオブジェクトはテンプレート内の関数から返すことができ、テンプレート内の関数呼び出しは自動的に結果を待機します。 通常Pythonで追加するawait
が暗示されます。 たとえば、データベースからデータを非同期的にロードするメソッドを提供できます。テンプレートデザイナーの観点からは、他の関数と同じように呼び出すことができます。
ポリシー
Jinja 2.9以降、環境でポリシーを構成できます。これは、フィルターやその他のテンプレート構成の動作にわずかに影響を与える可能性があります。 これらは policies 属性で構成できます。
例:
env.policies['urlize.rel'] = 'nofollow noopener'
truncate.leeway
:- truncate フィルターの余裕のデフォルトを構成します。 Leewayは2.9で導入されましたが、古いテンプレートとの互換性を復元するために、 0 に構成して、古い動作を元に戻すことができます。 デフォルトは 5 です。
urlize.rel
:- urlize フィルターを使用して生成されたリンクの rel 属性の項目を定義する文字列。 これらのアイテムは常に追加されます。 デフォルトは noopener です。
urlize.target
:- 呼び出しによって他のターゲットが明示的に定義されていない場合に、 urlize フィルターからのリンクに対して発行されるデフォルトのターゲット。
urlize.extra_schemes
:- デフォルトの
http://
、https://
、およびmailto:
に加えて、これらのスキームで始まるURLを認識します。 json.dumps_function
:- これが None 以外の値に設定されている場合、 tojson フィルターは、デフォルトの関数ではなく、この関数でダンプします。 この関数は、将来フィルターから渡される可能性のある任意の追加引数を受け入れる必要があることに注意してください。 現在、渡される可能性のある唯一の引数はインデントです。 デフォルトのダンプ機能は
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 ( jinja2.utils.F )–
- リターンタイプ
jinja2.utils.F
- jinja2.pass_eval_context(f)
テンプレートのレンダリング中に呼び出されたときに、装飾された関数の最初の引数として EvalContext を渡します。 評価コンテキストを参照してください。
関数、フィルター、およびテストで使用できます。
EvalContext.environment
のみが必要な場合は、 pass_environment()を使用してください。バージョン3.0.0の新機能:
evalcontextfunction
およびevalcontextfilter
を置き換えます。- パラメーター
f ( jinja2.utils.F )–
- リターンタイプ
jinja2.utils.F
- jinja2.pass_environment(f)
テンプレートのレンダリング中に呼び出されたときに、装飾された関数の最初の引数として Environment を渡します。
関数、フィルター、およびテストで使用できます。
バージョン3.0.0の新機能:
environmentfunction
およびenvironmentfilter
を置き換えます。- パラメーター
f ( jinja2.utils.F )–
- リターンタイプ
jinja2.utils.F
- jinja2.contextfilter(f)
装飾された関数の最初の引数としてコンテキストを渡します。
バージョン3.0以降非推奨: Jinja3.1で削除されます。 代わりに pass_context()を使用してください。
- パラメーター
f ( jinja2.filters.F )–
- リターンタイプ
jinja2.filters.F
- jinja2.evalcontextfilter(f)
装飾された関数の最初の引数としてevalコンテキストを渡します。
バージョン3.0以降非推奨: Jinja3.1で削除されます。 代わりに pass_eval_context()を使用してください。
バージョン2.4の新機能。
- パラメーター
f ( jinja2.filters.F )–
- リターンタイプ
jinja2.filters.F
- jinja2.environmentfilter(f)
装飾された関数の最初の引数として環境を渡します。
バージョン3.0以降非推奨: Jinja3.1で削除されます。 代わりに pass_environment()を使用してください。
- パラメーター
f ( jinja2.filters.F )–
- リターンタイプ
jinja2.filters.F
- jinja2.contextfunction(f)
装飾された関数の最初の引数としてコンテキストを渡します。
バージョン3.0以降非推奨: Jinja3.1で削除されます。 代わりに pass_context()を使用してください。
- パラメーター
f ( jinja2.utils.F )–
- リターンタイプ
jinja2.utils.F
- jinja2.evalcontextfunction(f)
装飾された関数の最初の引数としてevalコンテキストを渡します。
バージョン3.0以降非推奨: Jinja3.1で削除されます。 代わりに pass_eval_context()を使用してください。
バージョン2.4の新機能。
- パラメーター
f ( jinja2.utils.F )–
- リターンタイプ
jinja2.utils.F
- jinja2.environmentfunction(f)
装飾された関数の最初の引数として環境を渡します。
バージョン3.0以降非推奨: Jinja3.1で削除されます。 代わりに pass_environment()を使用してください。
- パラメーター
f ( jinja2.utils.F )–
- リターンタイプ
jinja2.utils.F
- jinja2.clear_caches()
- Jinjaは、環境とレクサーの内部キャッシュを保持します。 これらは、Jinjaが環境やレクサーを常に再作成する必要がないようにするために使用されます。 通常はそれを気にする必要はありませんが、メモリ消費量を測定している場合は、キャッシュをクリーンアップすることをお勧めします。
- リターンタイプ
- なし
- jinja2.is_undefined(obj)
渡されたオブジェクトが未定義かどうかを確認してください。 これは、 Undefined に対してインスタンスチェックを実行するだけですが、見栄えが良くなります。 これは、未定義の変数に反応するカスタムフィルターまたはテストに使用できます。 たとえば、カスタムのデフォルトフィルタは次のようになります。
def default(var, default=''): if is_undefined(var): return default return var
- パラメーター
obj ( Any )–
- リターンタイプ
ブール
例外
- exception jinja2.TemplateError(message=None)
- すべてのテンプレートエラーのベースクラス。
- パラメーター
- メッセージ(オプション [ str ] )–
- リターンタイプ
- なし
- exception jinja2.UndefinedError(message=None)
- テンプレートが Undefined を操作しようとした場合に発生します。
- パラメーター
- メッセージ(オプション [ str ] )–
- リターンタイプ
- なし
- exception jinja2.TemplateNotFound(name, message=None)
テンプレートが存在しない場合に発生します。
バージョン2.11で変更:指定された名前が Undefined で、メッセージが提供されなかった場合、 UndefinedError が発生します。
- パラメーター
名前(オプション [ ユニオン [ str 、 未定義 ] ] )–
メッセージ(オプション [ str ] )–
- リターンタイプ
なし
- exception jinja2.TemplatesNotFound(names=(), message=None)
TemplateNotFound と同様ですが、複数のテンプレートが選択されている場合に発生します。 これは TemplateNotFound 例外のサブクラスであるため、基本例外をキャッチするだけで両方をキャッチできます。
バージョン2.11で変更:名前のリスト内の名前が未定義の場合、空の文字列ではなく、未定義であることを示すメッセージが表示されます。
バージョン2.2の新機能。
- パラメーター
名前(シーケンス [ ユニオン [ str 、 未定義 ] ] )–
メッセージ(オプション [ str ] )–
- リターンタイプ
なし
- exception jinja2.TemplateSyntaxError(message, lineno, name=None, filename=None)
テンプレートに問題があることをユーザーに通知するために発生します。
- パラメーター
メッセージ( str )–
lineno ( int )–
名前(オプション [ str ] )–
ファイル名(オプション [ str ] )–
- リターンタイプ
なし
- message
エラーメッセージ。
- lineno
エラーが発生した行番号。
- name
テンプレートのロード名。
- filename
ファイルシステムのエンコーディングでテンプレートをロードしたファイル名(ほとんどの場合、utf-8、またはWindowsシステムのmbcs)。
- exception jinja2.TemplateRuntimeError(message=None)
- テンプレートエンジンの一般的なランタイムエラー。 状況によっては、Jinjaがこの例外を発生させる場合があります。
- パラメーター
- メッセージ(オプション [ str ] )–
- リターンタイプ
- なし
- exception jinja2.TemplateAssertionError(message, lineno, name=None, filename=None)
- テンプレートの構文エラーと同様ですが、テンプレート内の何かがコンパイル時にエラーを引き起こしたが、必ずしも構文エラーが原因ではない場合をカバーしています。 ただし、これは TemplateSyntaxError の直接のサブクラスであり、同じ属性を持っています。
- パラメーター
- ;;* メッセージ( str )–
- lineno ( int )–
- 名前(オプション [ str ] )–
- ファイル名(オプション [ str ] )–
- リターンタイプ
- なし
カスタムフィルター
フィルタは、フィルタの左側の値を最初の引数として受け取り、新しい値を生成するPython関数です。 フィルタに渡される引数は、値の後に渡されます。
たとえば、フィルタテンプレート:42
は、バックグラウンドでmyfilter(42, 23)
と呼ばれます。
Jinjaには、いくつかの組み込みフィルターが付属しています。 カスタムフィルターを使用するには、少なくともvalue
引数をとる関数を記述し、それを Environment.filters に登録します。
日時オブジェクトをフォーマットするフィルターは次のとおりです。
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番目の引数になります。
- pass_environment()は、 Environment を渡します。
- pass_eval_context()は、評価コンテキストを渡します。
- pass_context()は、現在の Context を渡します。
これは、改行をHTML <br>
および<p>
タグに変換するフィルターです。 evalコンテキストを使用して、入力をエスケープして出力を安全とマークする前に、自動エスケープが現在有効になっているかどうかを確認します。
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番目の引数になります。
- pass_environment()は、 Environment を渡します。
- pass_eval_context()は、評価コンテキストを渡します。
- pass_context()は、現在の Context を渡します。
評価コンテキスト
評価コンテキスト(短い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
評価コンテキストは実行時に変更しないでください。 変更は、evalコンテキストオブジェクト自体ではなく、拡張機能のnodes.EvalContextModifier
およびnodes.ScopedEvalContextModifier
でのみ発生する必要があります。
- class jinja2.nodes.EvalContext(environment, template_name=None)
評価時間情報を保持します。 カスタム属性を拡張機能でアタッチできます。
- パラメーター
環境(環境)–
template_name (オプション [ str ] )–
- リターンタイプ
なし
- autoescape
自動エスケープがアクティブかどうかに応じて、 True または False 。
- volatile
True コンパイラがコンパイル時に一部の式を評価できない場合。 実行時には、これは常に False である必要があります。
グローバル名前空間
グローバル名前空間には、 Template.render()に渡す必要なしに使用できるはずの変数と関数が格納されます。 これらは、コンテキストなしでインポートまたは含まれるテンプレートでも使用できます。 ほとんどのアプリケーションは、 Environment.globals のみを使用する必要があります。
Environment.globals は、その環境によってロードされるすべてのテンプレートに共通のデータを対象としています。 Template.globals は、そのテンプレートのすべてのレンダリングに共通のデータを対象としており、 Environment.get_template()[で指定されていない限り、デフォルトで Environment.globals になります。 X194X]など。 レンダリングに固有のデータは、コンテキストとして Template.render()に渡す必要があります。
特定のレンダリングでは、1セットのグローバルのみが使用されます。 テンプレートAとBの両方にテンプレートグローバルがあり、BがAを拡張している場合、b.render()
を使用すると、両方にBのグローバルのみが使用されます。
テンプレートのロード後に環境グローバルを変更したり、テンプレートのロード後にテンプレートグローバルを変更したりしないでください。 テンプレートのロード後にグローバルを変更すると、環境と他のテンプレート間で共有される可能性があるため、予期しない動作が発生します。
低レベルAPI
低レベルAPIは、実装の詳細、デバッグの目的、または高度な拡張手法を理解するのに役立つ機能を公開します。 自分が何をしているのかを正確に理解していない限り、これらのいずれかを使用することはお勧めしません。
- Environment.lex(source, name=None, filename=None)
指定されたソースコードをLexし、トークンを
(lineno, token_type, value)
の形式のタプルとして生成するジェネレーターを返します。 これは、拡張機能の開発およびテンプレートのデバッグに役立ちます。前処理は行いません。 拡張機能の前処理を適用する場合は、 preprocess()メソッドを使用してソースをフィルタリングする必要があります。
- パラメーター
ソース( str )–
名前(オプション [ str ] )–
ファイル名(オプション [ str ] )–
- リターンタイプ
イテレータ[タプル[int、str、str]]
- Environment.parse(source, name=None, filename=None)
ソースコードを解析し、抽象構文ツリーを返します。 このノードツリーは、コンパイラがテンプレートを実行可能なソースコードまたはバイトコードに変換するために使用されます。 これは、デバッグやテンプレートからの情報の抽出に役立ちます。
Jinja拡張機能を開発している場合、これにより、生成されたノードツリーの概要がわかります。
- パラメーター
ソース( str )–
名前(オプション [ str ] )–
ファイル名(オプション [ str ] )–
- リターンタイプ
jinja2.nodes.Template
- Environment.preprocess(source, name=None, filename=None)
- すべての拡張子でソースを前処理します。 これはすべての解析およびコンパイルメソッドに対して自動的に呼び出されますが、 lex()に対してはではなくです。通常、実際のソースのみをトークン化する必要があるためです。
- パラメーター
- ;;* ソース( str )–
- 名前(オプション [ str ] )–
- ファイル名(オプション [ str ] )–
- リターンタイプ
- str
- Template.new_context(vars=None, shared=False, locals=None)
このテンプレート用に新しい
Context
を作成します。 提供された変数はテンプレートに渡されます。 デフォルトでは、グローバルはコンテキストに追加されます。 sharedが True に設定されている場合、データはグローバルを追加せずにそのままコンテキストに渡されます。locals は、内部使用のためのローカル変数のdictにすることができます。
- パラメーター
vars (オプション [ Dict [ str 、 任意 ] ] )–
共有( bool )–
ローカル(オプション [ マッピング [ str 、 任意 ] ] )–
- リターンタイプ
- 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が parse()によって返される可能性のある新しいASTノードを新しいバージョンで導入した場合です。
メタ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 ( jinja2.nodes.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 ( jinja2.nodes.Template )–
- リターンタイプ
イテレータ[オプション[str]]