hbllmutils.template.env

Jinja2 environment enhancement utilities.

This module provides helper functions for configuring jinja2.Environment instances with Python built-ins, environment variables, and custom text helpers. The goal is to make template authoring more expressive by exposing commonly needed functionality as filters, tests, and globals.

The module contains the following main components:

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

• add_settings_for_env() - Add built-ins, text helpers, and environment variables

• create_env() - Create a fully configured Jinja2 environment

Example:

>>> import jinja2
>>> from hbllmutils.template.env import create_env
>>> env = create_env()
>>> template = env.from_string("{{ 3 | ordinalize }} and {{ 'word' | plural }}")
>>> template.render()
'3rd and words'

Note

The environment exposes all current OS environment variables as globals. Use this carefully when rendering templates with untrusted input.

add_builtins_to_env

hbllmutils.template.env.add_builtins_to_env(env: Environment) → Environment

Mount Python built-in functions to a Jinja2 environment.

This function inspects Python’s built-in namespace and mounts functions into a Jinja2 environment as filters, tests, and globals. Filters and tests are added when no conflicting entries already exist.

The mounting strategy follows these heuristics:

• Filters: any callable built-in is added as a filter if no name conflict exists.

• Tests: callables with an is prefix, plus common boolean functions (all, any, callable, hasattr) are added as tests.

• Globals: all built-in callables are exposed as globals if no conflict exists.

In addition, a few convenience filter aliases are always ensured:

• str, set, dict, keys, values, enumerate, reversed, filter

Parameters:

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

Returns:

The enhanced environment (same instance as input).

Return type:

jinja2.Environment

Example:

>>> import jinja2
>>> env = add_builtins_to_env(jinja2.Environment())
>>> env.from_string("{{ items | len }}").render(items=[1, 2, 3])
'3'
>>> env.from_string("{{ value is none }}").render(value=None)
'True'

Note

Built-in names that conflict with existing filters or tests are not overridden, preserving any user-defined behavior.

add_settings_for_env

hbllmutils.template.env.add_settings_for_env(env: Environment) → Environment

Add additional settings and helper functions to a Jinja2 environment.

This function enhances a Jinja2 environment by:

1. Adding Python built-in functions via add_builtins_to_env().

2. Adding text processing filters and globals:

   • indent - Indent text using textwrap.indent()

   • plural - Pluralize a word with its count using hbutils.string.plural_word()

   • ordinalize - Convert numbers to ordinal form using hbutils.string.ordinalize()

   • titleize - Convert text to title case using hbutils.string.titleize()

   • read_file_text - Read text content from a file path

3. Adding all current environment variables as global variables, allowing template authors to reference them directly.

Parameters:

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

Returns:

The enhanced environment (same instance as input).

Return type:

jinja2.Environment

Example:

>>> import jinja2
>>> env = add_settings_for_env(jinja2.Environment())
>>> env.from_string("{{ 'word' | plural }}").render()
'words'
>>> env.from_string("{{ 3 | ordinalize }}").render()
'3rd'

Warning

Environment variables are added as globals. If templates are rendered from untrusted sources, avoid exposing sensitive environment variables.

create_env

hbllmutils.template.env.create_env(strict_undefined: bool = True) → Environment

Create a new Jinja2 environment with enhanced settings.

This is a convenience function that builds a jinja2.Environment instance and applies add_settings_for_env(). It optionally configures the undefined-variable behavior using jinja2.StrictUndefined.

Parameters:

strict_undefined (bool) – If True (default), use jinja2.StrictUndefined to raise errors for undefined variables. If False, use the default jinja2.Undefined behavior.

Returns:

A fully configured Jinja2 environment with all enhancements.

Return type:

jinja2.Environment

Example:

>>> env = create_env()
>>> env.from_string("{{ 'hello' | upper }}").render()
'HELLO'
>>> env.from_string("{{ 3 | ordinalize }}").render()
'3rd'

Note

Use strict_undefined=False if you prefer Jinja2’s default behavior, where undefined variables render as empty strings.