templore

A from-scratch, zero-dependency Jinja2-like template engine in pure Python. Written to actually understand how a real template engine works end to end: lexing → expression parsing → AST → tree-walking rendering → inheritance.

No pip install of anything — the whole engine is standard-library only.

from templore import Environment, DictLoader

env = Environment(loader=DictLoader({"hi": "Hello {{ name|upper }}!"}))
print(env.get_template("hi").render(name="ada"))     # Hello ADA!

print(Environment().from_string("{{ 1 + 2 * 3 }}").render())  # 7

Features

1.0.2 security fixes

• tojson escapes HTML-sensitive characters while preserving valid JSON, so untrusted values cannot terminate a surrounding HTML script element.
• FileSystemLoader rejects absolute paths, parent traversal and Windows path syntax, and resolves links before enforcing each configured template root.

Use forward-slash relative template names. Template source itself must still be trusted; the loader is not a sandbox for executing untrusted templates. JSON inside double-quoted HTML attributes still needs attribute escaping; prefer a script element or a single-quoted attribute for tojson output.

Install / run

python -m pip install templore
python -m pytest -q           # from the source distribution

# render a template file from the command line:
python -m templore render page.html --data ctx.json
python -m templore render page.html --var name=Ada --compiled -o out.html

API

Environment(loader=None, autoescape=False, undefined="lenient")
    .from_string(source, name=None) -> Template
    .get_template(name) -> Template          # via loader, cached

Template.render(context=None, **kwargs) -> str

Loaders: DictLoader({name: source}), FileSystemLoader(path_or_paths).

CLI

python -m templore render TEMPLATE [--data FILE.json] [--var K=V ...]
                                   [--compiled] [--autoescape] [-o OUT]

The template is loaded via a FileSystemLoader rooted at its own directory, so extends / include / import resolve relative to it. --var values are strings and override keys from --data.

How it works

The pipeline lives in templore/ as five small stages:

source ──Lexer──▶ tokens ──Parser──▶ AST ──Template.render──▶ output
                              │
                     ExpressionParser (recursive descent w/ precedence)

• lexer.py — splits raw source on the {{ }} / {% %} / {# #} delimiters (applying - whitespace trimming), then tokenizes the expression text inside each tag.
• expressions.py — a recursive-descent parser that turns expression tokens into Expr nodes, honoring operator precedence (or < and < not < compare < add < mul < unary < filter < postfix < primary).
• parser.py — assembles statement nodes (for/if/set/block/…), recursing through nested bodies until it meets the matching end tag.
• nodes.py — the AST. Expression nodes evaluate(ctx, env); statement nodes render(ctx, env). A plain tree-walking interpreter — no codegen.
• environment.py — configuration, the template cache, and the inheritance engine. It flattens the extends chain into per-block "chains" so that overriding and super() fall out naturally.

Runtime bits (runtime.py): a scoped Context, the lenient Undefined sentinel, the Namespace for imports, and the Markup safe-string used by autoescaping. Filters and tests live in filters.py.

The compiled backend (compiler.py)

Environment(compiled=True) swaps the tree-walker for a code generator: the AST is turned into Python source for a root(ctx, env) function, exec'd once, and cached on the template. Expressions become inlined Python expressions and {% for %} / {% if %} become native loops/branches — no per-node dispatch at render time. Inspect it with template.compiled_root.__source__.

env = Environment(compiled=True)
t = env.from_string("{% for x in xs %}{{ x|upper }}{% endfor %}")
print(t.compiled_root.__source__)   # the generated Python

Templates using extends / block / macro / import / call are left to the interpreter (the compiler returns None and rendering falls back), so turning compiled=True on is always safe — output is identical either way, which the test suite verifies case-by-case.

License

MIT