Core API

The core of jinja2-fragments provides functionality to render individual blocks from Jinja2 templates.

exception jinja2_fragments.BlockNotFoundError(block_name, template_name, message=None)[source]

Bases: Exception

__init__(block_name, template_name, message=None)[source]

async jinja2_fragments.render_block_async(environment, template_name, block_name, *args, **kwargs)[source]

This works similar to render_block() but returns a coroutine that when awaited returns the entire rendered template block string. This requires the environment async feature to be enabled.

Return type:: str

async jinja2_fragments.render_blocks_async(environment, template_name, block_names, *args, **kwargs)[source]

This works similar to render_blocks() but returns a coroutine that when awaited returns every rendered template block as a single string. This requires the environment async feature to be enabled.

Return type:: str

jinja2_fragments.render_block(environment, template_name, block_name, *args, **kwargs)[source]

Render a specific block from a Jinja2 template with the given context.

This function renders a named block from a template located in the application’s template folder. The context variables passed are available within the rendered block. Custom signals are triggered before and after rendering to allow integration with additional logic.

Parameters:

template_name (str) – The name of the Jinja2 template file. This should include only the template file’s name, without the path.
block_name (str) – The name of the block defined in the template that you want to render.
**context – Additional variables to be included in the template’s context. These key-value pairs will be accessible inside the block.

Return type:

str

Returns:

The rendered HTML output of the block.

Raises:

RuntimeError – If the Flask application or Jinja2 environment is not properly initialized.
TemplateNotFound – If the template specified does not exist.
KeyError – If the block specified is not defined in the provided template.

Signals:

before_render_template_block: A signal sent before rendering the block.: Includes the template_name, block_name, and context.
template_block_rendered: A signal sent after rendering the block.: Includes the template_name, block_name, and context.

jinja2_fragments.render_blocks(environment, template_name, block_names, *args, **kwargs)[source]

Render multiple blocks from a Jinja2 template with the given context.

This function processes and renders the specified list of blocks from a single Jinja2 template file in the template folder. The given context variables are shared across all the blocks.

Parameters:

template_name (str) – The name of the Jinja2 template file. This should include only the template file’s name, without the path.
block_names (Sequence[str]) – A sequence of block names from the template that you want to render. These blocks are rendered sequentially in the given order.
**context – Additional variables passed as context for rendering the blocks. These variables will be available across all the blocks.

Return type:

str

Returns:

A combined HTML string containing the rendered content of all blocks.

Raises:

RuntimeError – If the Flask application or Jinja2 environment is not properly initialized.
TemplateNotFound – If the template specified does not exist.
KeyError – If any of the blocks specified in block_names are not defined in the template.

Signals:

before_render_template_blocks: Triggered before rendering the list of blocks.: Includes the template_name, block_names, and context.
template_blocks_rendered: Triggered after rendering the blocks.: Includes the template_name, block_names, and context.

jinja2_fragments.setup_globals(environment)[source]

Install render_block and render_blocks as Jinja2 template globals.

After calling this function, templates rendered with environment can use render_block and render_blocks directly in expressions:

{{ render_block("other_template.html", "block_name", key=value) }}
{{ render_blocks("other_template.html", ["block_a", "block_b"], key=value) }}

The current template context is automatically forwarded; extra keyword arguments override individual context variables.

The correct sync or async callable is chosen based on environment.is_async. Existing globals named render_block and render_blocks are preserved.

Parameters:: environment (Environment) – The Jinja2 Environment to modify.
Return type:: None