netboot 0.2.4__tar.gz → 0.3.1__tar.gz

{netboot-0.2.4 → netboot-0.3.1}/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.1}/CHANGELOG.md

@@ -4,7 +4,115 @@ 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.1] - 2026-10-02
+
+### Fixed
+- **`windhcp://` could not set a multi-valued option** (two name servers, two NTP
+  servers) with its default PowerShell method, and the failure took the rest of
+  the reservation with it. The value was sent comma-joined, and
+  `Set-DhcpServerv4OptionValue -Value` takes `String[]`: Windows answered
+  "Parameters for option value to be set for option ID 6 do not match with option
+  definition" and, under `ErrorActionPreference = 'Stop'`, every option after it
+  was abandoned — so the target got a router and **no boot file**. Values are now
+  sent as a list. Present since the backend shipped in 0.2.0; found by running it
+  against a real Windows Server 2025 DHCP server rather than reading the script.
+
+### Added
+- **`DhcpServer.extras(ctx, phase)`** — one documented extension point for
+  backend-native fragments netboot does not model: an extra statement, an extra
+  command, or a condition such as the iPXE chainload (serve the iPXE binary to a
+  PXE ROM, the script to iPXE). It defaults to the configured `raw.<backend>`
+  fragments, and a subclass overrides it to decide per target. All four shipped
+  backends consume it, and `raw.<backend>.remove=` is new: a fragment that
+  belongs to teardown rather than to arming. For `windhcp://` a fragment may be a
+  PowerShell line or a `{"Args": [...], "Ignore": bool}` netsh command, which
+  works under either `method`.
+- `method=netsh` **verifies what the server actually applied**. netsh exits 0 and
+  prints its success line even when it rejected what it was told — measured: a
+  `domain-name-servers` option with one unreachable address keeps the other, says
+  "not a valid DNS Server", says "Command completed successfully", exits 0. So
+  after applying, netboot reads the state back with `netsh ... dump` (the one
+  netsh output that is command syntax rather than localised prose) and fails
+  naming any option that is missing or short of values. The cmdlet method needs
+  none of this: Windows raises there by itself.
+- `windhcp://` takes **`method=powershell|netsh`**. The default is unchanged (the
+  `DhcpServer` cmdlets); `method=netsh` drives `netsh dhcp server ...` instead,
+  for a host where that PowerShell module is not installed. It is independent of
+  `transport=`, and netsh is invoked from PowerShell with each argument an array
+  element, so no value is spliced into a command line. Success is `$LASTEXITCODE`
+  rather than netsh's localised success line, a removal tolerates a reservation
+  that is not there, option data types are declared per option (unmapped ones as
+  `STRING`), and a multi-valued option becomes one argument per value.
+
+## [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 +671,9 @@ 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.1...HEAD
+[0.3.1]: https://github.com/jose-pr/netboot/compare/v0.3.0...v0.3.1
+[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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netboot
-Version: 0.2.4
+Version: 0.3.1
 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.1}/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.1}/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.1}/docs/configuration.md

@@ -60,7 +60,7 @@ DHCP options the server should give the client.
 | `dnsmasq://` | dnsmasq | writes `dhcp-host`/`dhcp-option` files, local or over `sftp://` | nothing locally; `netboot[ssh]` for remote paths |
 | `kea://`, `keas://` | ISC Kea | `reservation-add` / `reservation-del` via the control agent | `netboot[kea]` |
 | `dhcpd://` | ISC dhcpd | an OMAPI host object | `netboot[dhcpd]` |
-| `windhcp://` | Windows DHCP | its own PowerShell cmdlets over ssh or WinRM | nothing over ssh; `netboot[winrm]` for WinRM |
+| `windhcp://` | Windows DHCP | its PowerShell cmdlets *or* `netsh`, over ssh or WinRM | nothing over ssh; `netboot[winrm]` for WinRM |
 
 Each has one thing that is easy to get wrong:
 
@@ -72,8 +72,35 @@ Each has one thing that is easy to get wrong:
   file-only Kea loads the hook and still refuses.
 - **dhcpd** hosts added over OMAPI do not survive a restart by themselves — that
   is dhcpd's design.
-- **Windows** needs the `DhcpServer` module on the host PowerShell runs on, and
-  an account with DHCP-administrator rights.
+- **Windows** validates some option values as it stores them, whichever method
+  you use: a name server that does not answer is refused rather than stored. An
+  arm that fails part-way leaves the reservation with the options applied so far
+  — the next successful arm fixes it, and `pixie complete` removes it.
+- **Windows** needs an account with DHCP-administrator rights, and — for the
+  default `method=powershell` — the `DhcpServer` module on the host the shell runs
+  on. Where that module is missing (Server Core without the RSAT feature, or an
+  older release) `method=netsh` drives `netsh dhcp server ...` instead. The two
+  choices are independent: `transport=` is how netboot gets a shell (`ssh` or
+  `winrm`), `method=` is what it runs there.
+
+  netsh is still invoked *from* PowerShell, with each argument an element of a
+  JSON array — so no value is ever spliced into a command line, which is the same
+  guarantee the cmdlet path gives. Extra commands (a policy, say) go through
+  `raw.windhcp=` or a subclass's `extras()`; see
+  [Extra commands and conditions](extending.md#extra-commands-and-conditions),
+  which is also where the iPXE chainload recipe lives.
+
+  **netsh cannot be trusted to report failure.** Given an option value it dislikes
+  — a name server that does not answer — it keeps the rest, prints "not a valid DNS
+  Server", prints "Command completed successfully" and exits 0 (measured on
+  Windows Server 2025). So netboot reads the state back afterwards with
+  `netsh ... dump`, the one netsh output that is command syntax rather than
+  localised prose, and fails naming any option that did not land or lost values.
+  The cmdlet method needs no such check: Windows raises there by itself. A few behaviours are
+  netsh's own rather than netboot's: an option's data type has to be declared
+  (netboot maps the modelled options, and sends anything else as `STRING`), a
+  multi-valued option is passed as one argument per value, and the reservation is
+  created as `BOTH` (DHCP and BOOTP) to match what the cmdlets do by default.
 
 ### Options
 
@@ -176,11 +203,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.1/docs/extending.md

@@ -0,0 +1,215 @@
+# 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.
+
+### Extra commands and conditions
+
+netboot models the options it can translate everywhere, and `extras()` is the way
+in for everything else — an extra statement, an extra command, or a condition
+that makes the server answer two kinds of client differently. The canonical case
+is the **iPXE chainload**: hand a PXE ROM the iPXE binary, then hand iPXE itself
+the script, or iPXE loads iPXE forever.
+
+Two ways in, both ending up in the same list:
+
+```yaml
+dhcpservers:
+  # from config, per connection
+  - dhcpd://key@dhcp01/?raw.dhcpd=if exists user-class and option user-class = "iPXE" { filename "boot.ipxe"; } else { filename "undionly.kpxe"; }
+```
+
+```python
+# from code, which is the one that can look at the target
+from netboot.dhcp.dhcpd import dhcpd
+
+class dhcpd(dhcpd):                      # still handles dhcpd://
+    def extras(self, ctx, phase="add"):
+        lines = super().extras(ctx, phase)   # keep the config's own fragments
+        if phase == "add" and ctx.image.globals.get("ipxe"):
+            lines.append(
+                'if exists user-class and option user-class = "iPXE" '
+                '{ filename "boot.ipxe"; } else { filename "undionly.kpxe"; }'
+            )
+        return lines
+```
+
+`phase` is `add` or `remove`. A bare `raw.<backend>=` belongs to `add`;
+`raw.<backend>.remove=` is for a fragment that undoes something at teardown (a
+policy created while arming, say). What a fragment *is* belongs to the backend:
+
+| Backend | A fragment is | Where it lands |
+| ------- | ------------- | -------------- |
+| `dhcpd://` | dhcpd config **statements** | appended to the host object's `statements`, after the modelled options — so a conditional written there wins |
+| `dnsmasq://` | config **lines** (`dhcp-match=set:ipxe,77,iPXE`, `dhcp-boot=tag:ipxe,boot.ipxe`) | the options file for that target's tag |
+| `kea://` | an **`option-data` entry** | the reservation's `option-data` |
+| `windhcp://` | a **PowerShell line**, or a `{"Args": [...], "Ignore": false}` **netsh command** | after the reservation and its options |
+
+A netsh command works under either windhcp `method`: with `method=netsh` it joins
+the command list, and with `method=powershell` it becomes the `netsh` call it
+describes rather than being dropped. `Args` may be a list, or one string that is
+split on whitespace — a query string has nowhere to put a list. `Ignore` marks a
+command whose failure is acceptable, which is what a teardown usually wants.
+
+Fragments are emitted **verbatim**: netboot does not parse, validate or escape
+them. That is the point of an escape hatch, and its risk — a value that ends a
+dhcpd statement early, or a PowerShell line that does more than it looks like,
+is yours to get right. Where netboot builds the text itself (a netsh command
+under `method=powershell`) it quotes it properly.
+
+Order is defined: modelled options first, then `extras()`, in the order given
+(unsuffixed `raw.<backend>` before `raw.<backend>.add`). A condition that
+overrides an option therefore comes after the thing it overrides, which is what
+both dhcpd's last-write-wins statements and a Windows policy need.
+
+A declarative, cross-backend way to say "serve this file to iPXE and that one to
+a PXE ROM" is not here yet, because the backends disagree about where a condition
+lives — dhcpd puts it on the host, Windows in a scope-level policy, dnsmasq in a
+tag, Kea in a client class. `extras()` is what makes it expressible today.
+