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
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.fixPin 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.fixEnsure 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.fixRefer 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`.
fixEnsure 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.
fixVerify 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.
fixInstall 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.
Resources
No resource links recorded.