Pybars3

Common errors

• PybarsError: Template source must be a unicode string

  cause This error occurs when the template source provided to `compiler.compile()` is not a Unicode string. This is particularly common in Python 2 environments if string literals are not explicitly marked with `u''` or if byte strings are passed. In Python 3, it can happen if byte strings are inadvertently passed.
  fix Ensure your template source string is a Unicode string. In Python 2, use `u"your template here"`. In Python 3, all standard string literals are Unicode, but verify no byte strings (`b""`) are being used as template input.

• AttributeError: 'str' object has no attribute 'get'

  cause This error can occur within templates or helpers when attempting to access properties of a context variable that is a simple string, but the template expects an object (like a dictionary or an object with attributes). Older versions of Pybars3 (prior to 0.9.2) had issues where dictionary calls did not always take precedence over attributes, leading to unexpected resolution.
  fix Ensure the data context passed to the template matches the structure expected by the template. If accessing dictionary keys, ensure the context is a dictionary. Upgrade to Pybars3 0.9.2 or later, which improved the precedence of dictionary calls over attributes and `.get()` methods.

• TypeError: 'list' object is not callable (when using options['fn'])

  cause This typically happens in a custom block helper when `options['fn']` (which represents the inner block of the Handlebars helper) is not correctly invoked. It might be due to a missing `options` argument in the helper definition or calling `options.fn` instead of `options['fn']`.
  fix Verify that your block helper's signature includes `options` as the second positional argument and that you are correctly invoking the inner block using `options['fn'](scope_for_inner_block)`. For example: `result.extend(options['fn'](item))`.

Warnings

• gotcha Pybars3 does not fully implement all features of Handlebars.js 2.0 or even 1.1. Specific features like `@root`, `_parent`, `../` accessors, `each` helper with `@index`, `@key`, `@first`, `@last`, dynamic partials, and raw blocks are supported, but full compatibility with the latest Handlebars.js features should not be assumed.
  Fix: Consult the `pybars3` GitHub README for a partial list of supported Handlebars.js features to confirm functionality. If a feature is missing, consider implementing it as a custom helper.
• gotcha Custom helper functions in Pybars3 have different calling conventions than their JavaScript counterparts. Block helpers must accept `this, options, *args, **kwargs`. Other helpers and closures in the context should accept `this, *args, **kwargs`.
  Fix: Ensure your Python helper functions adhere to the specified argument signatures: `def my_block_helper(this, options, arg1, kwarg1='val'): ...` for block helpers, and `def my_helper(this, arg1, kwarg1='val'): ...` for other helpers.
• gotcha When passing keyword arguments to helpers (e.g., `{{foo bar quux=1}}`), the keyword names in Handlebars templates must not be Python reserved words. Using a reserved word like `print` as a keyword argument name will result in a Python syntax error.
  Fix: Avoid using Python reserved keywords as names for keyword arguments in your Handlebars templates when they are processed by Pybars3. Choose alternative names that are valid Python identifiers.
• gotcha For efficiency and control over HTML escaping, Pybars3 uses a `strlist` class. When a helper returns a `strlist` instance, its content will NOT be escaped, similar to Handlebars.js `SafeString`. Helpers in inner loops are recommended to return `list` or `strlist` for performance.
  Fix: Be mindful of the return type of your helpers. If you need to output unescaped HTML, return a `strlist`. For content that should be HTML-escaped by the template engine, return a standard Python string (or `unicode` in Python 2).

Install

• pip install pybars3 Install latest version

Imports

• Compiler

  from pybars import Compiler

  The main class for compiling Handlebars templates.

Quickstart

This quickstart demonstrates compiling a Handlebars template, registering a custom block helper, defining a partial, and rendering the template with contextual data. Note the use of `u""` for template strings for compatibility, though on Python 3 plain strings are sufficient.

from pybars import Compiler

# Get a compiler
compiler = Compiler()

# Define a helper function
def _list_helper(this, options, items):
    result = ['<ul>']
    for item in items:
        result.append('<li>')
        result.extend(options['fn'](item)) # Render the inner block
        result.append('</li>')
    result.append('</ul>')
    return result

# Register helpers and partials
helpers = {'list': _list_helper}
header_template = compiler.compile(u'<h1>{{title}}</h1>')
partials = {'header': header_template}

# Compile the main template source
source = u"""
{{>header}}
<p>Hello, {{name}}!</p>
{{#list people}}{{firstName}} {{lastName}}{{/list}}
"""
template = compiler.compile(source)

# Data to render
data = {
    'title': 'People List',
    'name': 'World',
    'people': [
        {'firstName': 'Yehuda', 'lastName': 'Katz'},
        {'firstName': 'Carl', 'lastName': 'Lerche'},
        {'firstName': 'Alan', 'lastName': 'Johnson'}
    ]
}

# Render the template
output = template(data, helpers=helpers, partials=partials)
print(output)