netboot 0.2.4__tar.gz → 0.3.0__tar.gz

{netboot-0.2.4 → netboot-0.3.0}/AGENTS.md

@@ -36,7 +36,15 @@ python -m venv .venv/3.14-nt-amd64
 ```
 
 Install **every extra that has tests**: without `http` the repository-service
-tests skip rather than run, and `pytest -rs` is how you see that happen.
+tests skip rather than run, and `pytest -rs` is how you see that happen. The
+`dev` extra pulls in the optional template engines' libraries (`mako`,
+`python-liquid`, `pybars3`, `chevron`) for the same reason.
+
+`tests/test_external_engines.py` needs **`ruby`** and **`puppet`**, which this
+Windows box does not have: those cases skip here and run under WSL
+(`FedoraLinux-44` has both). A change to `.erb`/`.epp` rendering is unverified
+until the suite has run there — the engine-shape cases (registration, suffixes,
+the missing-program error) do run everywhere.
 
 ## Commands
 

{netboot-0.2.4 → netboot-0.3.0}/CHANGELOG.md

@@ -4,7 +4,75 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2026-10-02
+
+### Changed
+- **The shell template engine now claims the `.shtpl` suffix only** (it claimed
+  *every* suffix before, as the documented fallback). The suffix picks the engine
+  and the stem names the artifact, which is the convention `install.ks.j2`
+  already used: rename `boot.cfg` to `boot.cfg.shtpl` and `ctx.render("boot.cfg")`
+  keeps working unchanged. A file no engine claims is **copied as is** by the new
+  `CopyTemplate`, last in the default `template_types` — so a static `grub.cfg`
+  needs no engine, and a file that *does* carry `%{NAME}` placeholders ships them
+  unrendered until it is renamed. That one case logs a warning naming the rename.
+  Narrowing `template_types` so nothing claims a file raises
+  `netboot.templates.TemplateEngineError`, which names the file and every
+  engine's suffixes.
+
+### Added
+- **Seven more template engines**, each claiming its own suffix and costing
+  nothing when unused: `MakoTemplate` (`.mako`, `netboot[mako]`),
+  `LiquidTemplate` (`.liquid`, `netboot[liquid]`), `HandlebarsTemplate`
+  (`.hbs`/`.handlebars`, `netboot[handlebars]`), `MustacheTemplate` (`.mustache`,
+  `netboot[mustache]`), and `ERBTemplate` (`.erb`) / `EppTemplate` (`.epp`),
+  which render through the system `ruby` and `puppet epp render` so an existing
+  template behaves as its author tested it (`PIXIE_RUBY` / `PIXIE_PUPPET` name
+  the program if it is not on `PATH`). Every engine is registered whether or not
+  its dependency is present — a claimed file reports what is missing instead of
+  being copied — and nothing is imported until a file claims it. What each engine
+  does with `templates_undefined` differs by library and is tabulated in the
+  configuration guide; handlebars and mustache cannot fail on an undefined name
+  at all.
+- `template_data()` / `DataView` / `jsonable()` — a lazy mapping view of the
+  render context for engines that read data rather than evaluate Python
+  (`{{ target.hostname }}` beside `{{ ctx.target.hostname }}`), and its
+  JSON-serialisable form for the subprocess engines.
+- `SubprocessTemplate` — the base for an engine that renders through another
+  language's own tooling: program lookup with an env override, a temporary
+  template and values file, a timeout, and the program's stderr in the error.
+- `ShellTemplate` is configured by subclassing, through three class attributes:
+  `EXT` (a string or a sequence, dots optional, case-insensitive; `None` or
+  `"*"` claims any suffix), `DELIMITER` (default `"%"`) and `PATTERN` —
+  `"braced"` (default, `%{NAME}`), `"unbraced"` (`%NAME`) or `"all"`.
+- POSIX default expressions in the braced form: `%{NAME:-fallback}` substitutes
+  the fallback when the value is unset *or* empty, `%{NAME-fallback}` only when
+  it is unset. One layer of `'`/`"` quotes is stripped, the fallback is literal
+  text, and a placeholder with a default never fails whatever
+  `templates_undefined` says. `:=`, `:?` and `:+` are not implemented and stay
+  literal text.
+- `CopyTemplate` — the copy-as-is engine described above, working in **bytes**:
+  the loader no longer decodes a file before knowing which engine claims it, so
+  the copy is byte-exact for anything (CRLF, latin-1, a binary) and
+  `ctx.render()` returns `bytes` for such a file. `EXT` narrows it to chosen
+  suffixes; `Template.BINARY` is the flag any engine can set to be handed raw
+  bytes. A non-UTF-8 file claimed by a *text* engine now raises
+  `TemplateEngineError` naming the file, where it used to fail inside the read.
+- `Loader.find_source()` — the byte-returning counterpart of `get_source()`
+  (which keeps jinja2's text contract).
+- **A template-engine registry**: `register_template_type()` (bare or as a
+  decorator, with an optional `priority=`), `unregister_template_type()`,
+  `TEMPLATE_TYPES` and `by_priority()`. `Loader(template_types=None)` — the new
+  default — uses every registered engine, so a `--load-module` plugin is picked
+  up without rebuilding the list, and the list is snapshotted at construction.
+- **`Template.PRIORITY`**, so engine selection does not depend on registration
+  order: engines are consulted highest first, `DEFAULT_PRIORITY` (0) for an
+  ordinary engine and `FALLBACK_PRIORITY` (-100) for `CopyTemplate`. A plugin is
+  registered after the shipped engines, so without this every plugin would sit
+  behind the catch-all and never see a file. Equal priorities keep the order they
+  were given, so an explicit `template_types` list still means what it says.
+- `Template.EXT` and `JinjaTemplate.EXT`, so suffix ownership is one declarative
+  attribute per engine, plus `netboot.templates.template_extensions()` to read it
+  back normalised.
 
 ## [0.2.4] - 2026-09-28
 
@@ -563,7 +631,8 @@ First packaged release: the `netboot` library with the `pixie` command line.
   config value construction no longer swallows non-`TypeError` errors; repo
   `joinpath` keeps `.local` a path so chained joins work.
 
-[Unreleased]: https://github.com/jose-pr/netboot/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/jose-pr/netboot/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/jose-pr/netboot/compare/v0.2.4...v0.3.0
 [0.2.4]: https://github.com/jose-pr/netboot/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/jose-pr/netboot/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/jose-pr/netboot/compare/v0.2.1...v0.2.2

{netboot-0.2.4 → netboot-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netboot
-Version: 0.2.4
+Version: 0.3.0
 Summary: PXE provisioning management: render netboot artifacts and drive DHCP for targets
 Project-URL: Homepage, https://github.com/jose-pr/netboot/
 Project-URL: Issues, https://github.com/jose-pr/netboot/issues
@@ -35,11 +35,15 @@ Requires-Dist: pyyaml; extra == 'config'
 Provides-Extra: dev
 Requires-Dist: black; extra == 'dev'
 Requires-Dist: build; extra == 'dev'
+Requires-Dist: chevron; extra == 'dev'
 Requires-Dist: dnspython; extra == 'dev'
 Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mako; extra == 'dev'
+Requires-Dist: pybars3; extra == 'dev'
 Requires-Dist: pypureomapi; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: python-liquid; extra == 'dev'
 Requires-Dist: pywinrm; extra == 'dev'
 Requires-Dist: pyyaml; extra == 'dev'
 Requires-Dist: requests; extra == 'dev'
@@ -52,10 +56,18 @@ Provides-Extra: docs
 Requires-Dist: mkdocs; extra == 'docs'
 Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: handlebars
+Requires-Dist: pybars3; extra == 'handlebars'
 Provides-Extra: http
 Requires-Dist: requests; extra == 'http'
 Provides-Extra: kea
 Requires-Dist: requests; extra == 'kea'
+Provides-Extra: liquid
+Requires-Dist: python-liquid; extra == 'liquid'
+Provides-Extra: mako
+Requires-Dist: mako; extra == 'mako'
+Provides-Extra: mustache
+Requires-Dist: chevron; extra == 'mustache'
 Provides-Extra: ssh
 Requires-Dist: pathlib-next[sftp]; extra == 'ssh'
 Provides-Extra: winrm
@@ -99,11 +111,21 @@ Optional extras:
 | `netboot[dns]` | The `dnspython` resolver backend (best coverage; without it hostname targets still resolve via the system/`nslookup` fallbacks) |
 | `netboot[http]` | `http`/`https` repository services (`requests`); `file`/`tftp` repos and rendering need nothing extra |
 | `netboot[kea]` | The `kea://` DHCP backend (`requests`) |
+| `netboot[mako]` | `*.mako` templates (`mako`) |
+| `netboot[liquid]` | `*.liquid` templates (`python-liquid`) |
+| `netboot[handlebars]` | `*.hbs` / `*.handlebars` templates (`pybars3`) |
+| `netboot[mustache]` | `*.mustache` templates (`chevron`) |
 | `netboot[dhcpd]` | The `dhcpd://` DHCP backend over OMAPI (`pypureomapi`) |
 | `netboot[winrm]` | `windhcp://` over WinRM (`pywinrm`); over ssh it needs nothing |
 | `netboot[ssh]` | `dnsmasq://` with remote `sftp://` paths (`pathlib_next[sftp]`) |
 | `netboot[docs]`   | Build the documentation site (`mkdocs`) |
 
+`*.erb` and `*.epp` templates need no extra, but do need `ruby` or `puppet`
+installed: they render through the real program, so an existing template behaves
+as its author tested it. `PIXIE_RUBY` / `PIXIE_PUPPET` name it when it is not on
+`PATH`. Jinja2 (`.j2`) and the `%{NAME}` shell engine (`.shtpl`) are built in, and
+a file no engine claims is copied unchanged.
+
 Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),
 [`pathlib_next`](https://github.com/jose-pr/pathlib-next) (URI-aware paths),
 [`yaconfiglib`](https://github.com/jose-pr/yaconfiglib) (layered YAML), and
@@ -175,7 +197,9 @@ python -m venv .venv/3.14
 ```
 
 Install every extra that has tests — without `http` the repository-service tests
-skip instead of running, which `-rs` makes visible. Develop on the latest Python
+skip instead of running, which `-rs` makes visible (`dev` carries the template
+engines' libraries for the same reason; the `.erb`/`.epp` tests skip unless
+`ruby`/`puppet` are installed). Develop on the latest Python
 and also run the floor (3.9) before finishing a piece of work. More detail, plus
 the layout and CI notes, in
 [`AGENTS.md`](https://github.com/jose-pr/netboot/blob/main/AGENTS.md).

{netboot-0.2.4 → netboot-0.3.0}/README.md

@@ -35,11 +35,21 @@ Optional extras:
 | `netboot[dns]` | The `dnspython` resolver backend (best coverage; without it hostname targets still resolve via the system/`nslookup` fallbacks) |
 | `netboot[http]` | `http`/`https` repository services (`requests`); `file`/`tftp` repos and rendering need nothing extra |
 | `netboot[kea]` | The `kea://` DHCP backend (`requests`) |
+| `netboot[mako]` | `*.mako` templates (`mako`) |
+| `netboot[liquid]` | `*.liquid` templates (`python-liquid`) |
+| `netboot[handlebars]` | `*.hbs` / `*.handlebars` templates (`pybars3`) |
+| `netboot[mustache]` | `*.mustache` templates (`chevron`) |
 | `netboot[dhcpd]` | The `dhcpd://` DHCP backend over OMAPI (`pypureomapi`) |
 | `netboot[winrm]` | `windhcp://` over WinRM (`pywinrm`); over ssh it needs nothing |
 | `netboot[ssh]` | `dnsmasq://` with remote `sftp://` paths (`pathlib_next[sftp]`) |
 | `netboot[docs]`   | Build the documentation site (`mkdocs`) |
 
+`*.erb` and `*.epp` templates need no extra, but do need `ruby` or `puppet`
+installed: they render through the real program, so an existing template behaves
+as its author tested it. `PIXIE_RUBY` / `PIXIE_PUPPET` name it when it is not on
+`PATH`. Jinja2 (`.j2`) and the `%{NAME}` shell engine (`.shtpl`) are built in, and
+a file no engine claims is copied unchanged.
+
 Built on [`duho`](https://github.com/jose-pr/duho) (CLI/args/command discovery),
 [`pathlib_next`](https://github.com/jose-pr/pathlib-next) (URI-aware paths),
 [`yaconfiglib`](https://github.com/jose-pr/yaconfiglib) (layered YAML), and
@@ -111,7 +121,9 @@ python -m venv .venv/3.14
 ```
 
 Install every extra that has tests — without `http` the repository-service tests
-skip instead of running, which `-rs` makes visible. Develop on the latest Python
+skip instead of running, which `-rs` makes visible (`dev` carries the template
+engines' libraries for the same reason; the `.erb`/`.epp` tests skip unless
+`ruby`/`puppet` are installed). Develop on the latest Python
 and also run the floor (3.9) before finishing a piece of work. More detail, plus
 the layout and CI notes, in
 [`AGENTS.md`](https://github.com/jose-pr/netboot/blob/main/AGENTS.md).

{netboot-0.2.4 → netboot-0.3.0}/docs/api.md

@@ -39,8 +39,22 @@ The engine and its context objects. Rendered from source via
 
 ::: netboot.templates.JinjaTemplate
 
+::: netboot.templates.MakoTemplate
+
+::: netboot.templates.LiquidTemplate
+
+::: netboot.templates.HandlebarsTemplate
+
+::: netboot.templates.MustacheTemplate
+
+::: netboot.templates.ERBTemplate
+
+::: netboot.templates.EppTemplate
+
 ::: netboot.templates.ShellTemplate
 
+::: netboot.templates.CopyTemplate
+
 ## Utilities
 
 ::: netboot.utils.dicts

{netboot-0.2.4 → netboot-0.3.0}/docs/configuration.md

@@ -176,11 +176,90 @@ not a mapping is an error naming the file.
 
 `templates` is a list of search paths (local or URI). For each render netboot looks
 for a file named by the target's MAC (`aa-bb-cc-...`), hostname, or IP — falling
-back to the bare template name. A `.j2` / `.jinja` / `.jinja2` file is rendered
-with Jinja2; anything else is rendered with the `%`-delimited shell engine, whose
-`%{UPPER_SNAKE}` placeholders come from the flattened context.
+back to the bare template name.
+
+**The suffix picks the engine, and the stem names the artifact.** A `.j2` /
+`.jinja` / `.jinja2` file is rendered with Jinja2; a `.shtpl` file with the
+`%`-delimited shell engine, whose `%{UPPER_SNAKE}` placeholders come from the
+flattened context. Seven more engines ship for template trees that already exist
+in another language:
+
+| Engine | Suffixes | Needs | `templates_undefined` |
+| ------ | -------- | ----- | --------------------- |
+| `JinjaTemplate` | `.j2` `.jinja` `.jinja2` | — | all three |
+| `MakoTemplate` | `.mako` | `netboot[mako]` | `strict`, `lenient`; `debug` behaves as `lenient` |
+| `LiquidTemplate` | `.liquid` | `netboot[liquid]` | all three (`debug` names the variable in the output) |
+| `HandlebarsTemplate` | `.hbs` `.handlebars` | `netboot[handlebars]` | **always lenient** — the library cannot fail |
+| `MustacheTemplate` | `.mustache` | `netboot[mustache]` | **always lenient** (logs under `strict`) |
+| `ERBTemplate` | `.erb` | `ruby` on `PATH` (or `PIXIE_RUBY`) | n/a — missing data is Ruby's `nil` |
+| `EppTemplate` | `.epp` | `puppet` on `PATH` (or `PIXIE_PUPPET`) | n/a — missing data is Puppet's `undef` |
+| `ShellTemplate` | `.shtpl` | — | all three |
+| `CopyTemplate` | anything else | — | n/a — nothing is substituted |
+
+Every optional engine is **registered whether or not its library is installed**,
+so a `.liquid` file tells you to `pip install netboot[liquid]` instead of being
+quietly copied. None of them is imported until a file claims it, so an install
+that uses none pays nothing.
+
+Jinja and mako evaluate Python, so a template reaches into `ctx` directly. The
+data languages (liquid, handlebars, mustache) and the external ones (ERB, EPP)
+get a **mapping view** of the same context instead: `{{ ctx.target.hostname }}`
+and `{{ target.hostname }}` both resolve, an address or a path arrives as the
+string a template would have printed, and the engine's own machinery
+(`ctx._netboot_`, the renderer) is left out. ERB additionally sets each top-level
+name as an instance variable (`@target`), and EPP as a parameter (`$target`).
+
+ERB and EPP run the real `ruby` and `puppet` as a subprocess, with the context
+marshalled to JSON — which is the point: an existing `.erb` renders the way its
+author tested it, rather than the way a reimplementation guesses. Set `PIXIE_RUBY`
+or `PIXIE_PUPPET` if the program is installed but not on `PATH`. Because a template is also found by its stem, the file behind
+an artifact called `boot.cfg` is `boot.cfg.shtpl` and `ctx.render("boot.cfg")`
+still finds it.
+
+Anything else is **copied as is** — a static `grub.cfg`, an EFI binary or a
+license file is a template that needs no engine. The copy engine works in
+**bytes**: the loader never decodes the file, so the result is byte-exact
+whatever it holds (CRLF line endings, latin-1 text, something that is not text at
+all) and `ctx.render()` returns `bytes` for it rather than `str`.
+
+Before 0.3.0 the shell engine claimed every suffix, so a file that *does* carry
+`%{NAME}` placeholders now ships them unrendered: rename it to `*.shtpl` once.
+That is the one mistake a copy can hide, so a copy that still finds placeholders
+logs a warning naming the rename.
 
 Only the braced form is substituted, so a bare `%word` is left alone — a kickstart
 file keeps its `%packages`, `%pre`, `%post` and `%end` sections, and a script keeps
 `date +%Y`. Write `%%` for a literal `%` next to a brace, `%{NAME}` to substitute.
-An unknown `%{NAME}` is an error.
+An unknown `%{NAME}` follows `templates_undefined` (above).
+
+`%{NAME:-fallback}` renders `fallback` when `NAME` is unset **or empty**, and
+`%{NAME-fallback}` only when it is unset — the two POSIX forms, so a template can
+carry its own default instead of requiring the variable. One layer of `'`/`"`
+quotes is stripped (`%{NAME:-'a default'}`), the fallback is literal text (no
+nested placeholders, and no `}` inside it), and a placeholder that has a default
+never fails whatever `templates_undefined` says. The other POSIX forms (`:=`,
+`:?`, `:+`) are not implemented and stay literal text.
+
+The engine is configured by subclassing, not by config, for a tree that uses
+another convention:
+
+```python
+from netboot.templates.shell import ShellTemplate
+
+class DollarTemplate(ShellTemplate):
+    EXT = (".tpl", ".cfg")   # a single string is fine; `None` claims any suffix
+    DELIMITER = "$"
+    PATTERN = "all"          # 'braced' (default), 'unbraced', or 'all'
+```
+
+Register the class with `netboot.templates.register_template_type` (see
+[Extending](extending.md#custom-template-engines)) or pass it in
+`Loader(..., template_types=[...])`. Engines are consulted in `PRIORITY` order,
+highest first, so a registered engine is asked before the catch-all
+`CopyTemplate` whatever order they were registered in. The default is every
+registered engine: `JinjaTemplate`, `ShellTemplate`, then `CopyTemplate`. Narrow
+it — dropping the copy engine, or giving it a suffix list of its own — and a file
+nothing claims raises `netboot.templates.TemplateEngineError`, naming the file and
+what each engine handles. A file that is not valid UTF-8 raises the same error when the engine
+that claims it needs text; set `BINARY = True` on an engine to be handed the raw
+bytes instead, as `CopyTemplate` does.

netboot-0.3.0/docs/extending.md

@@ -0,0 +1,150 @@
+# Extending
+
+## Event hooks
+
+Pass `hooks=[...]` to `Pixie(...)` — each entry is a callable or a
+`"module.function"` import string. A hook
+
+```python
+def my_hook(event, netboot, value, kwargs):
+    ...
+    return value
+```
+
+is invoked for every `PixieEvent` and may transform the value flowing through it.
+Events fire around object creation (`NewPixieObject`, `SetPixieProperty`,
+`PixieInitiated`), lookup (`LookupTarget`, `FoundTarget`, `FoundTargetImage`,
+`FoundTargetDhcpzone`), context construction (`PixieContextForTarget`), and the
+init/complete lifecycle (`StartPixieInitialize` … `EndPixieComplete`). This is the
+seam for customising how targets/images/zones are resolved and how the render
+context is assembled.
+
+### The contract
+
+- **Always return.** Every hook is handed the previous hook's return value, and
+  the last return value is what netboot uses. A hook that falls off the end
+  returns `None`, which is then what the engine gets — a lookup hook that
+  forgets to `return value` turns every lookup into "not found".
+- **The signature is positional**, and `kwargs` arrives as a plain `dict` (the
+  fourth argument), not as `**kwargs`.
+- **`netboot` is `None` for `NewPixieObject`**, which fires before the instance
+  exists; `value` there is the class about to be instantiated, and returning a
+  subclass is how you swap in your own.
+- **`value` and `kwargs` differ per event.** `SetPixieProperty` gets a
+  `(name, value)` tuple plus `origin=`/`rawvalue=`; the lookup events get the
+  object found (or the query, for `LookupTarget`) plus `target=`; the lifecycle
+  events get the target, then the built context.
+- **`PixieEvent` is a string enum whose values are prefixed** — the value of
+  `PixieEvent.LookupTarget` is the string `"PixieEvent.LookupTarget"`. Compare
+  against the enum member, not a bare name.
+
+```python
+from netboot import PixieEvent
+
+def only_on_lookup(event, netboot, value, kwargs):
+    if event is not PixieEvent.FoundTarget:
+        return value                      # pass everything else through
+    return value or fallback_target()
+```
+
+## Custom template engines
+
+An engine is a class with two things: the suffixes it claims (`EXT`) and
+`render()`. Register it and it joins the engines every `Loader` consults.
+
+```python
+from netboot.templates import Template, register_template_type
+
+@register_template_type
+class MakoTemplate(Template):
+    EXT = ".mako"                      # a string, or a sequence of them
+
+    def __init__(self, template: str) -> None:
+        self._source = template
+
+    def render(self, **extras):
+        ctx = self._globals_["ctx"]    # the PixieContext being rendered
+        return my_mako_render(self._source, ctx)
+```
+
+Import the module before anything renders — `--load-module your.plugin`, the same
+flag a DHCP backend plugin needs.
+
+**Priority, not registration order, decides who gets a file.** Engines are
+consulted highest `PRIORITY` first, and a plugin is necessarily registered
+*after* the shipped engines — if order decided, every plugin would sit behind the
+catch-all `CopyTemplate` and never see a file. So:
+
+| `PRIORITY` | Meaning |
+| ---------- | ------- |
+| `DEFAULT_PRIORITY` (`0`) | an ordinary engine claiming its own suffixes — the default, and enough to outrank the copy engine |
+| above `0` | override a shipped engine on a suffix it also claims (`priority=10` to take `.j2` from `JinjaTemplate`) |
+| `FALLBACK_PRIORITY` (`-100`) | a last resort, where `CopyTemplate` sits |
+
+Engines of *equal* priority keep the order they were given, so an explicit
+`Loader(..., template_types=[...])` still means what it says. Set the priority on
+the class, or at registration for a class you do not own:
+
+```python
+register_template_type(SomeonesEngine, priority=10)
+```
+
+`unregister_template_type(cls)` removes one again, and a `Loader` snapshots the
+registry when it is built, so importing a plugin halfway through a run never
+changes an engine already in use.
+
+Other attributes on the contract: **`BINARY = True`** to be handed the file's raw
+`bytes` instead of decoded text (and to return bytes, as `CopyTemplate` does),
+and `EXT = None` to claim *every* suffix — which only makes sense together with a
+low priority.
+
+The shipped engines are the worked examples, and they cover the three shapes an
+engine takes:
+
+- **evaluates Python** (`JinjaTemplate`, `MakoTemplate`) — hand the engine `ctx`
+  itself and let the template reach into it.
+- **reads data only** (`LiquidTemplate`, `HandlebarsTemplate`,
+  `MustacheTemplate`) — build the namespace with
+  `netboot.templates.template_data(self._globals_, extras)`, which returns a lazy
+  mapping view of the context. liquid cannot traverse attributes at all, so this
+  is not optional for that class of engine.
+- **shells out** (`ERBTemplate`, `EppTemplate`) — subclass
+  `SubprocessTemplate`, set `COMMAND`, `ENV_VAR` and `EXT`, and implement
+  `command(program, template_path, values_path)`. The base marshals the context
+  with `jsonable()`, writes template and values into a temporary directory, runs
+  the program with a timeout, and turns a non-zero exit into a
+  `TemplateEngineError` carrying the program's own stderr.
+
+An engine that needs an optional library imports it in a helper, not at module
+scope, and raises `ImportError` naming the extra — that way the class can be
+registered unconditionally, and a file it claims reports what is missing rather
+than falling through to the copy engine.
+
+## Custom DHCP backends
+
+`netboot.dhcp.DhcpServer` dispatches on the URI scheme of a zone's `dhcpservers`
+entry: a subclass whose lowercased class name equals the scheme handles it.
+
+```python
+from netboot.dhcp import DhcpServer
+
+class dnsmasq(DhcpServer):        # handles dnsmasq://...
+    def add_target(self, ctx):
+        ...                       # arm DHCP for ctx.target
+    def remove_target(self, ctx):
+        ...                       # disarm it
+```
+
+netboot ships four backends — `netboot.dhcp.dnsmasq`, `.kea`, `.dhcpd` and
+`.windhcp` — and they are the worked examples: one writes files (locally or over
+`sftp://`), one speaks a REST API, one a binary protocol, and one runs
+PowerShell over ssh or WinRM. A backend gets its client options from
+`self.options_for(ctx)` and translates them; see the configuration guide for
+what an operator writes.
+
+Subclassing at any depth is honoured, so a backend may share an intermediate
+base. Import your plugin module before the config builds the zones — pass
+`--load-module your.plugin` (repeat or colon-separate for several) so the
+`DhcpServer` subclass is registered when `dnsmasq://...` is resolved.
+
+An unknown scheme raises a clear `ValueError` rather than silently doing nothing.

{netboot-0.2.4 → netboot-0.3.0}/examples/README.md

@@ -6,8 +6,8 @@ a laptop.
 
 ```
 config/pixie.yaml              the config `pixie` discovers (./config/pixie.yaml)
-templates/debian/boot.cfg      shell-engine template (%{NAME} placeholders)
-templates/debian/install.ks.j2 Jinja template (full context access)
+templates/debian/boot.cfg.shtpl shell-engine template (%{NAME} placeholders)
+templates/debian/install.ks.j2  Jinja template (full context access)
 plugins/recording.py           a DhcpServer backend that prints instead of arming
 ```
 
@@ -44,9 +44,11 @@ Expected output for `initiate web01`: the backend line, then the rendered
   zone by containment, so it names its `dhcpzone` — otherwise zone lookup finds
   nothing. Either target can be selected by id, hostname, MAC or IP, in any MAC
   spelling.
-- **Both template engines.** `boot.cfg` has no Jinja suffix, so the shell engine
-  renders it: `%{UPPER_SNAKE}` placeholders from the flattened context, and a
-  bare `%` left alone (which is what lets a kickstart's `%packages` through).
+- **Both template engines.** The suffix picks the engine and the stem names the
+  artifact: `boot.cfg.shtpl` is rendered by the shell engine and asked for as
+  `boot.cfg` — `%{UPPER_SNAKE}` placeholders from the flattened context, a bare
+  `%` left alone (which is what lets a kickstart's `%packages` through), and
+  `%{NAME:-fallback}` for a value the context may not carry.
   `install.ks.j2` is Jinja, with `ctx`, `shell_quote`, `Path` and `Uri` in scope.
 - **A real DHCP backend.** `config/pixie.yaml` carries a commented
   `dnsmasq://` entry beside the recording stub: uncomment it (and drop the stub)

netboot-0.3.0/examples/templates/debian/boot.cfg.shtpl

@@ -0,0 +1,8 @@
+# Shell-engine template: the `.shtpl` suffix is what picks the engine, and the
+# rendered artifact is named by the stem (`boot.cfg`). Only %%{NAME} substitutes;
+# a bare % is literal text, so this comment survives and so does a shell line
+# like: date +%Y%m%d. %%{NAME:-fallback} fills in a value the context lacks.
+default=install
+label install
+    kernel %{IMAGE_GLOBALS_KERNEL}
+    append ip=%{TARGET_IP} hostname=%{TARGET_HOSTNAME} domain=%{DHCPZONE_DOMAIN}

{netboot-0.2.4 → netboot-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netboot"
-version = "0.2.4"
+version = "0.3.0"
 authors = [{ name = "Jose A." }]
 description = "PXE provisioning management: render netboot artifacts and drive DHCP for targets"
 readme = "README.md"
@@ -52,6 +52,15 @@ dependencies = [
 [project.optional-dependencies]
 # Config-file loading for the CLI (YAML with !include).
 config = ["pyyaml"]
+# The mako template engine (`*.mako`). netboot.templates registers the engine
+# either way, so a .mako file without the extra raises ImportError naming it
+# rather than falling through to the copy engine.
+mako = ["mako"]
+# Further optional template engines, same deal: the engine is always registered,
+# the library is imported only when a file claims it.
+liquid = ["python-liquid"]
+handlebars = ["pybars3"]
+mustache = ["chevron"]
 # http/https repository services. pathlib_next's uri scheme handler for
 # http(s) imports `requests` at module import, and nothing else installs it --
 # pathlib_next[uri] does not. Repos served over file/tftp, and rendering in
@@ -84,6 +93,11 @@ dev = [
     # Backend dependencies, so their tests run rather than skip.
     "pypureomapi",
     "pywinrm",
+    # Template engines behind an extra, so their tests run rather than skip.
+    "mako",
+    "python-liquid",
+    "pybars3",
+    "chevron",
 ]
 docs = ["mkdocs", "mkdocs-material", "mkdocstrings[python]"]