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

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

@@ -16,6 +16,132 @@ 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
@@ -709,7 +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.1...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.1 → 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.1 → processkit_py-1.2.0}/Cargo.lock

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

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

@@ -1,6 +1,6 @@
 [package]
 name = "processkit-py"
-version = "1.1.1"
+version = "1.2.0"
 edition = "2021"
 description = "PyO3 binding crate for the processkit Python package (compiled into wheels)"
 license = "MIT"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processkit-py
-Version: 1.1.1
+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.1 → 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.1 → 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.1 → 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

processkit_py-1.2.0/benchmarks/test_streaming_throughput.py

@@ -0,0 +1,41 @@
+"""Line-streaming throughput: `RunningProcess.stdout_lines()` (see
+`docs/streaming.md`) draining a child that writes a known number of lines as
+fast as it can, end to end (spawn through `afinish()`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from processkit import Command
+
+from ._shared import PY
+
+if TYPE_CHECKING:
+    from pytest_benchmark.fixture import BenchmarkFixture
+
+#: How many lines the child emits per run. Large enough that the loop
+#: dominates over the fixed spawn cost, small enough that a bench round stays
+#: fast (this file runs once per nightly job, at whatever --benchmark-min-rounds
+#: pytest-benchmark's calibration lands on).
+_LINE_COUNT = 5_000
+
+_PRODUCER = f"for i in range({_LINE_COUNT}): print(i)"
+
+
+def test_stdout_lines_throughput(benchmark: BenchmarkFixture) -> None:
+    async def scenario() -> int:
+        proc = await Command(PY, ["-c", _PRODUCER]).astart()
+        count = 0
+        async for _line in proc.stdout_lines():
+            count += 1
+        finished = await proc.afinish()
+        assert finished.exited_zero
+        return count
+
+    def run() -> int:
+        return asyncio.run(scenario())
+
+    lines = benchmark(run)
+    assert lines == _LINE_COUNT

processkit_py-1.2.0/deny.toml

@@ -0,0 +1,44 @@
+# cargo-deny configuration. CI runs
+# `cargo deny check advisories bans licenses sources`
+# (see .github/workflows/ci.yml, `rust-audit` job). Kept in the PR gate (not
+# nightly-hardening.yml) for the same reason
+# pip-audit is: the crate is compiled into every wheel users install, so a
+# newly-disclosed RustSec advisory or license violation should block the next
+# merge, not wait for the nightly schedule. Adapted from the sibling
+# ProcessKit-rs repository's `deny.toml` (same categories), scoped to this
+# binding's own Cargo tree (pyo3, pyo3-async-runtimes, tokio, tracing, ...).
+[advisories]
+# Fail on crates with a RustSec security advisory or that have been yanked.
+version = 2
+yanked = "deny"
+
+[licenses]
+# This crate is MIT and is compiled into the distributed wheels; the
+# dependency tree must stay on permissive licenses a downstream MIT/Apache
+# consumer can absorb. A new transitive dependency with anything outside this
+# list (copyleft, source-available, unknown) fails CI loudly instead of
+# slipping into a release.
+version = 2
+allow = [
+    "MIT",
+    "Apache-2.0",
+    # target-lexicon (a pyo3-build-config build-dependency) uses this LLVM
+    # linking exception on top of Apache-2.0 -- still permissive, no
+    # copyleft/attribution burden beyond plain Apache-2.0.
+    "Apache-2.0 WITH LLVM-exception",
+    "BSD-3-Clause",
+    "Unicode-3.0",
+]
+
+[bans]
+# Duplicate versions of the same crate are a warning, not a hard failure.
+multiple-versions = "warn"
+# Wildcard version requirements hide breakage; flag them.
+wildcards = "deny"
+
+[sources]
+# Only allow dependencies from the official crates.io registry -- no git
+# dependencies or unknown/private registries sneaking into the tree that
+# gets compiled into every wheel.
+unknown-registry = "deny"
+unknown-git = "deny"

{processkit_py-1.1.1 → processkit_py-1.2.0}/docs/README.md

@@ -46,11 +46,13 @@ handy before you ship: it collects every per-OS caveat in one place.
 | [Coming from subprocess](migrating.md) | Side-by-side translation of `subprocess` / `asyncio.subprocess` patterns, the exception mapping, and the whole-tree containment the stdlib can't give |
 | [Running commands](commands.md) | The `Command` builder end to end — args, env/sandboxing, stdin, stdout/stderr redirection, encodings, output caps, timeouts, privileges — and every consuming verb (`output`, `run`, `probe`, …) with its error semantics |
 | [Process groups](process-groups.md) | Kill-on-drop containment: creating groups, spawning, teardown, whole-tree signals, suspend/resume, member listing, resource limits, stats |
+| [Sandboxing untrusted tools](sandboxing.md) | The agent/LLM-tool recipe: locked-down env → bounded output → group resource limits → timeout → teardown, a checklist, and an honest threat model (what this does and does not protect against) |
 | [Streaming & interactive I/O](streaming.md) | `astart()` and the live `RunningProcess`: line streaming, interactive stdin, readiness probes (`wait_for_line` / `wait_for_port` / `wait_until`), per-run profiling |
 | [Pipelines](pipelines.md) | Shell-free command pipelines — chain with `.pipe()` or the pipe operator: wiring, pipefail attribution, chain timeouts, binary tails |
 | [Timeouts & cancellation](timeouts-and-cancellation.md) | How a deadline is *captured* vs when it raises, interrupting a blocked sync call (Ctrl+C), and asyncio cancellation that reaps the whole tree |
 | [Supervision](supervision.md) | Keeping a child alive: restart policies, backoff & jitter, stop conditions, outcomes |
 | [Testing your code](testing.md) | The `ProcessRunner` seam — `ScriptedRunner` (incl. scripted streaming `start()`), record/replay cassettes, the `RecordingRunner` spy, the `CliClient` wrapper, and the autoloaded **pytest plugin** (ready-made fixtures + a no-real-spawn guard) |
+| [Command-line usage](cli.md) | `python -m processkit run -- ...`: containment and resource limits for a shell command with no Python to write, flags, exit codes |
 | [Async runtimes & event loops](event-loops.md) | Which event loops the asyncio-native surface runs on — asyncio and uvloop (yes), anyio-on-asyncio (yes), native trio / anyio-on-trio / curio (no) — and why |
 | [Platform support](platforms.md) | The containment mechanisms, every per-feature support matrix in one place, and the caveats worth knowing before you ship |
 
@@ -62,10 +64,11 @@ record/replay, and opt-in logging are all present in every published wheel.
 There is nothing to opt into at install time:
 
 ```bash
-pip install processkit-py   # supported path once the first PyPI release lands (import name: processkit)
+pip install processkit-py   # import name: processkit
 ```
 
-Until then, build from source (`uv run maturin develop`) — see the
+On a platform without a prebuilt wheel, build from source (`uv run maturin
+develop`) — see the
 [README](https://github.com/ZelAnton/processkit-py#building-from-source).
 
 Distributed as **abi3 wheels for CPython 3.10+** (one wheel per OS/arch runs on