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

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

@@ -16,6 +16,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 -
 
+## [1.2.1] - 2026-07-09
+
+### Added
+
+- Add Command.prefer_local, exposing crate 2.2's bare-name resolution override
+- Add Command.prefer_local, exposing crate 2.2's bare-name resolution override
+- Add a runnable Command.prefer_local example to docs
+- Add ProcessStdin.send_control for interactive control-byte delivery
+- Add ProcessStdin.send_control for interactive control-byte delivery
+- Add Command.prefer_local usage example to docs/commands.md
+
+
+### Changed
+
+- Broaden Command.priority docstring privilege caveat to cover above_normal and niced-parent normal
+- Bump processkit dependency requirement and lockfile to 2.2.0
+- Bump processkit dependency requirement and lockfile to 2.2.0
+- Broaden Command.priority docstring privilege caveat to cover above_normal and niced-parent normal
+- Initialize integration workspace for batch B-20260709T132808Z
+- Initialize integration workspace for batch B-20260709T144637Z
+- Apply rustfmt to send_control signature
+- Bump processkit dependency to 2.2.1
+- Initialize integration workspace for batch B-20260709T162529Z
+- Bump processkit dependency to 2.2.1
+
+
+### Fixed
+
+- Fix Windows-incompatible relative path-form assertion in the prefer_local example
+
 ## [1.2.0] - 2026-07-08
 
 ### Added
@@ -835,7 +865,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.2.0...HEAD
+[Unreleased]: https://github.com/ZelAnton/processkit-py/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/ZelAnton/processkit-py/compare/v1.2.0...v1.2.1
 [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

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

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

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

@@ -1,6 +1,6 @@
 [package]
 name = "processkit-py"
-version = "1.2.0"
+version = "1.2.1"
 edition = "2021"
 description = "PyO3 binding crate for the processkit Python package (compiled into wheels)"
 license = "MIT"
@@ -34,10 +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. Compatible-version requirement `2.1` (>=2.1.0, <3.0.0) — the
+# The Rust core. Compatible-version requirement `2.2` (>=2.2.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.
+# 2.2.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:
@@ -53,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 = "2.1", default-features = false, features = [
+processkit = { version = "2.2", default-features = false, features = [
   "process-control",
   "limits",
   "record",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processkit-py
-Version: 1.2.0
+Version: 1.2.1
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3

{processkit_py-1.2.0 → processkit_py-1.2.1}/docs/commands.md

@@ -10,6 +10,7 @@ so an early return, an exception, or a cancelled task can never leak a child.
 - [The two surfaces: sync and async](#the-two-surfaces-sync-and-async)
 - [Picking a verb](#picking-a-verb)
 - [Program, arguments, working directory](#program-arguments-working-directory)
+- [Local program search](#local-program-search)
 - [Environment and sandboxing](#environment-and-sandboxing)
 - [Standard input](#standard-input)
 - [Redirecting stdout and stderr](#redirecting-stdout-and-stderr)
@@ -109,6 +110,99 @@ cmd.command_line()       # "login --password hunter2" — includes the secret!
 repr(cmd)                # redacted: shows arg COUNT, never values
 ```
 
+## Local program search
+
+Use `prefer_local(dir)` when a bare-name program should resolve from a project or
+toolchain directory before falling back to the system `PATH`: for example
+`node_modules/.bin`, `target/debug`, or a vendored tool directory. The directory
+argument accepts `str` and `os.PathLike[str]`, like `cwd`.
+
+```python
+out = (
+    Command("ruff")
+    .prefer_local(Path(".venv/bin"))
+    .prefer_local(Path("tools/bin"))
+    .arg("--version")
+    .run()
+)
+```
+
+Repeated calls accumulate in priority order, so the first preferred directory is
+searched first, then the next, then the normal `PATH`. The search reuses the same
+platform behavior as `PATH` resolution, including `PATHEXT` on Windows.
+
+`prefer_local` affects only bare-name programs such as `"ruff"` or `"cargo"`.
+Path-form programs such as `"./ruff"`, `"tools/ruff"`, or an absolute path are
+used as written. It also does not rewrite the child's own `PATH`; it only changes
+how processkit finds the executable to spawn. If the program is not found, the
+preferred directories are included in the failure diagnostics along with the
+normal search locations.
+
+Here is a self-contained example that creates two local tool directories and
+prefers both before the system `PATH`:
+
+```python
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+from processkit import Command
+
+name = "demo-tool"
+
+
+def write_tool(directory: Path, text: str) -> Path:
+    directory.mkdir(parents=True)
+    if os.name == "nt":
+        tool = directory / f"{name}.cmd"
+        tool.write_text(f"@echo off\necho {text}\n", encoding="utf-8")
+    else:
+        tool = directory / name
+        tool.write_text(f"#!/bin/sh\necho {text}\n", encoding="utf-8")
+        tool.chmod(tool.stat().st_mode | stat.S_IXUSR)
+    return tool
+
+
+with tempfile.TemporaryDirectory() as tmp:
+    project = Path(tmp)
+    first = write_tool(project / "node_modules" / ".bin", "node tool")
+    second = write_tool(project / "target" / "debug", "debug tool")
+
+    # Search order for the bare name "demo-tool":
+    #   1. ./node_modules/.bin
+    #   2. ./target/debug
+    #   3. the parent process PATH
+    out = (
+        Command(name)
+        .cwd(project)
+        .prefer_local(first.parent)
+        .prefer_local(second.parent)
+        .run()
+    )
+    assert out == "node tool"
+
+    # The child still receives the inherited PATH unless you change it with
+    # env(...). prefer_local only affects processkit's spawn-time lookup.
+    assert str(first.parent) not in os.environ.get("PATH", "")
+
+    # Path-form programs bypass prefer_local and are used exactly as written.
+    assert Command(second).prefer_local(first.parent).run() == "debug tool"
+    old_cwd = Path.cwd()
+    os.chdir(project)
+    try:
+        assert (
+            Command(f"target{os.sep}debug{os.sep}{second.name}")
+            .prefer_local(first.parent)
+            .run()
+            == "debug tool"
+        )
+    finally:
+        os.chdir(old_cwd)
+
+    print(out)
+```
+
 ## Environment and sandboxing
 
 The environment builders compose, applied in a fixed order at spawn:

{processkit_py-1.2.0 → processkit_py-1.2.1}/docs/streaming.md

@@ -291,9 +291,21 @@ assert finished.exited_zero
 ```
 
 `ProcessStdin` is fully awaitable: `await write(bytes)`, `write_line(str)`
-(newline + flush), `flush()`, and `close()` (EOF). `take_stdin()` **raises**
-`ProcessError` if the `Command` didn't `keep_stdin_open()` or the writer was
-already taken — so a missing setup fails right here, not later on a `None`.
+(newline + flush), `send_control(str)`, `flush()`, and `close()` (EOF).
+`send_control()` accepts exactly one recognized control character and writes
+the mapped control byte to the child's stdin pipe: for example,
+`await stdin.send_control("c")` writes Ctrl-C (`\x03`) and
+`await stdin.send_control("d")` writes Ctrl-D (`\x04`). Invalid input raises
+`ValueError`.
+
+This is a byte in a normal pipe, not a terminal signal. It only affects
+children that read and interpret that byte from stdin; real terminal semantics
+such as SIGINT/SIGTSTP delivery require a pseudoterminal, which `processkit`
+does not provide yet.
+
+`take_stdin()` **raises** `ProcessError` if the `Command` didn't
+`keep_stdin_open()` or the writer was already taken — so a missing setup fails
+right here, not later on a `None`.
 
 **Avoid the full-duplex deadlock.** A child's stdout pipe has a finite OS
 buffer; once it fills, the child blocks *writing* stdout until something reads

{processkit_py-1.2.0 → processkit_py-1.2.1}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "maturin"
 # module-name below): `pip install processkit-py` -> `import processkit`.
 [project]
 name = "processkit-py"
-version = "1.2.0"
+version = "1.2.1"
 description = "Python bindings to the processkit Rust crate — asyncio-native, no-orphan process containment"
 readme = "README.md"
 # abi3 wheels (cp310+): Python 3.9 reached EOL October 2025; dev tools (mypy>=2.1) require 3.10+.

{processkit_py-1.2.0 → processkit_py-1.2.1}/src/command.rs

@@ -95,6 +95,18 @@ impl PyCommand {
         }
     }
 
+    /// Search this directory before `PATH` when resolving a bare-name program.
+    ///
+    /// Repeated calls accumulate in priority order. This only affects programs
+    /// such as `"tool"`; path-form programs such as `"./tool"` or
+    /// `"/opt/tool"` are left unchanged. The child's own `PATH` environment is
+    /// not rewritten.
+    fn prefer_local(&self, dir: PathBuf) -> Self {
+        Self {
+            inner: self.inner.clone().prefer_local(dir),
+        }
+    }
+
     fn env(&self, key: &str, value: &str) -> Self {
         Self {
             inner: self.inner.clone().env(key, value),
@@ -621,9 +633,11 @@ impl PyCommand {
     /// priority class, alongside `create_no_window`.
     ///
     /// Unlike the privilege/POSIX-only knobs above, `priority` is supported on
-    /// **both** platform families and never raises `Unsupported`. The one
-    /// caveat is `"high"` on Unix: lowering `nice` below its inherited value
-    /// needs `CAP_SYS_NICE` (Linux) or an equivalent privilege elsewhere;
+    /// **both** platform families and never raises `Unsupported`. On Unix,
+    /// `"high"`, `"above_normal"`, and `"normal"` under a positive-niced parent
+    /// raise priority relative to the inherited value. Lowering `nice` below
+    /// its inherited value needs `CAP_SYS_NICE` (Linux), root, or an equivalent
+    /// privilege elsewhere;
     /// without it the OS refuses the change and the run raises
     /// `PermissionDenied` (never a silent downgrade to a lower priority) —
     /// Windows needs no special privilege for its `HIGH_PRIORITY_CLASS`.

{processkit_py-1.2.0 → processkit_py-1.2.1}/src/errors.rs

@@ -109,6 +109,7 @@ fn init_dual_exceptions(m: &Bound<'_, PyModule>) -> PyResult<()> {
         py.get_type::<PyFileNotFoundError>(),
         "The program could not be found / spawned. Also a `FileNotFoundError`.",
     )?;
+    not_found.setattr("searched", py.None())?;
     let permission_denied = make_dual_exception(
         py,
         "PermissionDenied",
@@ -288,6 +289,9 @@ pub(crate) fn map_err_ref(error: &processkit::Error) -> PyErr {
             E::Exit { .. } => {
                 let _ = value.setattr("diagnostic", error.diagnostic());
             }
+            E::NotFound { searched, .. } => {
+                let _ = value.setattr("searched", searched.as_deref());
+            }
             E::OutputTooLarge {
                 max_lines,
                 max_bytes,

{processkit_py-1.2.0 → processkit_py-1.2.1}/src/processkit/_processkit.pyi

@@ -154,6 +154,11 @@ class Command:
     def arg(self, arg: StrPath) -> Command: ...
     def args(self, args: Args) -> Command: ...
     def cwd(self, path: StrPath) -> Command: ...
+    def prefer_local(self, dir: StrPath) -> Command:
+        """Search this directory before ``PATH`` when resolving a bare-name
+        program. Repeated calls accumulate in priority order, path-form
+        programs are unchanged, and the child's own ``PATH`` is not rewritten."""
+
     def env(self, key: str, value: str) -> Command: ...
     def envs(self, vars: Mapping[str, str]) -> Command: ...
     def env_remove(self, key: str) -> Command: ...
@@ -451,6 +456,13 @@ class ProcessStdin:
 
     async def write(self, data: ReadableBuffer) -> None: ...
     async def write_line(self, line: str) -> None: ...
+    async def send_control(self, control: str) -> None:
+        """Write one mapped control byte, e.g. ``"c"`` -> Ctrl-C (``\\x03``).
+
+        This writes a byte to the child's stdin pipe, not a terminal signal;
+        real SIGINT/SIGTSTP delivery requires a pseudoterminal.
+        """
+
     async def flush(self) -> None: ...
     async def close(self) -> None: ...
 
@@ -976,6 +988,9 @@ class ProcessNotFound(ProcessError, FileNotFoundError):
     """
 
     program: str
+    # The searched directories joined by the platform path separator, or `None`
+    # when no PATH-like search was used.
+    searched: str | None
 
 class PermissionDenied(ProcessError, PermissionError):
     """The program could not be spawned because of insufficient permissions

{processkit_py-1.2.0 → processkit_py-1.2.1}/src/running.rs

@@ -8,7 +8,7 @@ use processkit::OutputEvents as PkOutputEvents;
 use processkit::ProcessStdin as PkProcessStdin;
 use processkit::RunningProcess as PkRunningProcess;
 use processkit::StdoutLines as PkStdoutLines;
-use pyo3::exceptions::{PyOSError, PyStopAsyncIteration};
+use pyo3::exceptions::{PyOSError, PyStopAsyncIteration, PyValueError};
 use pyo3::prelude::*;
 use tokio::sync::Mutex;
 
@@ -53,6 +53,34 @@ impl PyProcessStdin {
         })
     }
 
+    /// Send a single control byte to the child's stdin.
+    fn send_control<'py>(&self, py: Python<'py>, control: String) -> PyResult<Bound<'py, PyAny>> {
+        let mut chars = control.chars();
+        let c = chars.next().ok_or_else(|| {
+            PyValueError::new_err("send_control() requires exactly one control character")
+        })?;
+        if chars.next().is_some() {
+            return Err(PyValueError::new_err(
+                "send_control() requires exactly one control character",
+            ));
+        }
+
+        let stdin = self.inner.clone();
+        pyo3_async_runtimes::tokio::future_into_py(py, async move {
+            let mut guard = stdin.lock().await;
+            let writer = guard
+                .as_mut()
+                .ok_or_else(|| PyOSError::new_err("stdin is closed"))?;
+            writer.send_control(c).await.map_err(|err| {
+                if err.kind() == std::io::ErrorKind::InvalidInput {
+                    PyValueError::new_err(err.to_string())
+                } else {
+                    PyErr::from(err)
+                }
+            })
+        })
+    }
+
     /// Flush buffered writes to the child.
     fn flush<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
         let stdin = self.inner.clone();

{processkit_py-1.2.0 → processkit_py-1.2.1}/tests/test_command.py

@@ -46,6 +46,18 @@ from processkit.testing import RecordingRunner, Reply, ScriptedRunner
 from .conftest import NO_SUCH_PROGRAM, PY
 
 
+def _make_executable_command(directory: pathlib.Path, name: str, output: str) -> pathlib.Path:
+    if os.name == "nt":
+        path = directory / f"{name}.cmd"
+        path.write_text(f"@echo off\r\necho {output}\r\n", encoding="utf-8")
+        return path
+
+    path = directory / name
+    path.write_text(f"#!/bin/sh\nprintf '%s\\n' {output!r}\n", encoding="utf-8")
+    path.chmod(0o755)
+    return path
+
+
 def test_output_captures_stdout_and_code() -> None:
     result = Command(PY, ["-c", "print('hello')"]).output()
     assert result.stdout.strip() == "hello"
@@ -96,6 +108,61 @@ def test_missing_program_raises_process_not_found() -> None:
         Command(NO_SUCH_PROGRAM).output()
 
 
+def test_prefer_local_finds_program_before_path(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    local_dir = tmp_path / "local-bin"
+    path_dir = tmp_path / "path-bin"
+    local_dir.mkdir()
+    path_dir.mkdir()
+    _make_executable_command(local_dir, "pk-tool", "local")
+    _make_executable_command(path_dir, "pk-tool", "path")
+    monkeypatch.setenv("PATH", str(path_dir))
+
+    assert Command("pk-tool").prefer_local(local_dir).run() == "local"
+
+
+def test_prefer_local_accumulates_in_priority_order(tmp_path: pathlib.Path) -> None:
+    first_dir = tmp_path / "first"
+    second_dir = tmp_path / "second"
+    first_dir.mkdir()
+    second_dir.mkdir()
+    _make_executable_command(first_dir, "pk-tool", "first")
+    _make_executable_command(second_dir, "pk-tool", "second")
+
+    output = Command("pk-tool").prefer_local(first_dir).prefer_local(second_dir).run()
+
+    assert output == "first"
+
+
+def test_prefer_local_does_not_affect_path_form_program(tmp_path: pathlib.Path) -> None:
+    local_dir = tmp_path / "local-bin"
+    explicit_dir = tmp_path / "explicit-bin"
+    local_dir.mkdir()
+    explicit_dir.mkdir()
+    _make_executable_command(local_dir, "pk-tool", "local")
+    explicit_program = _make_executable_command(explicit_dir, "pk-tool", "explicit")
+
+    assert Command(explicit_program).prefer_local(local_dir).run() == "explicit"
+
+
+def test_prefer_local_failure_diagnostics_include_preferred_dirs(
+    tmp_path: pathlib.Path,
+) -> None:
+    first_dir = tmp_path / "first"
+    second_dir = tmp_path / "second"
+    first_dir.mkdir()
+    second_dir.mkdir()
+
+    with pytest.raises(ProcessNotFound) as excinfo:
+        Command(NO_SUCH_PROGRAM).prefer_local(first_dir).prefer_local(second_dir).output()
+
+    searched = excinfo.value.searched
+    assert searched is not None
+    assert str(first_dir) in searched
+    assert str(second_dir) in searched
+
+
 def test_timeout_is_captured_by_output() -> None:
     result = Command(PY, ["-c", "import time; time.sleep(5)"]).timeout(0.3).output()
     assert result.timed_out

{processkit_py-1.2.0 → processkit_py-1.2.1}/tests/test_pipelines.py

@@ -136,7 +136,10 @@ def test_pipeline_stage_timeout_kills_its_whole_subtree(pid_file: pathlib.Path)
     # stage's whole subtree, including a grandchild it forks off -- previously
     # the stage's own kill reached only its direct child, so a forking stage's
     # grandchild survived, kept the pipe open, and stalled the downstream stage.
-    spawner = spawn_grandchild_command(pid_file).timeout(0.3)
+    # Keep this comfortably above Windows process-start latency under xdist:
+    # the timeout must fire after the grandchild PID is observable, otherwise
+    # the probe races the very timeout whose teardown behavior it is testing.
+    spawner = spawn_grandchild_command(pid_file).timeout(2.0)
     downstream = Command(PY, ["-c", "import sys; sys.stdin.read()"])
     pipe = spawner | downstream
 

{processkit_py-1.2.0 → processkit_py-1.2.1}/tests/test_streaming.py

@@ -43,6 +43,14 @@ _ECHO_UPPER = (
     "import sys; [(sys.stdout.write(line.upper()), sys.stdout.flush()) for line in sys.stdin]"
 )
 
+# Echoes the first raw stdin byte to stdout.
+_ECHO_ONE_STDIN_BYTE = (
+    "import sys; "
+    "data = sys.stdin.buffer.read(1); "
+    "sys.stdout.buffer.write(data); "
+    "sys.stdout.buffer.flush()"
+)
+
 # stdout + stderr on both streams.
 _BOTH_STREAMS = (
     "import sys; "
@@ -223,6 +231,32 @@ def test_interactive_stdin_write_accepts_bytearray_and_memoryview() -> None:
     assert asyncio.run(scenario()) == ["FROM-BYTEARRAY", "FROM-MEMORYVIEW"]
 
 
+def test_interactive_stdin_send_control_writes_control_byte() -> None:
+    async def scenario() -> bytes:
+        proc = await Command(PY, ["-c", _ECHO_ONE_STDIN_BYTE]).keep_stdin_open().astart()
+        stdin = proc.take_stdin()
+        await stdin.send_control("d")
+        await stdin.close()
+        result = await proc.aoutput_bytes()
+        return result.stdout
+
+    assert asyncio.run(scenario()) == b"\x04"
+
+
+def test_interactive_stdin_send_control_rejects_invalid_argument() -> None:
+    async def scenario() -> None:
+        proc = await Command(PY, ["-c", _ECHO_ONE_STDIN_BYTE]).keep_stdin_open().astart()
+        stdin = proc.take_stdin()
+        with pytest.raises(ValueError):
+            await stdin.send_control("0")
+        with pytest.raises(ValueError):
+            await stdin.send_control("cc")
+        await stdin.close()
+        await proc.aoutcome()
+
+    asyncio.run(scenario())
+
+
 def test_take_stdin_is_once() -> None:
     # The first take hands over the handle; a second take raises (consumed).
     async def scenario() -> None:

{processkit_py-1.2.0 → processkit_py-1.2.1}/uv.lock

@@ -964,7 +964,7 @@ wheels = [
 
 [[package]]
 name = "processkit-py"
-version = "1.2.0"
+version = "1.2.1"
 source = { editable = "." }
 
 [package.dev-dependencies]