Registry / llm-agents / pydantic-handlebars

pydantic-handlebars

JSON →
library0.2.1pypiunverified

pydantic-handlebars is an early-stage Python library, currently at version 0.1.0, that integrates the Handlebars templating engine with Pydantic for composing LLM prompts. It aims to provide structured, validated data from Pydantic models to Handlebars templates, primarily serving as an underlying component for projects like `pydantic-ai`. Due to its nascent stage, the release cadence is irregular, and the API is subject to change.

pip install pydantic-handlebars
INSTALL
IMPORT
SIG · PYDANTIC-HANDLEBAR
P
pydantic-handlebars
llm-agentsenv0.2.1
Install
3.0s avg
Import
Disk
26MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 3.7s
py 3.11
✓ —
✓ 3.1s
py 3.12
✓ —
✓ 2.5s
py 3.13
✓ —
✓ 2.7s
py 3.9
✕ build_error
✕ build_error
26MB installed
● package 26MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HandlebarsTemplate
from pydantic_handlebars import HandlebarsTemplate
The exact top-level API might be `TemplateStr` when used via `pydantic-ai`, or a direct Handlebars class for standalone use. This is a common pattern, but exact API for 0.1.0 is inferred.

This quickstart demonstrates how to define a Pydantic model for structured data, create a Handlebars template string, and then render the template by passing the Pydantic model's data (converted to a dictionary) to the `HandlebarsTemplate`. It highlights how Pydantic ensures data validity before rendering and touches on potential Handlebars rendering issues for missing data.

from pydantic import BaseModel from pydantic_handlebars import HandlebarsTemplate class UserProfile(BaseModel): name: str title: str company: str # Define your Handlebars template template_string = """ Hello, my name is {{name}}. I am a {{title}} at {{company}}. """ # Create a Pydantic model instance with data user_data = UserProfile(name="Alice", title="Software Engineer", company="Acme Corp") # Instantiate the HandlebarsTemplate with the template string template = HandlebarsTemplate(template_string) # Render the template using the Pydantic model's data rendered_output = template.render(user_data.model_dump()) print(rendered_output) # Example with missing data (will cause Pydantic validation error if not handled) try: invalid_data = UserProfile(name="Bob", title="Manager") # Missing 'company' except Exception as e: print(f"Caught expected error: {e.__class__.__name__}") # Example of direct Handlebars rendering issues (e.g., missing variable in template context) # This would typically be caught by Pydantic if the model was strict enough or template tried to access non-existent field. loose_template_string = "Hello, {{missing_field}}!" loose_template = HandlebarsTemplate(loose_template_string) # This specific `render` call doesn't raise if 'missing_field' is just not found, but it highlights template data needs. rendered_loose = loose_template.render({"name": "Charlie"}) print(f"Rendered with missing data (Handlebars default behavior): {rendered_loose}")
Debug
Known issues
breakingAs a 0.1.0 library, `pydantic-handlebars` is in an early development stage. Its API is highly unstable, and breaking changes are very likely in future minor or patch releases.
fix
Pin the version in your `requirements.txt` (e.g., `pydantic-handlebars==0.1.0`) and review changelogs carefully when upgrading.
affects: <1.0.0
gotcha`pydantic-handlebars` is built to work with Pydantic V2. Attempting to use it with Pydantic V1 will likely lead to compatibility issues or errors due to significant API changes between Pydantic versions.
fix
Ensure your project uses Pydantic V2 (`pip install 'pydantic>=2'`). If you must use Pydantic V1, you might need to find an alternative templating solution or adapt the integration manually.
affects: All versions when used with Pydantic V1
gotchaThis library is often used as an optional dependency within `pydantic-ai`, where templating functionality might be exposed via `pydantic_ai.TemplateStr`. Direct standalone usage of `pydantic-handlebars` might have a less documented or internal-facing API.
fix
Refer to the `pydantic-ai` documentation if you are using this library as part of the `pydantic-ai` ecosystem. For standalone use, be prepared to consult the source code for the most accurate API details.
affects: All versions
Errors
Common errors & fixes
pydantic. ValidationError: 1 validation error for UserProfile company field required (type=missing)
The data provided to the Pydantic model constructor (which then feeds the template) is missing a required field defined in the `BaseModel`.
fix
Ensure that the dictionary or keyword arguments passed to your Pydantic model instance contain all required fields as defined in your `BaseModel` schema. For optional fields, use `Optional[Type]` or provide a default value.
Handlebars runtime error: {{variable}} not found in context.
The Handlebars template attempts to access a variable or property (e.g., `{{my_field}}`) that is not present in the data dictionary passed to the template renderer.
fix
Verify that all variables referenced in your Handlebars template are present as keys in the dictionary generated from your Pydantic model (e.g., `model_instance.model_dump()`). Ensure your Pydantic model explicitly includes all fields needed by the template.
ModuleNotFoundError: No module named 'pydantic_handlebars'
The `pydantic-handlebars` package is not installed in the current Python environment.
fix
Install the library using pip: `pip install pydantic-handlebars`.
Upgrade
Version history
0.2.1latest on PyPI · released May 25, 2026
Audit
Dependencies
pydanticrequiredCore data validation and model definition.
python-handlebarsrequiredUnderlying Handlebars template engine implementation.
Agent activity
21 hits · last 30 days
node
20
OpenAI (training)
1
Resources

No resource links recorded.