hbllmutils.template.env

This module provides utilities for enhancing Jinja2 environments with Python builtins and additional settings.

It includes functions to add Python built-in functions to Jinja2 environments as filters, tests, and globals, as well as adding environment variables and custom text processing functions.

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 adds Python’s built-in functions to the specified Jinja2 environment as filters, tests, or global functions based on their characteristics. Functions are categorized and mounted appropriately:

• Filters: Functions that can process data (e.g., str, len, sorted)

• Tests: Boolean-returning functions for conditional checks (e.g., isinstance, callable)

• Globals: All built-in functions available as global functions in templates

Parameters:

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

Returns:

The Jinja2 Environment with Python builtins mounted

Return type:

jinja2.Environment

Example:

>>> env = jinja2.Environment()
>>> env = add_builtins_to_env(env)
>>> # Now Python builtins like len, str, etc. are available in templates
>>> template = env.from_string("{{ items | len }}")
>>> template.render(items=[1, 2, 3])
'3'

add_settings_for_env

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

Add additional settings and 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 custom text processing filters: - indent: Text indentation using textwrap.indent - plural: Pluralize words using hbutils.string.plural_word - ordinalize: Convert numbers to ordinal form (1st, 2nd, etc.) - titleize: Convert text to title case - read_file_text: Read text content from a file path

3. Adding environment variables as global variables for template access

Parameters:

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

Returns:

The enhanced Jinja2 environment

Return type:

jinja2.Environment

Example:

>>> env = jinja2.Environment()
>>> env = add_settings_for_env(env)
>>> # Now the environment has additional filters and globals
>>> template = env.from_string("{{ 'word' | plural }}")
>>> template.render()
'words'

create_env

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

Create a new Jinja2 environment with enhanced settings.

This function creates a new Jinja2 environment and applies all enhancements including Python builtins, custom filters, and environment variables via add_settings_for_env(). This is a convenience function that provides a fully configured environment ready for template rendering.

Parameters:

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

Returns:

A fully configured Jinja2 environment with all enhancements

Return type:

jinja2.Environment

Example:

>>> env = create_env()
>>> # Use the environment to render templates with enhanced features
>>> template = env.from_string("{{ 'hello' | upper }}")
>>> template.render()
'HELLO'
>>> template = env.from_string("{{ 3 | ordinalize }}")
>>> template.render()
'3rd'