EmPy Templating System

4.2.1 · active · verified Wed Apr 15

EmPy is a powerful, robust, and mature templating system for Python that allows embedding Python code directly into template text. It processes source documents containing special markup (default: '@') to produce output. The library is currently at version 4.2.1 and has an active development status, with recent updates modernizing its features and Python compatibility.

Warnings

breaking Major breaking changes occurred in the 4.x series compared to 3.x. This includes relicensing from GPL to BSD, significant changes to markup syntax (e.g., `repr` markup changed to backquote, in-place markup syntax changed), and modifications to the embedding interface. The `Interpreter` constructor and the global `expand` function now strictly require keyword arguments.
Fix: Review the official 4.x documentation and the `ANNOUNCE.html#changes` for specific migration details. Update markup syntax, and ensure all API calls to `em.Interpreter` and `em.expand` use keyword arguments (e.g., `expand(template, globals_=...)`).
breaking Internal module names and constants were changed in 4.x. For example, the `OVERRIDE_OPT` constant, previously accessible, was removed or refactored, leading to `ImportError` for applications that relied on such internals (e.g., `colcon-core` issues).
Fix: Avoid relying on EmPy's internal constants or module structure. If specific functionalities are needed, refer to the official API for supported methods. Downgrade to 3.x if critical functionality depends on removed internals and a migration is not immediately feasible.
gotcha Multi-line Python statements within `@{...}` blocks must be flush with the left margin of the template. Python's significant indentation rules apply directly to these blocks, and incorrect indentation will lead to `IndentationError` or other parsing failures.
Fix: Ensure that all lines within `@{...}` statement blocks are aligned to the leftmost column of the template content, unless they are intentionally indented as part of a Python code block (e.g., inside a function definition). Consistent indentation is key.
gotcha There are two distinct Python libraries with very similar names: `empy` (the templating system) and `EMpy` (Electromagnetic Python). They serve entirely different purposes and have different installation commands (`pip install empy` vs `pip install ElectromagneticPython`).
Fix: Verify that you are installing and using the correct library based on your intended application. For templating, ensure `empy` is installed and imported as `from em import ...`.

Install

pip install empy Install EmPy

Imports

expand
```
from em import expand
```
The primary API for string expansion is the 'expand' function found in the 'em' module (em.py). While 'empy' is the package name, 'em' is the module for core functionality. Attempting to directly 'import empy' as a module might not provide the expected API for templating, as 'empy' also refers to an internal 'pseudomodule' within the interpreter context.

Quickstart

This quickstart demonstrates how to use EmPy's `expand` function to process a template string with embedded Python expressions and statements. The template uses '@(expression)' for inline evaluation and '@{...}' for Python code blocks. A dictionary is passed as the `globals_` argument to provide the context for template variables.

from em import expand

template_string = '''Hello, @(name)!\nYour lucky number is @(2 * 3 * 7).\n@{for item in items:}\n  - @item\n@{}\n'''

context = {
    'name': 'World',
    'items': ['apple', 'banana', 'cherry']
}

rendered_output = expand(template_string, globals_=context)
print(rendered_output)

view raw JSON →