dotpromptz-handlebars

A high-performance Handlebars template engine for Python, powered by Rust.

This package provides Python bindings to handlebars-rust, offering near-native performance for template rendering while maintaining a Pythonic API.

Features

• Fast: Rust-powered template compilation and rendering
• Compatible: Implements the Handlebars specification
• Safe: HTML escaping by default, with options for raw output
• Extensible: Support for custom helpers and partials
• Type-safe: Full type hints for IDE support

Installation

pip install dotpromptz-handlebars

Quick Start

from handlebarrz import Template

# Create a template instance
template = Template()

# Register and render a template
template.register_template('greeting', 'Hello, {{name}}!')
result = template.render('greeting', {'name': 'World'})
print(result)  # Output: Hello, World!

Usage

Basic Templating

from handlebarrz import Template

template = Template()

# Simple variable substitution
template.register_template('simple', 'Welcome, {{user}}!')
print(template.render('simple', {'user': 'Alice'}))
# Output: Welcome, Alice!

# Nested properties
template.register_template('nested', '{{person.name}} is {{person.age}} years old')
print(template.render('nested', {'person': {'name': 'Bob', 'age': 30}}))
# Output: Bob is 30 years old

Built-in Helpers

# Conditionals
template.register_template(
    'conditional',
    """
{{#if active}}
  User is active
{{else}}
  User is inactive
{{/if}}
""",
)

# Iteration
template.register_template(
    'list',
    """
{{#each items}}
  - {{this}}
{{/each}}
""",
)

# With helper for context switching
template.register_template(
    'with',
    """
{{#with user}}
  Name: {{name}}, Email: {{email}}
{{/with}}
""",
)

Custom Helpers

from handlebarrz import HelperOptions, Template

template = Template()


# Register a custom helper
def format_name(params: list[object], options: HelperOptions) -> str:
    name = str(params[0]) if params else ''
    return name.upper() if options.hash_value('uppercase') else name


template.register_helper('format', format_name)
template.register_template('custom', '{{format name uppercase=true}}')
print(template.render('custom', {'name': 'alice'}))
# Output: ALICE

HelperOptions is callback-scoped; do not retain it for later use or access it from background work.

Partials

template = Template()

# Register a partial
template.register_partial('header', '<h1>{{title}}</h1>')
template.register_template('page', '{{> header}}<p>{{content}}</p>')
print(template.render('page', {'title': 'Welcome', 'content': 'Hello!'}))
# Output: <h1>Welcome</h1><p>Hello!</p>

HTML Escaping

template = Template()

# HTML is escaped by default
template.register_template('escaped', '{{content}}')
print(template.render('escaped', {'content': "<script>alert('xss')</script>"}))
# Output: &lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;

# Use triple braces for raw output
template.register_template('raw', '{{{content}}}')
print(template.render('raw', {'content': '<b>bold</b>'}))
# Output: <b>bold</b>

API Reference

Template Class

Part of Dotprompt

This package is part of the Dotprompt project, providing the Handlebars templating engine for the dotpromptz Python package. While primarily designed for Dotprompt, it can be used as a standalone Handlebars implementation for Python.

License

Apache-2.0