netboot 0.1.0__py3-none-any.whl

netboot/AGENTS.md

@@ -0,0 +1,244 @@
+# `netboot` — public API header
+
+Header-file-style reference for the `netboot` package: every public export with
+its signature, arguments, contract, and gotchas, so this module can be
+consumed without reading its source. Kept current with the public API. For the
+project overview, install instructions and CLI usage, see the repo-root
+overview doc.
+
+## Engine (`netboot` / `netboot.__init__`)
+
+- **`Pixie(hooks=(), **config)`** — the engine. `config` is the merged config
+  mapping: `targets`, `images`, `dhcpzones`, `repos` (each a `dict[id, ...]`
+  built into the corresponding class via its type hints — `TypeError` from the
+  value class falls back to a no-`_id` constructor call), `globals` (dict,
+  deep-copied), `defaults` (per-collection default mappings), plus any other
+  annotated `Pixie` attribute. `hooks` is a sequence of callables or
+  `"module.func"` import-path strings; resolved once in `__new__`. Every
+  config-driven step fires a `PixieEvent` through the hook chain (see below)
+  so hooks can intercept object construction and property values before
+  they're set.
+  - **`.targets`** / **`.dhcpzones`** / **`.images`** / **`.repos`** —
+    `dict[str, ...]` of `PixieTarget` / `DhcpZone` / `PixieImage` /
+    `Repository`, keyed by config id.
+  - **`.globals`** — `dict`, layered into every render context.
+  - **`.hook(event, value=None, **kwargs) -> value`** — run the hook chain for
+    `event`, threading `value` through each `f(event, netboot, value, kwargs)`
+    and returning the (possibly transformed) result.
+  - **`.lookup_target(target: str) -> PixieTarget | None`** — exact id match
+    first, else the first target whose hostname starts with `target`
+    (case-insensitive), or whose MAC or IP equals it. Fires
+    `PixieEvent.LookupTarget` (may substitute a `PixieTarget` directly) then
+    `PixieEvent.FoundTarget`; `None` if nothing resolves to a `PixieTarget`.
+  - **`.lookup_image(name: str, target=None) -> PixieImage`** — the image
+    whose `.match(img_name, name)` returns the highest truthy value (default
+    `PixieImage.match` is exact-name equality); falls back to an empty dict
+    if nothing matches (**not** `None` — check truthiness carefully). Fires
+    `PixieEvent.FoundTargetImage`.
+  - **`.lookup_dhcpzone(name: str, target=None) -> DhcpZone | None`** — by id;
+    if `name` is empty and `target` is given, uses `target.dhcpzone` or finds
+    the zone whose `.network` contains `target.ip` (and caches the id back
+    onto `target.dhcpzone`). Fires `PixieEvent.FoundTargetDhcpzone`.
+  - **`.make_context(target, globals: list[dict] = None) -> PixieContext`** —
+    resolves image + dhcp zone for `target`, merges
+    `[self.globals, *globals, image.globals, dhcpzone.globals, target.globals]`
+    (image/dhcpzone/target objects are shared across targets and never
+    mutated) into a fresh `PixieContext`, attaches a new `Renderer`/`Loader`
+    over `config["templates"]`, and sets `.version`. Raises a plain
+    `Exception` if the target's image or dhcp zone can't be resolved. Fires
+    `PixieEvent.PixieContextForTarget`.
+  - **`.initialize(target) -> PixieContext`** — `make_context` then
+    `ctx.pxe_init(self)` (arms every `dhcpzone.dhcpservers` for the target).
+    Fires `StartPixieInitialize` / `EndPixieInitialize`.
+  - **`.complete(target) -> PixieContext`** — `make_context` then
+    `ctx.pxe_complete(self)` (disarms every `dhcpzone.dhcpservers`). Fires
+    `StartPixieComplete` / `EndPixieComplete`.
+  - **`.VERSION`** — class attr, `netboot.__version__` at class-definition time.
+
+- **`PixieEvent`** (`StrEnum`) — hook event names: `NewPixieObject`,
+  `StartPixieInit`, `SetPixieProperty`, `PixieInitiated`, `LookupTarget`,
+  `FoundTarget`, `FoundTargetImage`, `FoundTargetDhcpzone`,
+  `PixieContextForTarget`, `StartPixieInitialize`, `EndPixieInitialize`,
+  `StartPixieComplete`, `EndPixieComplete`.
+
+- **`PixieTarget(**kwargs)`** (`argparse.Namespace` + `yaconfiglib.OpaqueMerge`)
+  — `_id`, `hostname`, `ip` (`IPAddress`), `mac` (`MACAddress`), `image`,
+  `dhcpzone`, `globals` (`dict`), `template_path` (`list[str | Path]`).
+  Construction fills gaps: a MAC-shaped `_id` with no explicit `mac` is
+  adopted as the MAC (else `mac` defaults to the null MAC
+  `00:00:00:00:00:00`); if `ip`/`hostname` are missing, resolves `hostname`
+  via reverse/forward DNS lookup (`netboot._netutils.nslookup`) or infers
+  `hostname`/`ip` from `_id` when it looks like one; `hostname` is
+  lower-cased. Requires the `dns` extra for hostname resolution to actually
+  find an IP (silently yields empty otherwise).
+
+- **`PixieImage(**kwargs)`** (`content.Resource`) — `template_path`,
+  `globals`. **`.match(name: str, check: str)`** — override point for custom
+  image-selection logic; default is `name == check`. Returning a comparable
+  (e.g. `int`) instead of a bare bool lets `Pixie.lookup_image` prefer the
+  best of several matches.
+
+- **`PixieContext(**kwargs)`** (`argparse.Namespace`) — built by
+  `Pixie.make_context`, not constructed directly. Fields: `target`, `image`,
+  `dhcpzone`, `repos` (`dict[str, Repository]`), `resources`
+  (`dict[str, Resource]`), `generated` (`datetime`, set at construction),
+  `version` (`str`), `templates`, `_renderer` (a `templates.Renderer`).
+  - **`.render(filename: str, strict=True) -> str | None`** — render a
+    template found by name/suffix search (see `templates.Loader` below)
+    against this context. `strict=True` (default) re-raises render errors;
+    `strict=False` logs at DEBUG and returns `None`.
+  - **`.resource(name: str | Resource, service: str = None) -> UriPath | None`**
+    — resolve a resource (by id, looked up in `.resources`, or a `Resource`
+    directly) to a fetchable URI via its repo's `service`. `None` if the repo
+    or resource can't be found.
+  - **`.resource_repo(name: str) -> Repository | None`** — the `Repository`
+    backing resource `name`.
+  - **`.searchpaths -> list[Path]`** — `target.template_path + image.template_path`,
+    consulted (before the engine-wide `config["templates"]`) when resolving a
+    template name.
+  - **`.pxe_init(netboot) -> Self`** / **`.pxe_complete(netboot) -> Self`** —
+    arm/disarm every `dhcpzone.dhcpservers` for this context; called by
+    `Pixie.initialize`/`.complete`, not usually invoked directly.
+
+## DHCP (`netboot.dhcp`)
+
+- **`DhcpServer(uri: str)`** — base class for DHCP backends, dispatched by
+  URI scheme: `DhcpServer("dnsmasq://...")` returns an instance of whichever
+  registered subclass has a matching lowercased class name (any subclass
+  depth, so a plugin may subclass an intermediate base). Raises `ValueError`
+  if no subclass matches the scheme — import the plugin module first (e.g.
+  via CLI `--load-module`). `.uri` holds the original URI.
+  - **`.add_target(ctx: PixieContext)`** / **`.remove_target(ctx)`** — no-ops
+    on the base class; a backend overrides these to actually arm/disarm.
+- **`DhcpZone(**kwargs)`** (`Namespace` + `OpaqueMerge`) — `network`
+  (`IPNetwork`), `gateway` (`IPAddress | None`), `domain` (`str | None`),
+  `search` (`list[str]`), `nameservers` (`list[IPAddress]`), `globals`,
+  `dhcpservers` (`list[DhcpServer]`, strings coerced via `DhcpServer(uri)`).
+  Accepts `gateway`+`netmask`, or a CIDR `network`/`gateway` string, and
+  derives the rest. **`.nameserver`** — first of `.nameservers`, or `""`.
+  **`.get_local_server(servers, default)`** — first `server` contained in
+  `.network`, else `default`.
+
+## Content (`netboot.content`)
+
+- **`Resource(**kwargs)`** — `path` (`Pathname`, coerced via `_parse_path`),
+  `src` (repo id string). `resource / "sub"` joins the path, same `src`.
+- **`Repository(**kwargs)`** — `address` (`Host`), `services`
+  (`dict[str, UriPath]`), `local` (`UriPath | None`, a filesystem/local
+  service). `repo / "sub"` (`.joinpath`) returns a **new** `Repository` with
+  every service (and `.local`) suffixed by `sub` — the original is untouched.
+  **`.get(*path, service=None) -> UriPath | None`** — join `path` onto the
+  named service's base URI (`service=None` → `.local`, scheme `"file"`);
+  `None` if that service isn't defined. **`.service(name) -> UriPath | None`**
+  — the base URI for `name` (host filled in from `.address.try_ip()` for
+  non-local services). `repo[path, service]` is sugar for `.get(path, service=service)`.
+
+## Templates (`netboot.templates`)
+
+- **`Loader(searchpaths, template_types=(JinjaTemplate, ShellTemplate))`** — a
+  Jinja2 `BaseLoader`. Resolves a template name against
+  `ctx.searchpaths + searchpaths` (context-specific paths first), trying each
+  name `ctx._template_names(...)` yields (MAC, hostname, IP, then the bare
+  suffix — first existing file wins) before falling back to the next search
+  path. A name may carry `k=v;flag:` options before the final `:` (parsed but
+  not currently consulted by name selection). Picks the first
+  `template_types` entry whose `.can_process(path, source)` is true; raises
+  `jinja2.TemplateNotFound` if nothing matches, or a plain `Exception` if a
+  matching type has no usable engine.
+- **`Renderer`** — alias for `jinja2.Environment`; one is created per
+  `PixieContext` (never share one across contexts — `globals["ctx"]` is
+  mutated per render).
+- **`Template`** — minimal base (`.render(**globals)`, classmethod
+  `.can_process(file, template) -> bool`, both no-ops/`False` on the base).
+- **`JinjaTemplate`** (`.j2`/`.jinja`/`.jinja2` suffix) — a real
+  `jinja2.Template`; `.render()` additionally injects `shell_quote`, `Path`
+  (`pathlib.Path`) and `Uri` (`pathlib_next.uri.UriPath`) into the render
+  globals.
+- **`ShellTemplate`** (matches any suffix — keep it **last** in
+  `template_types`) — `string.Template` with `%`-delimited placeholders;
+  `.render()` flattens the context (`utils.flatten`, keys joined with `_`,
+  list items by index) into `UPPERCASE` substitution variables (`None` → `""`,
+  `bool` → `"true"`/`"false"`).
+
+## Utils (`netboot.utils`)
+
+- **`Namespace`** (`netboot.utils.config`) — `yaconfiglib.TypedNamespace` +
+  `OpaqueMerge`; the shared base for netboot's config objects (applies
+  `_parse_<prop>` coercers at construction, and marks the built object as
+  merge-opaque — a later config layer replaces it wholesale rather than
+  merging field-by-field).
+- **`Host(address: str | Host | None = None)`** — a hostname-or-IP repo
+  address. **`.try_ip() -> IPAddress | str`** — resolves to an `IPAddress`
+  (IP literal as-is, hostname via DNS — needs the `dns` extra); falls back to
+  the original string on resolution failure. Equality/hash by `.address`.
+- **`flatten(map, _prefix="") -> dict`** — recursively flattens a
+  dict/`Namespace`/list into a single-level dict, joining keys with `_`
+  (`{"a": {"b": 1}}` → `{"a_b": 1}`) and using list indices as keys.
+- **`shell_quote(text: str | list[str], quote='"') -> list[str]`** — wrap each
+  string in `quote`; always returns a list, even for a single string input.
+- **`arr_get(arr, pos, default=None)`** — `arr[pos]` or `default` if out of
+  range.
+- **`import_(name: str) -> object`** — import `"pkg.mod.attr"` and return
+  `attr` (splits on the last dot).
+- **IP/MAC re-exports** (from the vendored `netboot._netutils`, also available
+  as `netboot.utils.net.*`): `IPAddress`, `IPInterface`, `IPNetwork` (factories
+  over stdlib `ipaddress`; `IPNetwork` defaults `strict=False`), `parse_ip`/
+  `parse_network` (tolerate `None`/empty → `None`), `is_valid_ip` (never
+  raises), `MACAddress` (accepts colon/hyphen/Cisco-dot/bare textual forms,
+  int, or bytes; `.as_str(sep)`, `.packed`, hashable/comparable),
+  `active_nic_addresses`, `ping`, `nslookup` (needs the `dns` extra; always
+  returns a `list`, empty on any failure, never `None`). `netboot._netutils` is
+  a private, in-tree module — import these names via `netboot.utils` /
+  `netboot.utils.net`, not the private path directly.
+
+## Logging (`netboot.logging`)
+
+- **`LOGGER`** — the `"NETBOOT"` logger. Importing this module also quiets
+  `urllib3.connectionpool` / `paramiko.transport` to `WARNING` and disables
+  urllib3's insecure-request warning, best-effort, without importing those
+  libraries itself.
+
+## CLI driver (`netboot.main`)
+
+Thin driver over `duho.app`; `duho` owns command discovery, parser build,
+config/env layering and parsing. Netboot overrides only *dispatch*: it loads
+the layered YAML config into one `Pixie` object, then runs the selected
+command against it.
+
+- **`main(name=None, argv=None) -> int`** — build the app, parse `argv`,
+  dispatch. `name` defaults to `"pixie"` — the CLI's identity: it is the prog
+  name **and** the `duho.env.Env` prefix, so `PIXIE_<KEY>` env vars (and an
+  optional `pixie_env` companion module of defaults, autoloaded from
+  `sys.path`/CWD) supply app settings; the resolved `Env` is attached to the
+  dispatched instance as `_env_`. The `netboot` name is only the
+  library/import package. This is the console-script
+  (`pixie = netboot.main:main`) and `python -m netboot` entry point.
+- **`PixieArgs`** (`duho.LoggingArgs` mixin) — the global CLI fields:
+  `config` (`-c/--config`), `baseconfig` (default `./config`), `load_module`
+  (`-l/--load-module`, repeatable, colon-extendable), `cmdspath`
+  (`--cmdspath`, repeatable, `os.pathsep`-extendable).
+- **`Pixie_`** (`PixieArgs` + `duho.Cli`) — the runnable app root;
+  `_version_` is `netboot.__version__`.
+- **`parse_path(path: str | Path) -> Path`** — a bare path → `LocalPath`; a
+  path containing `:` (a URI scheme) → `UriPath`.
+- Command-module contract (built-ins in `netboot.cmds`; discovered the same
+  way via `--cmdspath` / `PIXIE_CMDS_PATH`, `os.pathsep`-separated): a module
+  exposing `register(parser, args)` (add its argparse arguments) and
+  `run(netboot: Pixie, args, conf: dict) -> int | None` (`conf` is the raw
+  merged config dict, deep-copied before `Pixie` construction). A later
+  command source wins on a name clash. A module whose `run` does **not**
+  accept at least 3 positional params (no netboot-first signature) is instead
+  dispatched through plain `duho.run_command(command, instance)`.
+- Loading the config (`-c/--config`, else `<baseconfig>/pixie.yaml`) requires
+  the `config` extra (`pyyaml`); raises `ImportError` with an install hint
+  otherwise. `conf["templates"]` always gets the CWD's `templates` dir
+  prepended.
+
+## Built-in commands (`netboot.cmds`)
+
+- **`initiate <target> [--iscsi]`** — `netboot.lookup_target` then
+  `netboot.initialize(target)`. `--iscsi` is accepted but not yet consumed by
+  the built-in logic (a hook/plugin extension point). Exit 1 if the target
+  isn't found.
+- **`complete <target>`** — `netboot.lookup_target` then
+  `netboot.complete(target)`. Exit 1 if the target isn't found.

netboot/__init__.py

@@ -0,0 +1,394 @@
+import datetime
+import enum as _enum
+import typing as _ty
+from copy import deepcopy
+from pathlib import Path
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    try:
+        __version__ = _pkg_version("netboot")
+    except PackageNotFoundError:  # running from a source tree without install
+        __version__ = "0.0.0"
+except ImportError:  # pragma: no cover - importlib.metadata is stdlib on 3.9+
+    __version__ = "0.0.0"
+
+# Compat: StrEnum introduced in Python 3.11; emulate for older Pythons
+try:
+    from enum import StrEnum
+except ImportError:
+    class StrEnum(str, _enum.Enum):
+        def __str__(self):
+            return self.value
+
+from argparse import Namespace
+from typing import Mapping, get_type_hints, Union
+
+from . import _netutils as netutils
+from pathlib_next.uri.schemes import *  # noqa: F401,F403
+from yaconfiglib import OpaqueMerge
+from yaconfiglib import typed_merge as mergeObjects
+
+from .content import Repository, Resource
+from .dhcp import DhcpZone
+from .logging import LOGGER
+from .templates import Loader, Renderer
+from .utils import IPAddress, MACAddress, T
+from .utils.misc import import_
+
+
+class PixieTarget(Namespace, OpaqueMerge):
+    _id: str
+    hostname: str
+    ip: IPAddress
+    mac: MACAddress
+    image: str
+    dhcpzone: str
+    globals: dict
+    template_path: list[Union[str, Path]]
+
+    #: MAC value treated as "unset" (a target keyed by hostname/IP has no MAC).
+    _NULL_MAC = "00:00:00:00:00:00"
+
+    def __init__(self, **kwargs) -> None:
+        for prop, key in {
+            "dhcpzone": "",
+            "mac": "",
+            "ip": "",
+            "image": "",
+            "hostname": "",
+            "template_path": [],
+        }.items():
+            kwargs.setdefault(prop, key)
+        super().__init__(**kwargs)
+        # If no MAC was given but the id itself is a MAC, adopt it; otherwise
+        # fall back to the null MAC so downstream `.mac` is always a MACAddress.
+        if not self.mac or str(self.mac) == self._NULL_MAC:
+            if MACAddress._VALID_MAC.match(str(self._id)):
+                self.mac = self._id
+            else:
+                self.mac = self._NULL_MAC
+        if not isinstance(self.mac, MACAddress):
+            self.mac = MACAddress(self.mac)
+        resolve = not self.ip or not self.hostname
+        while resolve:
+            resolve = False
+            not_mac = not MACAddress._VALID_MAC.match(self._id)
+            id_is_ip = netutils.is_valid_ip(self._id)
+            if not self.ip and self.hostname:
+                _resolved = netutils.nslookup(self.hostname)
+                if _resolved:
+                    self.ip = _resolved[0]
+                resolve = True
+            if not self.ip and id_is_ip:
+                self.ip = self._id
+                resolve = True
+            if not self.hostname and not_mac and not id_is_ip:
+                self.hostname = self._id
+                resolve = True
+        if self.ip:
+            self.ip = netutils.parse_ip(self.ip)
+        self.hostname = self.hostname.lower()
+
+
+class PixieImage(Resource):
+    template_path: list["Path"]
+    globals: dict
+
+    def match(self, name: str, check: str):
+        return name == check
+
+
+class PixieContext(Namespace):
+    target: PixieTarget
+    image: PixieImage
+    dhcpzone: DhcpZone
+    repos: dict[str, Repository]
+    generated: datetime.datetime
+    resources: dict[str, Resource]
+    version: str
+    templates: list[Union[str, Path]]
+    _renderer: Renderer
+
+    def __init__(self, **kwargs) -> None:
+        self.dhcp_server = None
+        self.generated = datetime.datetime.now()
+        super().__init__(**kwargs)
+
+    def init(self, netboot: "Pixie"): ...
+
+    def resource(self, name: Union[str, Resource], service: str = None):
+        if isinstance(name, Resource):
+            repo = self.repos.get(name.src, None)
+            path = name.path
+        else:
+            path = None
+            repo = self.resource_repo(name)
+        if not repo:
+            return
+        if not path:
+            path = self.resources[name].path
+        return repo.get(path, service=service)
+
+    def resource_repo(self, name: str):
+        resource = self.resources.get(name)
+        if not resource:
+            return
+        return self.repos.get(resource.src)
+
+    def pxe_init(self, config: "Pixie"):
+        for dhcpserver in self.dhcpzone.dhcpservers:
+            dhcpserver.add_target(self)
+        return self
+
+    def pxe_complete(self, config: "Pixie"):
+        for dhcpserver in self.dhcpzone.dhcpservers:
+            dhcpserver.remove_target(self)
+        return self
+
+    def _template_names(self, suffix: Union[list[str], str], **options) -> list[str]:
+        # ``options`` (a ``k=v:name`` template spec) is accepted for forward
+        # compatibility; name selection does not use it today.
+        suffixes = suffix if isinstance(suffix, list) else [suffix]
+        ip = self.target.ip
+        # Skip an unset/unspecified IP so it never yields a spurious name.
+        ip_name = str(ip) if ip and str(ip) not in ("0.0.0.0", "::") else ""
+        names = []
+        for version in [
+            self.target.mac.as_str("-"),
+            self.target.hostname,
+            ip_name,
+        ]:
+            if version:
+                for suffix in suffixes:
+                    names.append(f"{version}.{suffix}")
+        for suffix in suffixes:
+            names.append(suffix)
+
+        return names
+
+    @property
+    def searchpaths(self) -> list[Path]:
+        return [*self.target.template_path, *self.image.template_path]
+
+    def render(self, filename: str, strict=True):
+        # Each PixieContext owns its own Renderer (built in make_context), so
+        # setting globals["ctx"] here is per-context; do not share one Renderer
+        # across contexts or nested renders would clobber this.
+        self._renderer.globals["ctx"] = self
+        try:
+            template = self._renderer.get_template(filename)
+            return template.render()
+        except Exception as e:
+            if strict:
+                raise e
+            else:
+                LOGGER.debug(
+                    f"While rendering [{filename}] encountered an exeption:\t{repr(e)}"
+                )
+                return None
+
+
+class PixieEvent(StrEnum):
+    NewPixieObject = "PixieEvent.NewPixieObject"
+    StartPixieInit = "PixieEvent.StartPixieInit"
+    SetPixieProperty = "PixieEvent.SetPixieProperty"
+    PixieInitiated = "PixieEvent.PixieInitiated"
+    LookupTarget = "PixieEvent.LookupTarget"
+    FoundTarget = "PixieEvent.FoundTarget"
+    FoundTargetImage = "PixieEvent.FoundTargetImage"
+    FoundTargetDhcpzone = "PixieEvent.FoundTargetDhcpzone"
+    PixieContextForTarget = "PixieEvent.PixieContextForTarget"
+    StartPixieInitialize = "PixieEvent.StartPixieInitialize"
+    EndPixieInitialize = "PixieEvent.EndPixieInitialize"
+    StartPixieComplete = "PixieEvent.StartPixieComplete"
+    EndPixieComplete = "PixieEvent.EndPixieComplete"
+
+
+_PixieHook = _ty.Callable[["PixieEvent", "Pixie", T, dict], T]
+
+
+class Pixie:
+    targets: "dict[str,PixieTarget]"
+    dhcpzones: "dict[str,DhcpZone]"
+    images: "dict[str, PixieImage]"
+    repos: "dict[str,Repository]"
+    globals: dict[str, object]
+    _ctxcls: PixieContext = PixieContext
+    VERSION = __version__
+    _config: dict
+    _hooks: list[_PixieHook] = []
+
+    def hook(
+        self: "Pixie|_ty.Sequence[_PixieHook]",
+        event: PixieEvent,
+        __value: T = None,
+        /,
+        **kwargs,
+    ):
+        LOGGER.debug(f"Running Hooks for: {event}")
+        if isinstance(self, Pixie):
+            netboot = self
+            hooks = self._hooks
+        else:
+            netboot = None
+            hooks = self
+        for hook in hooks:
+            __value = hook(event, netboot, __value, kwargs)
+        return __value
+
+    def __new__(
+        cls,
+        /,
+        hooks: _ty.Sequence[_PixieHook] = [],
+        **config,
+    ):
+
+        hooks = [(hook if callable(hook) else import_(hook)) for hook in hooks]
+        cls = Pixie.hook(hooks, PixieEvent.NewPixieObject, cls, config=config)
+        inst = object.__new__(cls)
+        inst._hooks = hooks
+        return inst
+
+    def __init__(
+        netboot,
+        /,
+        **config,
+    ):
+        netboot._config = netboot.hook(PixieEvent.StartPixieInit, config)
+        netboot.globals = deepcopy(config.get("globals") or {})
+        defaults = config.get("defaults") or {}
+
+        for prop, hint in get_type_hints(netboot.__class__).items():
+            if prop.startswith("_"):
+                continue
+            origin = _ty.get_origin(hint) or hint
+            value = config.get(prop)
+            prop_defaults = defaults.get(prop)
+            if issubclass(origin, dict):
+                value: dict[str] = value or {}
+                _keycls, _valcls = _ty.get_args(hint)
+                _value = {}
+                if _valcls is object:
+                    _valctr = lambda _id, val: val
+                else:
+
+                    def _valctr(_id, val):
+                        val = val if isinstance(val, Mapping) else val.__dict__
+                        if prop_defaults:
+                            _val = deepcopy(prop_defaults)
+                            _val.update(val)
+                            val = _val
+                        try:
+                            return _valcls(_id=_id, **val)
+                        except TypeError:
+                            # _valcls doesn't accept an _id kwarg; build without.
+                            return _valcls(**val)
+
+                for uid, val in value.items():
+                    if not str(uid).startswith("_"):
+                        _value[_keycls(uid)] = _valctr(uid, val)
+            else:
+                _value = hint(value) if value is not None else None
+            prop, value = netboot.hook(
+                PixieEvent.SetPixieProperty, (prop, _value), origin=origin, rawvalue=value
+            )
+            setattr(netboot, prop, value)
+
+        netboot.hook(PixieEvent.PixieInitiated)
+
+    def lookup_target(self, target: str) -> PixieTarget:
+        target: Union[str, PixieTarget] = self.hook(PixieEvent.LookupTarget, target)
+        if isinstance(target, str):
+            lower: str = target.lower()
+            _target = self.targets.get(target, None)
+            if _target is None:
+                for _target in self.targets.values():
+                    if (
+                        _target.hostname.lower().startswith(lower)
+                        or _target.mac.as_str() == lower
+                        or str(_target.ip) == lower
+                    ):
+                        target = _target
+                        break
+
+            else:
+                target = _target
+
+        target = self.hook(PixieEvent.FoundTarget, target)
+        if not isinstance(target, PixieTarget):
+            target = None
+        return target
+
+    def lookup_image(self, name: str, target: PixieTarget = None) -> PixieImage:
+        imgs: list[tuple[int, PixieImage]] = [(-1, {})]
+        for img_name, image in self.images.items():
+            check = image.match(img_name, name)
+            if check != False:
+                imgs.append((check, image))
+        imgs.sort(key=lambda x: x[0])
+        return self.hook(PixieEvent.FoundTargetImage, imgs.pop()[1], target=target)
+
+    def lookup_dhcpzone(self, name: str, target: PixieTarget = None) -> DhcpZone:
+        if not name and target:
+            if target.dhcpzone:
+                name = target.dhcpzone
+            else:
+                for zone_id, zone in self.dhcpzones.items():
+                    if target.ip in zone.network:
+                        name = zone_id
+                        target.dhcpzone = zone_id
+                        break
+        zone = self.dhcpzones.get(name, None)
+        return self.hook(PixieEvent.FoundTargetDhcpzone, zone, target=target)
+
+    def make_context(
+        self, target: "PixieTarget", globals: list[dict] = None
+    ) -> PixieContext:
+        image = self.lookup_image(target.image, target)
+        if not image:
+            raise Exception(f"Image not found for target: {target.image}")
+        LOGGER.info(f"Found target image: {target.image}")
+
+        zone = self.lookup_dhcpzone(target.dhcpzone, target)
+        if not zone:
+            raise Exception(
+                f"Not supported client due to missing subnet: {target.dhcpzone}"
+            )
+        LOGGER.info(f"Found target dhcpzone: {target.dhcpzone}")
+
+        ctx = {
+            "image": image,
+            "dhcpzone": zone,
+            "target": target,
+            "repos": self.repos,
+            "resources": {},
+        }
+        # Collect object-level globals to layer into the context WITHOUT mutating
+        # the shared image/dhcpzone/target objects (they are reused across
+        # targets, so deleting their `globals` would drop them for later calls).
+        _globals = [self.globals, *(globals or [])]
+        for k in ["image", "dhcpzone", "target"]:
+            g = getattr(ctx[k], "globals", None)
+            if g:
+                _globals.append(g)
+
+        ctx = mergeObjects(self._ctxcls, ctx, *_globals)
+
+        ctx: PixieContext
+        ctx._renderer = Renderer(loader=Loader(self._config.get("templates", [])))
+        ctx.version = f"netboot-v{self.VERSION}"
+        return self.hook(PixieEvent.PixieContextForTarget, ctx, target=target)
+
+    def initialize(self, target: "PixieTarget"):
+        target = self.hook(PixieEvent.StartPixieInitialize, target)
+        ctx = self.make_context(target)
+        ctx = ctx.pxe_init(self)
+        return self.hook(PixieEvent.EndPixieInitialize, ctx)
+
+    def complete(self, target: "PixieTarget"):
+        target = self.hook(PixieEvent.StartPixieComplete, target)
+        ctx = self.make_context(target)
+        ctx = ctx.pxe_complete(self)
+        return self.hook(PixieEvent.EndPixieComplete, ctx)

netboot/__main__.py

@@ -0,0 +1,4 @@
+from .main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())