runspec-linux-core 0.3.2__tar.gz → 0.3.3__tar.gz

{runspec_linux_core-0.3.2 → runspec_linux_core-0.3.3}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # runspec-linux-core Changelog
 
+## [0.3.3] — 2026-06-22
+
+Add `commands.py` — the pure logic behind the new `runspec-linux` `which`
+runnable:
+
+- **`which(names, *, all_matches=False, path=None)`** — locate executables on the
+  search PATH, like the `which` command. `names` is a single command or a list
+  (a string is split on whitespace, so `"python3 pip3"` resolves both).
+  `all_matches` returns every match across the PATH (not just the first that
+  would run); `path` overrides the search path (defaults to `$PATH`, falling back
+  to `os.defpath`). A name containing a path separator is checked directly rather
+  than searched. Returns `{path, all_found, results: [{name, found, path,
+  paths}]}` and raises `ValueError` when no name is given.
+
 ## [0.3.2] — 2026-06-21
 
 Add `venvs.py` — the pure logic behind three new `runspec-linux` runnables for

{runspec_linux_core-0.3.2 → runspec_linux_core-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.3.2
+Version: 0.3.3
 Summary: Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)
 Requires-Python: >=3.10
 Provides-Extra: dev

{runspec_linux_core-0.3.2 → runspec_linux_core-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.3.2"
+version = "0.3.3"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []

{runspec_linux_core-0.3.2 → runspec_linux_core-0.3.3}/runspec_linux_core/__init__.py

@@ -9,6 +9,7 @@ Each function does the work and returns plain data; failures raise (see
 ``runspec_linux_core.errors``).
 """
 
+from runspec_linux_core.commands import which
 from runspec_linux_core.containers import (
     container_logs,
     list_containers,
@@ -83,4 +84,6 @@ __all__ = [
     "configure_pip",
     # tcp
     "nc_send",
+    # commands
+    "which",
 ]

runspec_linux_core-0.3.3/runspec_linux_core/commands.py

@@ -0,0 +1,76 @@
+"""Command-location helpers — find executables on the search PATH."""
+
+import os
+
+
+def _is_executable(path: str) -> bool:
+    return os.path.isfile(path) and os.access(path, os.X_OK)
+
+
+def _resolve(name: str, dirs: list[str]) -> list[str]:
+    """Return every executable match for ``name`` across ``dirs`` (in order)."""
+    # A name with a path separator is a path, not a bare command: check it
+    # directly rather than searching the PATH (mirrors `which`/`shutil.which`).
+    if os.sep in name or (os.altsep and os.altsep in name):
+        return [os.path.abspath(name)] if _is_executable(name) else []
+    seen: set[str] = set()
+    matches: list[str] = []
+    for d in dirs:
+        full = os.path.join(d, name)
+        if full in seen:
+            continue
+        seen.add(full)
+        if _is_executable(full):
+            matches.append(full)
+    return matches
+
+
+def which(
+    names: str | list[str],
+    *,
+    all_matches: bool = False,
+    path: str | None = None,
+) -> dict:
+    """Locate executables on the search PATH, like the ``which`` command.
+
+    ``names`` is a single command name or a list of them; a string is split on
+    whitespace so ``"python3 pip3"`` resolves both. ``all_matches`` returns every
+    match found across the PATH (not just the first one that would run). ``path``
+    overrides the search path (defaults to ``$PATH``, falling back to
+    ``os.defpath``).
+
+    Returns::
+
+        {"path": "<search path used>",
+         "all_found": bool,                       # every requested name resolved
+         "results": [{"name": str, "found": bool,
+                      "path": str | None,         # first match, else None
+                      "paths": [str, ...]}]}      # all matches if all_matches
+
+    Raises ``ValueError`` when no name is given.
+    """
+    if isinstance(names, str):
+        names = names.split()
+    names = [n for n in names if n]
+    if not names:
+        raise ValueError("no command name given")
+
+    search = os.environ.get("PATH", os.defpath) if path is None else path
+    dirs = [d or os.curdir for d in search.split(os.pathsep)]
+
+    results = []
+    for name in names:
+        matches = _resolve(name, dirs)
+        results.append(
+            {
+                "name": name,
+                "found": bool(matches),
+                "path": matches[0] if matches else None,
+                "paths": matches if all_matches else matches[:1],
+            }
+        )
+    return {
+        "path": search,
+        "all_found": all(r["found"] for r in results),
+        "results": results,
+    }

runspec_linux_core-0.3.3/tests/test_commands.py

@@ -0,0 +1,88 @@
+import os
+import stat
+
+import pytest
+
+from runspec_linux_core import which
+
+
+def _make_exec(path):
+    path.write_text("#!/bin/sh\n")
+    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def test_which_finds_executable(tmp_path):
+    binp = tmp_path / "mytool"
+    _make_exec(binp)
+    res = which("mytool", path=str(tmp_path))
+    assert res["all_found"] is True
+    assert res["path"] == str(tmp_path)
+    (r,) = res["results"]
+    assert r == {
+        "name": "mytool",
+        "found": True,
+        "path": str(binp),
+        "paths": [str(binp)],
+    }
+
+
+def test_which_not_found(tmp_path):
+    res = which("nope", path=str(tmp_path))
+    assert res["all_found"] is False
+    assert res["results"][0] == {
+        "name": "nope",
+        "found": False,
+        "path": None,
+        "paths": [],
+    }
+
+
+def test_which_skips_non_executable(tmp_path):
+    (tmp_path / "plain").write_text("data")
+    res = which("plain", path=str(tmp_path))
+    assert res["results"][0]["found"] is False
+
+
+def test_which_multiple_names_space_separated(tmp_path):
+    _make_exec(tmp_path / "a")
+    res = which("a b", path=str(tmp_path))
+    assert [r["name"] for r in res["results"]] == ["a", "b"]
+    assert res["results"][0]["found"] is True
+    assert res["results"][1]["found"] is False
+    assert res["all_found"] is False
+
+
+def test_which_accepts_list(tmp_path):
+    _make_exec(tmp_path / "a")
+    res = which(["a"], path=str(tmp_path))
+    assert res["all_found"] is True
+
+
+def test_which_first_match_wins_all_matches_lists_every_dir(tmp_path):
+    d1 = tmp_path / "d1"
+    d2 = tmp_path / "d2"
+    d1.mkdir()
+    d2.mkdir()
+    _make_exec(d1 / "dup")
+    _make_exec(d2 / "dup")
+    search = os.pathsep.join([str(d1), str(d2)])
+
+    first = which("dup", path=search)
+    assert first["results"][0]["path"] == str(d1 / "dup")
+    assert first["results"][0]["paths"] == [str(d1 / "dup")]
+
+    allm = which("dup", all_matches=True, path=search)
+    assert allm["results"][0]["paths"] == [str(d1 / "dup"), str(d2 / "dup")]
+
+
+def test_which_name_with_path_separator_checked_directly(tmp_path):
+    binp = tmp_path / "tool"
+    _make_exec(binp)
+    res = which(str(binp))
+    assert res["results"][0]["found"] is True
+    assert res["results"][0]["path"] == str(binp)
+
+
+def test_which_empty_raises():
+    with pytest.raises(ValueError):
+        which("   ")