hbllmutils.template.quick

Quick template rendering utilities for simplified Jinja2 operations.

This module provides a streamlined interface for creating and rendering Jinja2 templates with minimal configuration. It extends the base PromptTemplate class to support custom environment preprocessing and offers a convenience function for one-off template rendering.

The module contains the following main components:

• QuickPromptTemplate - Enhanced template class with environment preprocessing

• quick_render() - Convenience function for quick template file rendering

Note

This module is designed for rapid prototyping and simple template rendering scenarios. For more complex template management, consider using the base PromptTemplate class directly.

Example:

>>> from hbllmutils.template.quick import QuickPromptTemplate, quick_render
>>> 
>>> # Using QuickPromptTemplate with custom environment preprocessing
>>> def add_filters(env):
...     env.filters['uppercase'] = str.upper
...     return env
>>> 
>>> template = QuickPromptTemplate(
...     "Hello, {{ name|uppercase }}!",
...     fn_env_preprocess=add_filters
... )
>>> print(template.render(name="world"))
Hello, WORLD!
>>> 
>>> # Quick rendering from a file
>>> result = quick_render(
...     "template.txt",
...     name="Alice",
...     age=30
... )

QuickPromptTemplate

class hbllmutils.template.quick.QuickPromptTemplate(template_text: str, strict_undefined: bool = True, fn_env_preprocess: Callable[[Environment], Environment] | None = None)

Enhanced prompt template with support for custom environment preprocessing.

This class extends PromptTemplate to allow custom preprocessing of the Jinja2 environment before template creation. This enables adding custom filters, tests, globals, or other environment modifications in a clean, reusable manner.

Parameters:

• template_text (str) – The Jinja2 template string to use for rendering

• strict_undefined (bool, optional) – Whether to raise errors on undefined variables, defaults to True

• fn_env_preprocess (Optional[Callable[[jinja2.Environment], jinja2.Environment]], optional) – Optional function to preprocess the Jinja2 environment before template creation. The function should accept a jinja2.Environment and return a modified jinja2.Environment

Variables:

_fn_env_preprocess (Optional[Callable[[jinja2.Environment], jinja2.Environment]]) – Stored environment preprocessing function

Note

The environment preprocessing function is called during initialization, before the template is compiled from the template text.

Example:

>>> import jinja2
>>> from hbllmutils.template.quick import QuickPromptTemplate
>>> 
>>> # Define a custom environment preprocessor
>>> def add_custom_filters(env):
...     env.filters['reverse'] = lambda x: x[::-1]
...     env.filters['double'] = lambda x: x * 2
...     return env
>>> 
>>> # Create template with custom environment
>>> template = QuickPromptTemplate(
...     "{{ text|reverse }} and {{ number|double }}",
...     fn_env_preprocess=add_custom_filters
... )
>>> 
>>> # Render with custom filters applied
>>> result = template.render(text="hello", number=5)
>>> print(result)
olleh and 10

__init__(template_text: str, strict_undefined: bool = True, fn_env_preprocess: Callable[[Environment], Environment] | None = None) → None

Initialize a QuickPromptTemplate with optional environment preprocessing.

Parameters:

• template_text (str) – The Jinja2 template string to use for rendering

• strict_undefined (bool, optional) – Whether to raise errors on undefined variables, defaults to True

• fn_env_preprocess (Optional[Callable[[jinja2.Environment], jinja2.Environment]], optional) – Optional function to preprocess the Jinja2 environment. Should accept and return a jinja2.Environment object

Example:

>>> template = QuickPromptTemplate(
...     "Hello, {{ name }}!",
...     strict_undefined=True
... )
>>> print(template.render(name="World"))
Hello, World!

quick_render

hbllmutils.template.quick.quick_render(template_file: str, strict_undefined: bool = True, fn_env_preprocess: Callable[[Environment], Environment] | None = None, **params: Any) → str

Quickly render a template file with the provided parameters.

This convenience function provides a one-line solution for loading a template from a file and rendering it with the given parameters. It creates a QuickPromptTemplate instance from the file and immediately renders it with the provided keyword arguments.

Parameters:

• template_file (str) – Path to the template file to render (string or Path object)

• strict_undefined (bool, optional) – Whether to raise errors on undefined variables, defaults to True

• fn_env_preprocess (Optional[Callable[[jinja2.Environment], jinja2.Environment]], optional) – Optional function to preprocess the Jinja2 environment before rendering. Should accept and return a jinja2.Environment object

• params (Any) – Variable names and their values to substitute in the template

Returns:

The rendered template string

Return type:

str

Raises:

• FileNotFoundError – If the template file does not exist

• jinja2.UndefinedError – If strict_undefined is True and an undefined variable is referenced in the template

Note

This function automatically detects the file encoding when reading the template file, making it suitable for templates in various encodings.

Warning

For repeated rendering of the same template, consider creating a QuickPromptTemplate instance once and calling its render() method multiple times for better performance.

Example:

>>> from hbllmutils.template.quick import quick_render
>>> 
>>> # Simple template rendering
>>> result = quick_render(
...     "greeting.txt",
...     name="Alice",
...     age=30
... )
>>> 
>>> # With custom environment preprocessing
>>> def add_filters(env):
...     env.filters['shout'] = lambda x: x.upper() + "!"
...     return env
>>> 
>>> result = quick_render(
...     "message.txt",
...     fn_env_preprocess=add_filters,
...     text="hello world"
... )