tplx

Render a tree of templates where each file's suffix picks its engine and its stem names what it renders: boot.cfg.j2 is Jinja, boot.cfg.mako is mako, and both answer to boot.cfg. A file no engine claims is copied byte for byte. Documentation: https://jose-pr.github.io/tplx/.

Features

• One call for every engine — Jinja, mako, Liquid, Handlebars, Mustache, Go's text/template, ERB, EPP, envsubst (as GNU, a8m or drone) and a %{NAME} shell-style engine, each rendering the same data.
• Name by stem, dispatch by suffix — a caller asks for boot.cfg; the file found decides the engine.
• Several search roots, local or remote, searched in order, plus per-caller candidate names and paths (web01.boot.cfg before boot.cfg).
• Includes that search the same way — {% include %}, <%include/>, {{> partial}} and the rest resolve through the lookup that loaded the file.
• One undefined-variable policy (strict, lenient, debug) that means the same thing in every engine that can honour it.
• Your encoding of the data — a DataEncoder subclass decides what is a structure and how values are written and flattened for the engines that cannot run Python.
• Byte-exact fallback — an unclaimed file is copied as it is, never decoded.
• Pluggable — an engine is a class with a suffix list and a priority, registered directly or through the tplx.engines entry point, and checked by the shipped tplx.testing.EngineContract suite.
• Nothing required — each engine's library is an extra, imported only when a file needs it.

Installation

pip install tplx

Each library-backed engine is an extra of that name (pip install "tplx[jinja,mako]"); the cli extra adds the tplx command.

Each engine keeps its own syntax and defaults. In particular Handlebars and Mustache HTML-escape {{x}} (& becomes &), as their specifications say; write {{{x}}} for the value as it is. The other engines write values unescaped.

Templates and their roots are trusted, in every engine alike: Jinja and mako run Python, ERB and EPP run Ruby and Puppet. What tplx guards is the template name: one that would leave the search paths (.., a backslash, a drive) is refused.

Quick start

from tplx import Loader

loader = Loader(["templates"])
text = loader.render("boot.cfg", {"hostname": "web01"}, release="13")

A caller with its own search order binds it once; includes follow it:

lookup = loader.lookup(
    candidates=lambda name: [f"web01.{name}", name],
    paths=["debian"],  # templates/debian/ before templates/
)
text = lookup.render("boot.cfg", hostname="web01")

Filters, helpers and options go to each engine's own environment:

import shlex

from tplx import JinjaTemplate, Loader

loader = Loader(
    ["templates"],
    configure={JinjaTemplate: lambda env: env.filters.update(quote=shlex.quote)},
)

Command line

pip install "tplx[cli,jinja]"
tplx render templates/boot.cfg.j2 -s hostname=web01      # one file
tplx render boot.cfg -r templates -d host.json -o boot.cfg  # a name, data from JSON
tplx render web01.boot.cfg boot.cfg -r templates         # the first name found
tplx find boot.cfg -r templates                          # which file, which engine
tplx engines                                             # what is registered
tplx render nginx.conf -r templates --env -u debug       # envsubst from the environment

-s a.b=v nests and merges into --data; -s n=json:3 passes JSON. Exit status: 0 done, 1 the template or an engine failed, 2 a usage error.

API overview

Development

python -m venv .venv/3.14
.venv/3.14/bin/python -m pip install -e ".[dev,docs]"   # Scripts/ on Windows
.venv/3.14/bin/python -m pytest -q -rs

Releasing

This project follows Semantic Versioning and keeps a CHANGELOG.md. Pushing a tag matching v* triggers the release workflow: test and dependency-floor gates → build (checking the tag names the version built) → an installed-wheel smoke test and a strict docs build as gates → GitHub release → publish. The release workflow never deploys the docs site itself: for a final release its last job dispatches the docs workflow at the tag, which owns every Pages deploy.

License

MIT — see LICENSE.