docs(examples): runnable, CI-guarded programs for each target niche

Author: ZelAnton

CHANGELOG.md

@@ -159,6 +159,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   x86_64 musllinux wheels on every push (aarch64 builds natively at release).
 - Packaging metadata for the PyPI page: Trove classifiers (CPython 3.10–3.14, the
   supported operating systems, topics) and project URLs (Documentation, Issues).
+- Runnable [`examples/`](examples/) — self-contained, cross-platform programs, one
+  per target niche (whole-tree no-orphan teardown, a readiness-gated server,
+  supervision-until-healthy, a resource-limited sandbox). Each is exercised in CI.
 
 ### Changed
 - Renamed `Command.ok_codes()` → **`success_codes()`** (clearer that it is the

README.md

@@ -170,6 +170,11 @@ to …" tasks to working snippets — then read
 | [Testing your code](docs/testing.md) | The runner seam, scripted/record-replay doubles, `CliClient` |
 | [Platform support](docs/platforms.md) | Mechanisms, all capability matrices, every caveat |
 
+Prefer whole programs to snippets? The **[`examples/`](examples/)** directory has
+runnable, self-contained scripts — one per niche (no-orphan teardown, a
+readiness-gated server, supervision, a resource-limited sandbox). Each runs on
+Windows, Linux, and macOS and is exercised in CI.
+
 ## A tour of the capabilities
 
 Each section below is a taste with a pointer to its full guide.

examples/01_no_orphan_guarantee.py

@@ -0,0 +1,50 @@
+"""No-orphan guarantee: a ProcessGroup reaps a whole tree, grandchildren included.
+
+This is the core reason processkit exists. We start two children that each spawn
+a *grandchild*; a naive ``subprocess`` call tracks only the direct child, so the
+grandchildren would outlive a timeout, an exception, or a cancelled task. Inside
+a ``ProcessGroup``, leaving the ``with`` block tears the entire tree down in one
+kernel operation — a Windows Job Object, a Linux cgroup v2, or a POSIX process
+group.
+
+Run it:  python examples/01_no_orphan_guarantee.py
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+from processkit import Command, ProcessGroup
+
+# A child that spawns a detached grandchild (a 60-second sleeper) and then sleeps
+# itself. Neither does any real work — they stand in for a build tool's compiler
+# children, a server's workers, or an agent tool's helper processes.
+_CHILD = (
+    "import subprocess, sys, time; "
+    "subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)']); "
+    "time.sleep(60)"
+)
+
+
+def main() -> None:
+    with ProcessGroup() as group:
+        group.start(Command(sys.executable, ["-c", _CHILD]))
+        group.start(Command(sys.executable, ["-c", _CHILD]))
+
+        # Give the children a moment to spawn their grandchildren, then look at
+        # what the kernel container is tracking.
+        time.sleep(0.5)
+        members = group.members()
+        print(f"containment mechanism : {group.mechanism}")
+        print(f"processes in the tree : {len(members)} (PIDs {members})")
+        print("leaving the block - the whole tree is about to be reaped...")
+
+    # Past this line the group is gone: both children AND their grandchildren
+    # have been killed as a unit. No orphan survives — not even the ones we never
+    # held a handle to.
+    print("done - every child and grandchild has been torn down.")
+
+
+if __name__ == "__main__":
+    main()

examples/02_wait_for_server.py

@@ -0,0 +1,69 @@
+"""Start a server, wait until it is ready, use it, then reap the whole tree.
+
+The "start a service, then talk to it" pattern — everywhere in CI orchestration
+and integration tests, and a constant Python pain point (racy ``sleep()`` calls,
+leaked server processes). Here the server runs inside a ``ProcessGroup``, so no
+matter how the block exits — success, exception, or timeout — the server and
+anything it spawned are gone.
+
+``wait_for_port`` replaces the usual ``time.sleep(2)  # hope it's up`` guess with
+an actual readiness check.
+
+Run it:  python examples/02_wait_for_server.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import sys
+import urllib.request
+
+from processkit import Command, ProcessGroup, wait_for_port
+
+HOST = "127.0.0.1"
+
+
+def _free_port() -> int:
+    """Grab a port the OS is not using, so the example never collides with
+    something already listening."""
+    with socket.socket() as sock:
+        sock.bind((HOST, 0))
+        return int(sock.getsockname()[1])
+
+
+def _http_status(url: str) -> int:
+    """A blocking HTTP GET returning the status code — run off the event loop."""
+    with urllib.request.urlopen(url, timeout=5) as response:
+        return int(response.status)
+
+
+async def main() -> None:
+    port = _free_port()
+    async with ProcessGroup() as group:
+        # Python's stdlib HTTP server stands in for your real service. Send its
+        # logs to null: it communicates over the socket, so we don't need them —
+        # and an undrained stdio pipe would otherwise stall a background server.
+        server = (
+            Command(sys.executable, ["-m", "http.server", str(port), "--bind", HOST])
+            .stdout("null")
+            .stderr("null")
+        )
+        await group.astart(server)
+
+        print(f"waiting for the server on {HOST}:{port} ...")
+        await wait_for_port(HOST, port, timeout=10)
+        print("server is accepting connections")
+
+        # urllib is blocking, so run it in a worker thread rather than stalling
+        # the event loop.
+        loop = asyncio.get_running_loop()
+        status = await loop.run_in_executor(None, _http_status, f"http://{HOST}:{port}/")
+        print(f"GET / -> HTTP {status}")
+        print("leaving the block - the server tree is about to be reaped...")
+
+    print("done - the server has been torn down.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/03_supervise_until_healthy.py

@@ -0,0 +1,58 @@
+"""Keep restarting a flaky worker until it comes up healthy.
+
+The supervision pattern for the agent / long-lived-service niche. A worker that
+fails a couple of times before succeeding is restarted with exponential backoff,
+and a ``stop_when`` predicate ends the loop the moment a run succeeds. The
+restart policy, the backoff schedule, and the stop condition are all declarative
+— no hand-rolled retry loop.
+
+Run it:  python examples/03_supervise_until_healthy.py
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from pathlib import Path
+
+from processkit import Command, Supervisor
+
+# A worker that fails its first two runs, then succeeds. It uses a file as an
+# attempt counter that persists across restarts — standing in for a service that
+# needs a dependency (a port, a migration, a mount) to become ready first.
+_WORKER = """
+import os, sys
+path = sys.argv[1]
+attempt = (int(open(path).read()) if os.path.exists(path) else 0) + 1
+open(path, "w").write(str(attempt))
+print(f"worker attempt {attempt}", flush=True)
+sys.exit(0 if attempt >= 3 else 1)
+"""
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        counter = Path(tmp) / "attempts"
+
+        outcome = Supervisor(
+            Command(sys.executable, ["-c", _WORKER, str(counter)]),
+            # Restart after every run; the predicate below decides when we are
+            # actually done (use "on_crash" to restart only on a non-zero exit).
+            restart="always",
+            max_restarts=5,
+            # Small delays so the example finishes quickly; scale these up for a
+            # real service (e.g. 0.5 / 2.0 / 30.0).
+            backoff_initial=0.05,
+            backoff_factor=2.0,
+            max_backoff=1.0,
+            stop_when=lambda result: result.is_success,
+        ).run()  # or: await ...arun()
+
+    print(f"restarts   : {outcome.restarts}")  # 2 — it failed twice first
+    print(f"stopped by : {outcome.stopped}")  # 'predicate' — our stop_when fired
+    print(f"final code : {outcome.final_result.code}")
+    print("healthy" if outcome.final_result.is_success else "gave up")
+
+
+if __name__ == "__main__":
+    main()

examples/04_sandbox_resource_limits.py

@@ -0,0 +1,78 @@
+"""Sandbox an untrusted child tree with kernel-enforced resource limits.
+
+The differentiator versus a plain subprocess wrapper: a ``ProcessGroup`` can cap
+a whole tree's memory, process count, and CPU — enforced by the Windows Job
+Object or a Linux cgroup v2. We also lock the command itself down (empty
+environment, bounded captured output, die-with-parent) so a misbehaving tool
+cannot run away with the machine.
+
+Kernel resource limits need privileges the environment may not grant: inside a
+container, a systemd user session, or a non-root cgroup the kernel forbids them,
+and macOS (a POSIX process group) has no equivalent. processkit is honest about
+this — it raises rather than silently ignoring the cap — so this example catches
+that and degrades to "contained, but uncapped", staying runnable anywhere.
+
+Run it:  python examples/04_sandbox_resource_limits.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from processkit import Command, ProcessGroup, ResourceLimit, Unsupported
+
+_MiB = 1024 * 1024
+
+# A short-lived stand-in for an untrusted tool doing a little work.
+_TOOL = "import time; time.sleep(0.1)"
+
+
+def _locked_down_tool() -> Command:
+    """An untrusted command tied down independently of the group's limits: an
+    empty environment (only PATH allow-listed), a bounded captured output, and
+    kill-on-parent-death so it cannot outlive us even without explicit teardown."""
+    return (
+        Command(sys.executable, ["-c", _TOOL])
+        .env_clear()
+        .inherit_env(["PATH"])
+        .kill_on_parent_death()
+        .output_limit(max_bytes=8 * _MiB)
+    )
+
+
+def _run(
+    *,
+    max_memory: int | None = None,
+    max_processes: int | None = None,
+    cpu_quota: float | None = None,
+) -> None:
+    with ProcessGroup(
+        max_memory=max_memory,
+        max_processes=max_processes,
+        cpu_quota=cpu_quota,
+    ) as group:
+        group.start(_locked_down_tool())
+        print(f"  mechanism           : {group.mechanism}")
+        # Live usage stats are a bonus, not the point — some mechanisms (a POSIX
+        # process group) can't report them, so don't let that mask the sandbox.
+        try:
+            stats = group.stats()
+            print(f"  active processes    : {stats.active_process_count}")
+            print(f"  peak memory (bytes) : {stats.peak_memory_bytes}")
+        except Unsupported:
+            print("  usage stats         : unavailable on this platform")
+
+
+def main() -> None:
+    try:
+        _run(max_memory=512 * _MiB, max_processes=64, cpu_quota=1.0)
+        print("ran the tool under kernel-enforced memory / process / CPU limits.")
+    except (ResourceLimit, Unsupported) as exc:
+        print(f"kernel resource limits are not permitted here: {exc}")
+        print("(typical in containers / non-root cgroups / macOS) - running uncapped.")
+        _run()
+        print("ran the tool contained, but without resource caps.")
+
+
+if __name__ == "__main__":
+    main()

examples/README.md

@@ -0,0 +1,23 @@
+# processkit examples
+
+Runnable, self-contained programs — each maps to one of the niches processkit is
+built for. They use only the standard library plus `processkit`, spawn their own
+child processes (via the running Python), and work the same on Windows, Linux,
+and macOS. Every one is exercised in CI, so they stay current with the API.
+
+Run any of them from the repository root:
+
+```bash
+python examples/01_no_orphan_guarantee.py
+```
+
+| Example | Shows | Niche |
+|---|---|---|
+| [`01_no_orphan_guarantee.py`](01_no_orphan_guarantee.py) | A `ProcessGroup` reaps a whole child→grandchild tree on block exit | The core guarantee |
+| [`02_wait_for_server.py`](02_wait_for_server.py) | Start a server, `await wait_for_port(...)`, make a request, tear the tree down (async) | CI orchestration / integration tests |
+| [`03_supervise_until_healthy.py`](03_supervise_until_healthy.py) | `Supervisor` with restart + backoff + a `stop_when` predicate | Agents / long-lived services |
+| [`04_sandbox_resource_limits.py`](04_sandbox_resource_limits.py) | Memory / process / CPU caps on a locked-down untrusted child | Sandboxing untrusted tools |
+
+For task-sized snippets rather than whole programs, see the
+[cookbook](../docs/cookbook.md); for the full treatment of any area, the
+[guide set](../docs/README.md).

tests/test_examples.py

@@ -0,0 +1,45 @@
+"""Every script under examples/ must run to a clean exit.
+
+These are the programs users copy first, so a broken one is a broken first
+impression — and because they live outside the package, nothing else would catch
+API drift in them. Each runs in a child interpreter (they spawn processes and
+bind ports of their own), so this mirrors exactly what `python examples/<name>.py`
+does for a user.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_EXAMPLES_DIR = Path(__file__).resolve().parent.parent / "examples"
+_EXAMPLES = sorted(_EXAMPLES_DIR.glob("*.py"))
+
+
+def test_examples_directory_is_populated() -> None:
+    # Guard against a false green if the directory moves or the glob breaks:
+    # an empty parametrization would otherwise report zero tests, silently.
+    assert _EXAMPLES, f"no example scripts found under {_EXAMPLES_DIR}"
+
+
+@pytest.mark.parametrize("script", _EXAMPLES, ids=lambda p: p.name)
+def test_example_runs_cleanly(script: Path) -> None:
+    result = subprocess.run(
+        [sys.executable, str(script)],
+        capture_output=True,
+        text=True,
+        timeout=60,
+        check=False,
+    )
+    assert result.returncode == 0, (
+        f"{script.name} exited {result.returncode}\n"
+        f"--- stdout ---\n{result.stdout}\n--- stderr ---\n{result.stderr}"
+    )
+    # A caught-and-handled error is fine (e.g. the sandbox example degrades on a
+    # ResourceLimit); an *un*caught one surfaces as a traceback on stderr.
+    assert "Traceback (most recent call last)" not in result.stderr, (
+        f"{script.name} raised an uncaught exception:\n{result.stderr}"
+    )