processkit-py 1.1.0__tar.gz → 1.2.0__tar.gz

{processkit_py-1.1.0 → processkit_py-1.2.0}/CHANGELOG.md

@@ -16,6 +16,217 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 -
 
+## [1.2.0] - 2026-07-08
+
+### Added
+- `Command.stdout_tee` / `Command.stderr_tee` now accept a **Python writer**
+  object (anything with a callable `write()` — `io.StringIO`, `sys.stderr`, a
+  text-mode file, a logger wrapper) in addition to a file path, mirroring the
+  child's output straight into your own console/buffer/logger while still
+  capturing it. Each decoded line (plus a `"\n"`) is passed to `write()` as a
+  `str` via an async-write bridge: every write is dispatched to the runtime's
+  blocking pool (re-acquiring the GIL there) and awaited on the capture pump, so
+  a slow — even sleeping — `write()` applies backpressure without blocking the
+  event loop or deadlocking the runtime. The object is discriminated from a path
+  by exposing `write` (neither `str` nor `pathlib.Path` does) and is never closed
+  for you; `append=True` is meaningful only for a file path and raises
+  `ValueError` if combined with a writer. A `write()` exception disables the tee
+  for the rest of the run (a `tracing` warning under `enable_logging()`, the same
+  isolation as the file tee) and is additionally reported via `sys.unraisablehook`
+  — the run and its captured result are unaffected. The previous "a file path
+  only, an arbitrary Python writer is deliberately not supported" restriction is
+  lifted. See `docs/streaming.md#tee-output-to-a-file`.
+- `Command.on_stdout_line(callback)` / `Command.on_stderr_line(callback)`: a
+  `Callable[[str], None]` invoked with every decoded line as it is produced —
+  the way to give the **synchronous** surface (`.output()`/`.run()`) live
+  progress observation during an otherwise-blocking call, without losing the
+  full capture. Also fires on the async verbs and on a streamed run
+  (`start()`/`astart()` + `stdout_lines()`/`output_events()`); at most one
+  handler per stream (a repeat call replaces the previous one); a raising
+  callback is reported via `sys.unraisablehook` rather than propagated or
+  breaking the run. Inert under `stdout("inherit")`/`stdout("null")` (resp.
+  `stderr(...)`) and, for `on_stdout_line` only, under `output_bytes()` (which
+  captures stdout raw, bypassing the line pump — stderr still goes through it,
+  so `on_stderr_line` still fires there). See
+  `docs/streaming.md#live-per-line-callbacks`.
+- A `benchmarks/` suite (`pytest-benchmark`, new `bench` dependency-group)
+  measuring spawn+capture overhead against `subprocess`/`asyncio.subprocess`,
+  `ProcessGroup` start/exit, line-streaming throughput, and `output_all`
+  concurrency scaling — dev tooling only, no public API change. Runs nightly
+  via the `bench` job in `nightly-hardening.yml`, never in the PR gate; see
+  `benchmarks/README.md`.
+- `wait_for_path(path, *, timeout, interval=0.05)` — a new async readiness
+  helper alongside `wait_until` / `wait_for_port` / `wait_for_line`, polling
+  until a filesystem path appears (a unix socket, a pid file, or any other
+  marker a daemon creates once ready). Same timeout/interval discipline as its
+  siblings (NaN/negative `timeout` and non-positive `interval` raise
+  `ValueError`; `timeout=0` still checks the path at least once) and raises
+  `WaitTimeout` (also a `TimeoutError`) on expiry, now carrying a `path` field
+  (`WaitTimeout.__init__` gained a `path: StrPath | None = None` parameter).
+- `python -m processkit run -- <cmd> [args...]`: a CLI wrapper that runs a
+  command inside a kill-on-exit `ProcessGroup` with inherited stdio, for
+  shell scripts and CI steps with no Python to write. Supports `--timeout`,
+  `--timeout-grace`, `--max-memory`, `--max-processes`, and `--cpu-quota`;
+  the child's own exit code is passed through unchanged,
+  and a timeout / missing program / rejected resource limit is reported as a
+  one-line stderr message with a documented, GNU-`timeout`-style exit code
+  instead of a traceback. See `docs/cli.md`.
+- `Finished` gains `timed_out` and `signal` properties that delegate to the
+  nested `outcome`, so it now mirrors `Outcome` fully — matching `code` and
+  `exited_zero`, which were already exposed directly — instead of requiring
+  `finished.outcome.timed_out` / `finished.outcome.signal`.
+- `Command.stdin_file(path)` — feed the child's stdin from a file, streamed in
+  chunks by the crate rather than read whole into a Python `bytes` object, for
+  large inputs (a `psql` dump, a `tar` archive, a multi-gigabyte log). Like
+  most other builder methods (`stdout_tee`/`stderr_tee` are the deliberate
+  exception), it does not touch the filesystem at build time — the path is
+  opened lazily at spawn, so a missing/unreadable file surfaces as the generic
+  `ProcessError` from the run/output verb, not `FileNotFoundError`. Reusable
+  across retries/re-runs, like `stdin_bytes`/`stdin_text`; the usual "last
+  stdin method wins" rule applies alongside `stdin_bytes()`/`stdin_text()`/
+  `keep_stdin_open()`.
+- `ProcessResult` and `BytesResult` gain `diagnostic: str | None` (stderr if it
+  carries text, otherwise stdout, otherwise `None` — the same preference order
+  as `NonZeroExit`/`Timeout`/`Signalled.diagnostic` on the exceptions) and
+  `outcome: Outcome` (the same value `RunProfile.outcome` and the checking-verb
+  exceptions expose). A result held as data (`output()`/`output_bytes()`
+  without `ensure_success()`) no longer requires re-deriving these by hand.
+  (An `output_contains_any` convenience was considered alongside these and
+  rejected: the underlying `processkit` crate has no such method, so it
+  wouldn't be parity with the crate or the exceptions like `diagnostic`/
+  `outcome` are — and it's a one-liner callers can already write themselves
+  via `combined`, e.g. `any(s in result.combined for s in needles)`.)
+- Value semantics for the result types: `ProcessResult`, `BytesResult`,
+  `Outcome`, `Finished`, `RunProfile`, and `SupervisionOutcome` now define
+  `__eq__` (comparing every field the underlying `processkit` crate's own
+  `PartialEq` compares — not `object`'s previous identity comparison) and a
+  consistent `__hash__` (none of their fields are stored floats, so hashing is
+  sound), so two results can now be compared with `==` and used in a `set` or
+  as a `dict` key without a manual field-by-field comparison.
+  `ProcessResult`/`Outcome`/`Finished`/`SupervisionOutcome` are also picklable
+  — e.g. to return a `ProcessResult` from a
+  `concurrent.futures.ProcessPoolExecutor` worker. The underlying crate has no
+  public constructor for any of these types, so unpickling reconstructs one via
+  `processkit.testing.ScriptedRunner` (an in-memory, no-subprocess replay) —
+  faithful for every field the Python binding exposes, but a command that
+  customized `success_codes()`/`timeout()` is not guaranteed to compare `==`
+  its original after a round trip (those two fields have no Python accessor to
+  reconstruct exactly). `BytesResult` (raw stdout may not be valid UTF-8, and
+  the only reconstruction channel available is text-only) and `RunProfile`
+  (reports live OS resource-sampling telemetry with no synthesis path outside
+  an actual monitored run) explicitly do **not** support pickling and raise a
+  clear `TypeError` rather than failing silently or fabricating the missing
+  data.
+
+### Changed
+- `CliClient(default_env_fn=...)` now validates that every value in the
+  mapping is callable **at construction time**, raising `TypeError` (naming
+  the offending key) immediately instead of silently accepting a non-callable
+  value and only discovering the mistake later — once per built command, as
+  an unraisable-hook warning plus an always-empty resolved env var. Valid
+  callables behave exactly as before.
+
+### Fixed
+- `Args` (`from processkit import Args`) no longer rejects the single most
+  common real call site — a variable annotated `list[str]` (or
+  `list[pathlib.Path]` / `list[os.PathLike[str]]`) passed straight through to
+  an argv-like parameter, e.g. `args: list[str] = [...]; cmd.args(args)`.
+  `list` is invariant, so the original `list[StrPath] | tuple[StrPath, ...]`
+  spelling only ever accepted a `list[StrPath]`-annotated variable or a
+  literal, not a `list[str]`/`list[Path]`/`list[os.PathLike[str]]`-annotated
+  one, even though the values are runtime-identical — a static-typing-only
+  false positive with no runtime effect. `Args` is now a union of the concrete
+  homogeneous list shapes (`list[str]`, `list[Path]`, `list[os.PathLike[str]]`)
+  instead of the single invariant `list[StrPath]`; a *mixed* `str`/
+  `os.PathLike[str]` argv is still accepted, now spelled as a `tuple` rather
+  than a `list` literal (e.g. `cmd.args((path, "literal"))`). A bare `str`
+  still does not type-check as `Args` (unchanged; see the `Args` docstring).
+
+## [1.1.1] - 2026-07-06
+
+### Added
+- `Command.line_terminator(mode)` / `Command.stdout_line_terminator(mode)` /
+  `Command.stderr_line_terminator(mode)` — choose where the line pump splits a
+  stream into lines: `"newline"` (default, splits on `\n` only, unchanged
+  behavior) or `"carriage_return"` (also splits on a bare `\r`, delivering each
+  frame of a `curl`/`pip`/`apt`-style redrawn-in-place progress bar live instead
+  of piling it all up into one line at EOF). `line_terminator` sets both
+  streams at once; the `stdout_`/`stderr_` variants target one stream, leaving
+  the other's framing untouched. Binds `processkit` 2.1.0's
+  `Command::line_terminator`/`stdout_line_terminator`/`stderr_line_terminator`
+  (`LineTerminator`), exposed as the new `LineTerminatorName` string-preset
+  alias.
+- `testing.Reply.with_stderr(text)` — attach stderr to a scripted reply,
+  including a successful (`Reply.ok(...)`) one, without resorting to
+  `Reply.fail(0, ...)` as a workaround.
+- `processkit.testing.DryRunRunner` — a render-only test double that never
+  spawns a process: every verb renders the command to its display-quoted line
+  (via the crate's own `Command.command_line()` quoting) and returns a
+  synthetic success, the seam behind a tool's own `--dry-run`/`--echo` mode.
+  Inspect the rendered lines with `commands()` / `only_command()`, or stream
+  them live as each call happens with `on_invocation(callback)`. Works at every
+  runner injection point (`output_all` and friends, `Supervisor`, `CliClient`,
+  `runner=`), like the other doubles. (Binds `processkit` 2.1.0's
+  `testing::DryRunRunner`.)
+- `Supervisor(..., give_up_when=classifier)` — classify a permanent failure so
+  supervision gives up instead of restarting a crash forever, reporting the new
+  `SupervisionOutcome.stopped == "gave_up"`. Bound as a **Python callable**
+  (like `stop_when`, not a `retry_if`-style string preset — the crate's
+  classifier is a per-attempt closure, and a useful verdict is result-specific,
+  not a fixed vocabulary). The callback receives one argument mirroring the
+  crate's `GiveUpAttempt` sum type, dispatched with `isinstance`: a
+  `ProcessResult` for a crashed run that produced a result (classify by e.g.
+  `attempt.code`), or a `ProcessError` subclass for a launch that never produced
+  one (classify by e.g. `isinstance(attempt, ProcessNotFound)` for a missing
+  binary). Consulted only for a crash the policy would otherwise restart, ahead
+  of `max_restarts` and the failure-storm guard. A crash verdict stops with
+  `stopped == "gave_up"`; a launch-failure verdict has no result to report and
+  surfaces the classified error directly from `run()`/`arun()`. Off by default —
+  a permanent failure restarts as before. The classifier runs on the runtime
+  thread under the GIL; a raising or non-bool callback reads as "not permanent"
+  (keep restarting) and is surfaced via the unraisable hook, never silently
+  swallowed.
+- `Command.umask(mask)` — set the child's POSIX file-mode creation mask; on a
+  non-POSIX platform the run raises `Unsupported`, matching the existing
+  `uid`/`gid`/`groups`/`setsid` verbs.
+- `Command.priority(level)` — set the child's CPU-scheduling priority, one of
+  the named presets `"idle"`, `"below_normal"`, `"normal"`, `"above_normal"`,
+  `"high"` (new `Priority` type alias). Unix `nice`/`setpriority`, Windows
+  priority class — unlike the privilege/POSIX-only verbs above, supported on
+  **both** platform families, so it never raises `Unsupported`. Raising to
+  `"high"` on Unix without `CAP_SYS_NICE`/root raises `PermissionDenied`
+  instead of silently applying a lower priority.
+- `Command.timeout_opt(seconds)` — like `timeout()`, but takes `float | None`,
+  convenient when a timeout arrives from config as `Optional[float]`: a value
+  behaves exactly like `timeout(seconds)`, `None` clears a prior `timeout()`
+  exactly like `no_timeout()`.
+- `Command.retry_never()` — explicitly opt one command out of retrying, even
+  when it runs through a `CliClient` configured with a `default_retry_if`.
+- `NonZeroExit` / `Timeout` / `Signalled` now carry a `stdout_bytes: bytes | None`
+  field — the exact raw stdout bytes when the error came from a checking verb over
+  `output_bytes()` (e.g. `BytesResult.ensure_success()`), `None` on the text path
+  (`run()` / `output()`) where `stdout` is already the complete decoded text.
+  When present, these are the exact pre-decode bytes `stdout` is a lossy UTF-8
+  view of (they differ only for non-UTF-8 output). Binds processkit 2.1.0's
+  `Error::stdout_bytes()`.
+
+### Changed
+- `Command.output_limit(max_bytes=...)`'s byte ceiling now also bounds the raw
+  stdout of `output_bytes()` / `aoutput_bytes()`, matching processkit 2.1.0 —
+  previously a byte cap bounded only the line-pumped stderr and raw stdout was
+  always unbounded. Under `on_overflow="error"` an over-cap `output_bytes()` run
+  now raises `OutputTooLarge` (with `max_lines=None` — raw bytes have no line
+  count) where it once returned all bytes; under a drop mode its retained bytes
+  are bounded to a head/tail with `BytesResult.truncated` set. A `max_lines` cap
+  still never bounds raw stdout. This applies to every inherited `output_bytes`
+  consumer that runs a `Command` built with such a policy (`CliClient`,
+  `Pipeline`, `RunningProcess`, `ProcessGroup`, and the `runner=` doubles). The
+  `Supervisor` capture policy is unaffected — it captures line-based output only
+  and has no `output_bytes` verb.
+
+### Fixed
+-
+
 ## [1.1.0] - 2026-07-06
 
 ### Breaking
@@ -624,6 +835,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `enable_logging()` enables the crate's `tracing` feature; the bridge pulls
   `tracing` / `tracing-subscriber` (registry only) into the compiled wheel.
 
-[Unreleased]: https://github.com/ZelAnton/processkit-py/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/ZelAnton/processkit-py/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/ZelAnton/processkit-py/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/ZelAnton/processkit-py/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/ZelAnton/processkit-py/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/ZelAnton/processkit-py/releases/tag/v1.0.0

{processkit_py-1.1.0 → processkit_py-1.2.0}/CONTRIBUTING.md

@@ -80,6 +80,11 @@ native `uv run pytest`, which is faster for day-to-day work.
   warning-free `pytest`, plus `cargo fmt` / `clippy` on the Rust side — all
   configured in [`pyproject.toml`](pyproject.toml); run the
   [gates above](#build-and-test) locally before opening a pull request.
+- **Docs are built here, not published here.** `docs.yml` runs `mkdocs build
+  --strict` as a link/anchor check only; this repo does not deploy to GitHub
+  Pages or anywhere else (a separate project owns docs publishing). Do not
+  add a Pages/`mike`/`gh-pages` deploy step back — see RELEASING.md's "Docs
+  site" note.
 
 ## Changelog
 

{processkit_py-1.1.0 → processkit_py-1.2.0}/Cargo.lock

@@ -165,9 +165,9 @@ dependencies = [
 
 [[package]]
 name = "processkit"
-version = "1.2.0"
+version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d260c8da1b17daaf2f4379bd5c9ec9250d76e0af9c4fcf66e501ab443570ad0"
+checksum = "ccf43ce2a1756fe36382bc56b0bf1697d9ee1c32c0ed5a2afb5abf5163a64756"
 dependencies = [
  "async-trait",
  "encoding_rs",
@@ -184,7 +184,7 @@ dependencies = [
 
 [[package]]
 name = "processkit-py"
-version = "1.1.0"
+version = "1.2.0"
 dependencies = [
  "processkit",
  "pyo3",

{processkit_py-1.1.0 → processkit_py-1.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "processkit-py"
-version = "1.1.0"
+version = "1.2.0"
 edition = "2021"
 description = "PyO3 binding crate for the processkit Python package (compiled into wheels)"
 license = "MIT"
@@ -34,8 +34,10 @@ pyo3 = { version = "0.29", features = ["abi3-py310"] }
 # runtime we reuse for BOTH the sync surface (`block_on`) and the async surface
 # (`future_into_py`), so the binding owns exactly one runtime. Tracks pyo3 0.29.
 pyo3-async-runtimes = { version = "0.29", features = ["tokio-runtime"] }
-# The Rust core. Exact pin — the binding tracks API/behaviour churn deliberately,
-# not transitively (a 2.0.0 was published then yanked upstream; pin guards us).
+# The Rust core. Compatible-version requirement `2.1` (>=2.1.0, <3.0.0) — the
+# binding tracks API/behaviour churn deliberately, not transitively. 1.3.0 (a
+# semver-broken minor) and 2.0.0 (a mistaken publish) were yanked upstream, so
+# 2.1.0 is the floor; the requirement stays within the 2.x major on purpose.
 #
 # Features are listed EXPLICITLY with `default-features = false`, so a change to
 # the crate's default set can never silently alter our public surface:
@@ -51,7 +53,7 @@ pyo3-async-runtimes = { version = "0.29", features = ["tokio-runtime"] }
 # tests; it has no Python value (the Python test doubles come from the crate's
 # always-on `doubles` surface — ScriptedRunner / RecordingRunner — plus the
 # `record`-gated cassette RecordReplayRunner enabled above).
-processkit = { version = "=1.2.0", default-features = false, features = [
+processkit = { version = "2.1", default-features = false, features = [
   "process-control",
   "limits",
   "record",

{processkit_py-1.1.0 → processkit_py-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processkit-py
-Version: 1.1.0
+Version: 1.2.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -102,7 +102,7 @@ The first column is the differentiator: a child's *descendants* are contained an
 reaped as a unit (Job Object / cgroup v2 / process group), not just the direct
 child.
 
-> **Status: 1.0 — API frozen.** The public API follows
+> **Stable API.** The public API has been stable since 1.0 and follows
 > [Semantic Versioning](https://semver.org/): breaking changes land only in a new
 > major version, so `1.x` upgrades are backward-compatible. See
 > [CHANGELOG.md](CHANGELOG.md), and [ROADMAP.md](ROADMAP.md) for how it was built.
@@ -186,6 +186,17 @@ async def main():
 asyncio.run(main())
 ```
 
+No Python to write? `python -m processkit run -- <cmd> [args...]` gives a
+shell script or CI step the same kill-on-exit containment and resource
+limits from the command line, no code required:
+
+```bash
+python -m processkit run --timeout 30 --max-memory 536870912 -- pytest -x
+```
+
+See [Command-line usage](docs/cli.md) for the full flag list and exit-code
+contract.
+
 ## Documentation
 
 This README is the quick tour. The **[`docs/` guide set](docs/README.md)** goes

{processkit_py-1.1.0 → processkit_py-1.2.0}/README.md

@@ -69,7 +69,7 @@ The first column is the differentiator: a child's *descendants* are contained an
 reaped as a unit (Job Object / cgroup v2 / process group), not just the direct
 child.
 
-> **Status: 1.0 — API frozen.** The public API follows
+> **Stable API.** The public API has been stable since 1.0 and follows
 > [Semantic Versioning](https://semver.org/): breaking changes land only in a new
 > major version, so `1.x` upgrades are backward-compatible. See
 > [CHANGELOG.md](CHANGELOG.md), and [ROADMAP.md](ROADMAP.md) for how it was built.
@@ -153,6 +153,17 @@ async def main():
 asyncio.run(main())
 ```
 
+No Python to write? `python -m processkit run -- <cmd> [args...]` gives a
+shell script or CI step the same kill-on-exit containment and resource
+limits from the command line, no code required:
+
+```bash
+python -m processkit run --timeout 30 --max-memory 536870912 -- pytest -x
+```
+
+See [Command-line usage](docs/cli.md) for the full flag list and exit-code
+contract.
+
 ## Documentation
 
 This README is the quick tour. The **[`docs/` guide set](docs/README.md)** goes

{processkit_py-1.1.0 → processkit_py-1.2.0}/RELEASING.md

@@ -68,17 +68,13 @@ GitHub Release (wheels + sdist + `SHA256SUMS`).
 ## Docs site
 
 The guides in `docs/` render as a [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
-site via `.github/workflows/docs.yml`. The build (`mkdocs build --strict`) runs on
-every docs change as a link/anchor check; **deployment is opt-in** so there are no
-red runs before Pages is set up. To publish the site:
+site. `docs.yml` builds it (`mkdocs build --strict`) on every docs change as a
+link/anchor check only — this repo does **not** publish the site (no GitHub
+Pages, no `gh-pages` branch, no `mike`, no `DOCS_DEPLOY`). A separate project
+owns docs publishing. **Do not re-add a Pages/mike deploy job here** — if a
+future dependency bump or template sync tries to reintroduce one, undo it.
 
-1. Repo **Settings → Pages → Source: GitHub Actions**.
-2. Repo **Settings → Secrets and variables → Actions → Variables**: add
-   `DOCS_DEPLOY` = `true`.
-
-The next push to `main` that touches `docs/` or `mkdocs.yml` then deploys to
-`https://zelanton.github.io/processkit-py/`. Preview locally with
-`uvx --with mkdocs-material mkdocs serve`.
+Preview the docs locally with `uv run --group docs mkdocs serve`.
 
 ## If a release fails
 

{processkit_py-1.1.0 → processkit_py-1.2.0}/SECURITY.md

@@ -36,6 +36,14 @@ ready, a patched release is published to PyPI and the advisory is disclosed.
   [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). It scans the resolved
   Python dependency tree against the [PyPI Advisory Database](https://github.com/pypa/advisory-database)
   and fails the build on a known vulnerability.
+- **[cargo-deny](https://github.com/EmbarkStudios/cargo-deny)** is the Rust
+  analogue of pip-audit: the `rust-audit` job in
+  [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs
+  `cargo deny check advisories bans licenses sources` on every pull request
+  and every push to `main`, scanning the compiled Rust dependency tree
+  (configured in [`deny.toml`](deny.toml)) against the RustSec Advisory
+  Database and failing the build on a known vulnerability, a yanked crate, or
+  a disallowed license.
 - **[Dependabot](.github/dependabot.yml)** opens weekly pull requests to keep
   GitHub Actions, Python packages (`uv` ecosystem), and Rust crates (`cargo`
   ecosystem) current, so advisory fixes land promptly.

processkit_py-1.2.0/benchmarks/README.md

@@ -0,0 +1,57 @@
+# Benchmarks
+
+`pytest-benchmark` timings for the questions [ROADMAP.md](../ROADMAP.md)'s
+Phase 5 asks — "does the bridge add silly overhead?" — with a real number
+attached instead of only the loose pass/fail bound in
+`tests/test_hardening.py::test_no_silly_per_call_overhead`:
+
+- **`test_spawn_capture.py`** — spawn + capture a single short-lived command:
+  `processkit`'s `Command(...).output()` against the two stdlib "naive"
+  equivalents, `subprocess.run(..., capture_output=True)` and
+  `asyncio.create_subprocess_exec(...)` + `communicate()`. Same payload on
+  all three, so the comparison is per-call overhead, not a differing
+  workload.
+- **`test_process_group.py`** — `ProcessGroup` start/exit: creating the
+  group's kernel container, entering it, starting one short-lived child,
+  tearing the whole tree down.
+- **`test_streaming_throughput.py`** — `RunningProcess.stdout_lines()` (see
+  [`docs/streaming.md`](../docs/streaming.md)) draining a known number of
+  lines end to end.
+- **`test_output_all.py`** — `output_all()` / `aoutput_all()` at 1/10/50-way
+  concurrency (see [`docs/cookbook.md`](../docs/cookbook.md)).
+
+## Running locally
+
+This suite is **not** part of the PR gate — it lives in its own
+`bench` dependency-group and is excluded from `testpaths` (`tests/` only), so
+an ordinary `pytest`/`uv run pytest` never collects it. Install the group and
+run it explicitly:
+
+```console
+uv sync --group bench
+uv run pytest benchmarks/ --benchmark-only -p no:xdist -o addopts=""
+```
+
+`-p no:xdist -o addopts=""` disables `-n auto` (the repo's default
+`addopts`) — `pytest-benchmark` needs to run in the main process, in a single
+worker, to produce meaningful timings; under `pytest-xdist` it silently skips
+measuring instead.
+
+Useful extras:
+
+- `--benchmark-only` skips the normal (non-benchmark) test collection outside
+  this directory should it ever leak in; harmless here since `benchmarks/`
+  has none, but keeps the invocation copy-pasteable elsewhere.
+- `--benchmark-compare` / `--benchmark-autosave` — compare a run against a
+  previously saved one, to check a change before landing it.
+- `--benchmark-json=out.json` — machine-readable results (what the nightly
+  CI job uses to render the job-summary table; see below).
+
+## CI
+
+The `bench` job in
+[`.github/workflows/nightly-hardening.yml`](../.github/workflows/nightly-hardening.yml)
+runs this suite on the same `schedule`/`workflow_dispatch` triggers as the
+`stress` job — never on `push`/`pull_request` — and publishes the results as
+a table in the job summary, so a regression shows up as a trend across nights
+rather than only when someone happens to run this locally.

processkit_py-1.2.0/benchmarks/__init__.py

@@ -0,0 +1,11 @@
+"""Benchmark suite (`pytest-benchmark`) — overhead vs `subprocess`.
+
+Not part of the PR gate: `[tool.pytest.ini_options] testpaths` in
+`pyproject.toml` is `["tests"]`, so an ordinary `pytest` run never collects
+this directory. It runs on a schedule (and on manual dispatch) from the
+`bench` job in `.github/workflows/nightly-hardening.yml`, which installs the
+separate `bench` dependency-group and invokes `pytest benchmarks/
+--benchmark-only` explicitly. See `benchmarks/README.md` to run it locally.
+"""
+
+from __future__ import annotations

processkit_py-1.2.0/benchmarks/_shared.py

@@ -0,0 +1,20 @@
+"""Small pieces shared by the benchmark modules — no test collection here."""
+
+from __future__ import annotations
+
+import sys
+
+#: The interpreter under test, for building child `Command`s/`subprocess`
+#: calls — same idea as `tests/conftest.py`'s `PY`, kept local so this
+#: directory has no import-time dependency on the `tests/` package.
+PY = sys.executable
+
+#: A short-lived child that does no work (the pure per-call-overhead
+#: baseline) — the same style as `tests/test_hardening.py`'s
+#: `test_no_silly_per_call_overhead`.
+NOOP_CODE = "pass"
+
+#: A payload that also exercises stdout *capture* (not just spawn/exit),
+#: identical across all three "spawn + capture" benchmarks below so the
+#: comparison isolates per-call overhead rather than differing workloads.
+CAPTURE_CODE = "import sys; sys.stdout.write('x' * 4096)"

processkit_py-1.2.0/benchmarks/test_output_all.py

@@ -0,0 +1,52 @@
+"""`output_all` / `aoutput_all` at different concurrency levels — bounded
+parallel batches of short-lived commands (see `docs/cookbook.md`'s
+"many commands, bounded concurrency" recipe).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import pytest
+
+from processkit import Command, aoutput_all, output_all
+
+from ._shared import NOOP_CODE, PY
+
+if TYPE_CHECKING:
+    from pytest_benchmark.fixture import BenchmarkFixture
+
+#: Concurrency == batch size in every case below: N commands, all allowed to
+#: run at once, at each of the sizes the task calls out (1/10/50) — that
+#: isolates how the batch dispatch machinery itself scales, rather than
+#: mixing in a fixed backlog queued behind a narrower `concurrency=`.
+_CONCURRENCIES = (1, 10, 50)
+
+
+@pytest.mark.parametrize("concurrency", _CONCURRENCIES)
+def test_output_all_concurrency(benchmark: BenchmarkFixture, concurrency: int) -> None:
+    commands = [Command(PY, ["-c", NOOP_CODE]) for _ in range(concurrency)]
+    benchmark.group = f"output_all(concurrency={concurrency})"
+
+    def run() -> None:
+        results = output_all(commands, concurrency=concurrency)
+        assert len(results) == concurrency
+
+    benchmark(run)
+
+
+@pytest.mark.parametrize("concurrency", _CONCURRENCIES)
+def test_aoutput_all_concurrency(benchmark: BenchmarkFixture, concurrency: int) -> None:
+    commands = [Command(PY, ["-c", NOOP_CODE]) for _ in range(concurrency)]
+    benchmark.group = f"aoutput_all(concurrency={concurrency})"
+
+    async def scenario() -> int:
+        results = await aoutput_all(commands, concurrency=concurrency)
+        return len(results)
+
+    def run() -> None:
+        count = asyncio.run(scenario())
+        assert count == concurrency
+
+    benchmark(run)

processkit_py-1.2.0/benchmarks/test_process_group.py

@@ -0,0 +1,26 @@
+"""`ProcessGroup` start/exit — the cost of creating the group's kernel
+container (Job Object / cgroup-v2 / process group, see `docs/platforms.md`),
+entering the context manager, starting one short-lived child into it, and
+tearing the whole tree down on exit.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from processkit import Command, ProcessGroup
+
+from ._shared import NOOP_CODE, PY
+
+if TYPE_CHECKING:
+    from pytest_benchmark.fixture import BenchmarkFixture
+
+
+def test_process_group_start_exit(benchmark: BenchmarkFixture) -> None:
+    def run() -> None:
+        with ProcessGroup() as group:
+            proc = group.start(Command(PY, ["-c", NOOP_CODE]))
+            outcome = proc.outcome()
+            assert outcome.exited_zero
+
+    benchmark(run)

processkit_py-1.2.0/benchmarks/test_spawn_capture.py

@@ -0,0 +1,61 @@
+"""Spawn + capture a single short-lived command: `processkit` vs the two
+"naive" ways of doing the same thing from stdlib — `subprocess.run` and
+`asyncio.create_subprocess_exec` + `communicate()`. Same payload on all
+three (`_shared.CAPTURE_CODE`) so the comparison isolates the bridge's
+per-call overhead rather than a differing workload.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from typing import TYPE_CHECKING
+
+from processkit import Command
+
+from ._shared import CAPTURE_CODE, PY
+
+if TYPE_CHECKING:
+    from pytest_benchmark.fixture import BenchmarkFixture
+
+_EXPECTED = "x" * 4096
+
+
+def test_spawn_capture_processkit(benchmark: BenchmarkFixture) -> None:
+    def run() -> str:
+        result = Command(PY, ["-c", CAPTURE_CODE]).output()
+        assert result.is_success
+        return result.stdout
+
+    stdout = benchmark(run)
+    assert stdout == _EXPECTED
+
+
+def test_spawn_capture_subprocess(benchmark: BenchmarkFixture) -> None:
+    def run() -> str:
+        result = subprocess.run(
+            [PY, "-c", CAPTURE_CODE], capture_output=True, text=True, check=True
+        )
+        return result.stdout
+
+    stdout = benchmark(run)
+    assert stdout == _EXPECTED
+
+
+def test_spawn_capture_asyncio_subprocess(benchmark: BenchmarkFixture) -> None:
+    # `asyncio.run` opens/closes a fresh event loop per call — the same
+    # "naive per-call" shape a caller reaching for asyncio.subprocess without
+    # already running inside a long-lived loop would write.
+    async def scenario() -> str:
+        proc = await asyncio.create_subprocess_exec(
+            PY, "-c", CAPTURE_CODE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+        stdout, _stderr = await proc.communicate()
+        assert proc.returncode == 0
+        return stdout.decode()
+
+    def run() -> str:
+        return asyncio.run(scenario())
+
+    stdout = benchmark(run)
+    assert stdout == _EXPECTED