pyfcstm.utils.jinja2

Jinja2 environment augmentation utilities.

This module provides helpers for enriching a jinja2.Environment with Python built-ins, text-processing filters, and selected operating system environment variables. It is intended to simplify template authoring by making common Python functions available as filters, tests, and globals, while also adding project-specific text utilities.

The module contains the following public functions:

• add_builtins_to_env() - Register Python built-ins as filters, tests, and globals

• add_settings_for_env() - Apply built-ins plus additional filters and globals

Note

The added filters and globals are only attached to the environment instance passed to the functions and do not affect other environments.

Example:

>>> import jinja2
>>> from pyfcstm.utils.jinja2 import add_settings_for_env
>>> env = add_settings_for_env(jinja2.Environment())
>>> template = env.from_string("{{ 'Hello World'|to_identifier }}")
>>> template.render()
'Hello_World'

add_builtins_to_env

pyfcstm.utils.jinja2.add_builtins_to_env(env: Environment) → Environment

Mount Python built-in functions to a Jinja2 environment.

This function registers Python built-ins to the provided environment as:

• Filters: Callable built-ins are added as filters when no naming conflict exists.

• Tests: Common boolean checks are added as tests, using a simplified name for functions beginning with is (e.g., isinstance becomes the instance test).

• Globals: All non-conflicting built-ins are added to the global namespace.

In addition to these automatic registrations, this function always injects several convenience filters, even if they overwrite existing names in the environment:

• str: str

• set: set

• dict: dict

• keys: lambda x: x.keys()

• values: lambda x: x.values()

• enumerate: enumerate()

• reversed: reversed()

• filter: lambda x, y: filter(y, x)

Parameters:

env (jinja2.Environment) – A Jinja2 environment instance to modify.

Returns:

The same Jinja2 environment with built-ins mounted.

Return type:

jinja2.Environment

Warning

This function may override pre-existing filters named str, set, dict, keys, values, enumerate, reversed, and filter.

Example:

>>> import jinja2
>>> env = add_builtins_to_env(jinja2.Environment())
>>> tmpl = env.from_string("{{ [1, 2, 3]|reversed|list }}")
>>> tmpl.render()
'[3, 2, 1]'

add_settings_for_env

pyfcstm.utils.jinja2.add_settings_for_env(env: Environment) → Environment

Add built-ins, text filters, and environment variables to a Jinja2 environment.

This function enhances a Jinja2 environment by applying the following steps:

1. Register Python built-ins via add_builtins_to_env()

2. Add text-processing filters: - normalize: pyfcstm.utils.text.normalize() - to_identifier: pyfcstm.utils.text.to_identifier() - to_c_identifier: pyfcstm.utils.text.to_c_identifier()

3. Add a global helper: - indent: textwrap.indent()

4. Add operating system environment variables as globals (only if the name does not already exist in the environment).

Parameters:

env (jinja2.Environment) – The Jinja2 environment to enhance.

Returns:

The enhanced Jinja2 environment.

Return type:

jinja2.Environment

Note

Environment variables are only added if their names do not already exist in the environment’s global namespace.

Example:

>>> import jinja2
>>> env = add_settings_for_env(jinja2.Environment())
>>> template = env.from_string("{{ 'Hello World'|normalize }}")
>>> template.render()
'Hello_World'