Pydantic Handlebars

0.1.0 · active · verified Thu Apr 16

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.

Common errors

```
pydantic. ValidationError: 1 validation error for UserProfile
company
  field required (type=missing)
```
cause 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.
```
cause 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'
```
cause The `pydantic-handlebars` package is not installed in the current Python environment.

fix Install the library using pip: `pip install pydantic-handlebars`.

Warnings

breaking As 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.
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.
gotcha This 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.

Install

pip install pydantic-handlebars Install stable version

Imports

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.

Quickstart

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}")

view raw JSON →