simplon 0.1.0__py3-none-any.whl

simplon/__init__.py

@@ -0,0 +1,11 @@
+"""simplon - the delivery orchestrator kernel, the domain-agnostic shared core for the *ctl
+product family (netctl, infractl).
+
+A product installs `simplon` (PyPI) and pins it in its own requirements: the kernel arrives as an
+ordinary dependency, nothing is vendored and no source path is prepended. NOTE: the import package is
+deliberately `simplon`, not `platform` (a top-level `platform` package would shadow the Python stdlib
+`platform` module) and not bare `orchestrator` (collides with product packages).
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

simplon/allure.py

@@ -0,0 +1,100 @@
+"""Allure + pytest test-report primitives for the *ctl orchestrators (netctl#730, extracted from netctl's
+orchestrator testrun).
+
+The mechanics of the merged single-file Allure report - the timestamped archive name, the pytest argv
+that emits raw allure results + a machine-readable junit.xml, the per-module result merge that tags a
+parent suite, and the render of the merged single-file HTML - are product-agnostic. A product keeps its OWN
+suite wiring (which modules, which gradle tasks, which lab waits) and calls these to produce/merge/render
+the report. No product knowledge, so both netctl and infractl reuse them.
+
+Everything here is pure + filesystem-only EXCEPT `render_report`, which shells out to the allure CLI (else
+docker). It lives here rather than beside the caller because it is allure mechanism through and through and
+because it composes `report_filename` (netctl#1406, moved out of netctl's orchestrator.testrun).
+"""
+from __future__ import annotations
+
+import glob
+import json
+import os
+import shutil
+from datetime import datetime
+
+from simplon import log
+from simplon.run import run
+
+
+def report_filename(now: datetime | None = None, *, prefix: str = "allure") -> str:
+    """The archived single-file report name for a run: ``<prefix>-YYYYMMDD-HHMMSS.html`` (netctl#402). Pure
+    and now-injectable so the timestamped naming is unit-tested without invoking allure or the wall clock."""
+    return f"{prefix}-{(now or datetime.now()):%Y%m%d-%H%M%S}.html"
+
+
+def integration_pytest_argv(py: str, results: str, junit: str, extra: list[str]) -> list[str]:
+    """The integration pytest argv: allure raw results + a small machine-readable junit.xml, and NO
+    pytest-html (netctl#402 dropped --html/--self-contained-html; the single-file allure report supersedes
+    the per-suite report.html). Pure so the flag set is locked by a unit test; ``extra`` is appended
+    verbatim (e.g. a caller's -k filter)."""
+    return [py, "-m", "pytest", f"--alluredir={results}", f"--junit-xml={junit}", *extra]
+
+
+def merge_results(dst: str, srcs: list[str], *, parent_suite: str = "Unit") -> None:
+    """Copy each source dir's allure result files into ``dst``, tagging every ``*-result.json`` with
+    ``parentSuite=<parent_suite>`` unless already labelled (so a merged report groups a module's results
+    under one suite). Non-result files are copied through unchanged. Ported from the inline python in
+    netctl's run_unit_tests."""
+    os.makedirs(dst, exist_ok=True)
+    for src in srcs:
+        if not os.path.isdir(src):
+            continue
+        for f in glob.glob(os.path.join(src, "*")):
+            base = os.path.basename(f)
+            if base.endswith("-result.json"):
+                with open(f, encoding="utf-8") as fh:
+                    r = json.load(fh)
+                labels = r.setdefault("labels", [])
+                if not any(l.get("name") == "parentSuite" for l in labels):
+                    labels.append({"name": "parentSuite", "value": parent_suite})
+                with open(os.path.join(dst, base), "w", encoding="utf-8") as fh:
+                    json.dump(r, fh)
+            else:
+                shutil.copy(f, os.path.join(dst, base))
+
+
+def render_report(report_dir: str, results: str | None = None, *, prefix: str = "allure") -> None:
+    """Render the merged single-file allure HTML to a timestamped ``report_dir/<prefix>-YYYYMMDD-HHMMSS.html``
+    (netctl#402) via the local allure CLI, else docker. ``results`` defaults to ``report_dir/allure-results``;
+    a caller running an EXPLORATORY (argument-filtered) suite passes its own quarantined results dir plus a
+    distinct prefix, so that run's archive can never be mistaken for the canonical one.
+
+    ``allure --single-file`` emits index.html into an output DIR, so the render goes into a transient scratch
+    dir and that one self-contained file is moved out to the dated name; each run thus archives a portable,
+    diffable report (the regression baseline). Never raises: a missing render tool leaves the raw results in
+    place with a hint, because archiving must not itself be the reason a run is red.
+    """
+    results = results or os.path.join(report_dir, "allure-results")
+    scratch = os.path.join(report_dir, "allure-report")   # transient allure -o dir (holds the single index.html)
+    report = os.path.join(report_dir, report_filename(prefix=prefix))
+    if shutil.which("allure") is not None:
+        log.info("generating allure HTML report (local CLI, single-file)")
+        ok = run(["allure", "generate", "--single-file", "--clean", results, "-o", scratch]).ok
+        if not ok:
+            log.warn(f"allure generate failed; use: allure serve '{results}'")
+            return
+    elif shutil.which("docker") is not None:
+        log.info("no local allure CLI; rendering the allure HTML report via docker (single-file)")
+        ok = run(["docker", "run", "--rm", "-v", f"{report_dir}:/work", "-w", "/work", "--entrypoint", "allure",
+                  "frankescobar/allure-docker-service", "generate", "--single-file", "--clean",
+                  os.path.join("/work", os.path.relpath(results, report_dir)), "-o", "/work/allure-report"]).ok
+        if not ok:
+            log.warn(f"docker allure render failed; use: allure serve '{results}'")
+            return
+    else:
+        log.info("install allure (your product's `install` command, or 'brew install allure') for the report")
+        return
+    index = os.path.join(scratch, "index.html")
+    if os.path.isfile(index):
+        shutil.move(index, report)
+        shutil.rmtree(scratch, ignore_errors=True)
+        log.ok(f"allure HTML report: {report}")
+    else:
+        log.warn(f"allure produced no {index}; raw results left at {results}")

simplon/awake.py

@@ -0,0 +1,66 @@
+"""Keep the host awake for the duration of a long lab/build run (netctl#546, extracted to the delivery
+kernel in netctl#592 Train B).
+
+A full `build`/`up`/`seed`/`monitor accept` cycle runs for tens of minutes with no keypress; on a laptop
+the host then idle-sleeps mid-run, dropping the Colima VM / SSH channel and wedging the pipeline. This
+wraps those long commands in a context manager that inhibits idle sleep while they run and lets the host
+sleep normally again on exit. Product-agnostic: any *ctl orchestrator with multi-minute commands reuses it.
+
+The OS decision is a PURE helper (`_keep_awake_argv`) so it is unit-tested without spawning anything: on
+macOS it yields `caffeinate -dimsu` (prevent display/idle/system/disk sleep + keep-awake on AC and
+battery), on Linux/other it yields a `systemd-inhibit --what=idle` wrapper around a blocking `sleep`, and
+where neither applies it yields None (no-op). The context manager is STRICTLY best-effort: a missing or
+failing inhibitor logs a WARNING and continues - keeping the host awake is a convenience, never a reason
+to fail the actual run.
+"""
+from __future__ import annotations
+
+import contextlib
+import platform
+import subprocess
+from collections.abc import Iterator
+
+from simplon import log
+
+__all__ = ["keep_awake"]
+
+
+def _keep_awake_argv(os_name: str) -> list[str] | None:
+    """PURE: the argv of a long-lived process that inhibits host idle-sleep on `os_name`, or None when
+    there is nothing sensible to spawn.
+
+    macOS (`Darwin`) -> ``caffeinate -dimsu``: -d display, -i idle system sleep, -m disk idle, -s system
+    sleep on AC, -u declare user active. It runs until killed, which is exactly the enter/exit lifetime.
+    Linux -> ``systemd-inhibit --what=idle sleep infinity``: holds an idle inhibitor lock for its own
+    lifetime; killed on exit. Anything else -> None (no-op)."""
+    if os_name == "Darwin":
+        return ["caffeinate", "-dimsu"]
+    if os_name == "Linux":
+        return ["systemd-inhibit", "--what=idle", "--why=netctl lab/build run", "sleep", "infinity"]
+    return None
+
+
+@contextlib.contextmanager
+def keep_awake() -> Iterator[None]:
+    """Inhibit host idle-sleep for the duration of the `with` block; restore normal sleep on exit.
+
+    Best-effort by contract: if the platform has no inhibitor, or spawning it fails (binary missing,
+    permission), it logs a WARNING and yields anyway - a long run never fails because the host could not
+    be kept awake. The inhibitor process is always terminated in the `finally`, so sleep is re-enabled the
+    moment the wrapped command returns (or raises)."""
+    argv = _keep_awake_argv(platform.system())
+    proc: subprocess.Popen | None = None
+    if argv is not None:
+        try:
+            proc = subprocess.Popen(argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            log.info(f"keeping the host awake for this run ({argv[0]})")
+        except (OSError, ValueError) as exc:
+            log.warn(f"could not keep the host awake ({argv[0]}: {exc}); the run may be interrupted by idle-sleep")
+            proc = None
+    try:
+        yield
+    finally:
+        if proc is not None:
+            proc.terminate()
+            with contextlib.suppress(subprocess.TimeoutExpired):
+                proc.wait(timeout=5)

simplon/backend.py

@@ -0,0 +1,59 @@
+"""Backend - a deployment backend as a polymorphic object, not a dispatched string (netctl#735).
+
+An environment names HOW it is realised through its `backend` tag (a local lab, a cloud provider, ...).
+Everywhere else the delivery kernel is deliberately functional - stateless ops are functions - but the
+backend is the ONE axis that is genuinely meant to be extended, and switching on the tag
+(`if backend == "local": ... elif backend == "exoscale": ...`) across the deploy/destroy/status paths is
+the classic non-polymorphic smell exactly there. So the kernel keeps backend SELECTION polymorphic: a
+product registers one `Backend` implementation per backend name and `resolve` maps an `Environment` to that
+INSTANCE. Adding or extending a backend is then a new class, never a new `if`.
+
+This mirrors the kernel's other product seams (`ProductContext`, the `EnvironmentProvider` Protocol): the
+Protocol lives here, the concrete implementations live in the PRODUCT (netctl's `LocalBackend` for
+containerlab, its `ExoscaleBackend` skeleton, ...). The coupling flows product -> kernel, never the reverse:
+this module names no backend and no product, so a second consumer (infractl) registers its own backends
+against the same seam ("gleiche Maschine, anderer Katalog").
+"""
+from __future__ import annotations
+
+from typing import Mapping, Protocol, runtime_checkable
+
+from simplon.environments import Environment
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """One deployment backend: the object a product registers per `backend:` tag. Structural, so a
+    product's implementation need not import or subclass anything named here - any object exposing these
+    members satisfies it.
+
+    ``name`` is the backend tag it answers to (the `backend:` value in the env matrix); it MUST equal the
+    key the product registers the instance under, so `resolve` and the product's env-gate can identify it.
+    ``deploy``/``destroy``/``status`` are the environment lifecycle a CD command drives against ONE target
+    ``Environment``: deploy/destroy return a process return code (for the caller's exit), status returns the
+    rendered status report. An unbuilt op raises ``NotImplementedError`` so a half-scaffolded backend fails
+    loud instead of silently mis-running another backend's path.
+    """
+
+    name: str
+
+    def deploy(self, env: Environment) -> int: ...
+    def destroy(self, env: Environment) -> int: ...
+    def status(self, env: Environment) -> str: ...
+
+
+def resolve(env: Environment, backends: Mapping[str, Backend]) -> Backend:
+    """Resolve an environment to its `Backend` INSTANCE by the env's backend tag - the polymorphic
+    replacement for `if env.backend == ...` dispatch. ``backends`` is the product-supplied registry (tag ->
+    instance); the kernel names no backend. Fails loud (a `ValueError` naming the tag and the known
+    backends) when a manifest env references a backend with no registered implementation, so the mistake
+    dies here at selection time, not deep inside a deployment - the same fail-loud discipline as
+    `environments.parse`.
+    """
+    try:
+        return backends[env.backend]
+    except KeyError:
+        known = ", ".join(sorted(backends)) or "(none registered)"
+        raise ValueError(
+            f"environment '{env.name}': no backend registered for '{env.backend}' (known: {known})"
+        ) from None