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

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

@@ -1,5 +1,37 @@
 # runspec-linux-core Changelog
 
+## [0.3.4] — 2026-07-07
+
+Fix `create_venv` producing an unreadable `750` venv directory when the caller's
+umask is `027` (typical under `sudo -n -u <svc>` with a PAM-set login umask).
+`python -m venv` honours the current umask, so a shared service-account venv
+was landing owner-only instead of the `755` a stock `python -m venv <dest>`
+produces under the default `022` umask, locking every non-owner console out —
+contrary to the "shared between several consoles" use case the helper is built
+for.
+
+After the venv-creation step, `create_venv` now runs
+`chmod -R u=rwX,go=rX <dest>` to normalise the tree to `755` on directories and
+`644` on files while preserving the `+x` on real executables in `bin/` (capital
+`X` only sets execute on directories and files that already have some execute
+bit). The subsequent `chmod 2775 <dest>/logs` still gets the last word on the
+logs directory, and `chgrp -R <group>` (when passed) still runs. When `run_as`
+is set the new chmod runs as that user too.
+
+## [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.4}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.3.2
+Version: 0.3.4
 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
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

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

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.3.2"
+version = "0.3.4"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []
 
 [project.optional-dependencies]
 dev = [
-    "ruff",
+    "ruff==0.15.20",
     "mypy",
     "pytest>=8.0",
 ]

{runspec_linux_core-0.3.2 → runspec_linux_core-0.3.4}/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.4/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.2 → runspec_linux_core-0.3.4}/runspec_linux_core/venvs.py

@@ -92,12 +92,17 @@ def create_venv(
 ) -> dict:
     """Create a virtualenv at ``dest`` from a specific ``python`` interpreter.
 
-    Always uses ``--symlinks``. Then creates ``<dest>/logs`` mode ``2775`` (setgid,
-    so new audit-log files inherit the directory's group) and, if ``group`` is set,
-    ``chgrp -R`` the venv to it — enabling a shared service-account venv that several
-    consoles read/write. With ``run_as`` set every step runs as that user (so the
-    venv is owned by it). Raises ValueError on a non-executable interpreter / bad
-    name, or CommandError on a failed step.
+    Always uses ``--symlinks``. Then normalises the tree to ``u=rwX,go=rX`` so
+    directories are ``755`` and executables in ``bin/`` keep their ``+x`` — matching
+    what a plain ``python -m venv`` produces under a default ``022`` umask, regardless
+    of the caller's umask (``sudo -n -u <svc>`` often lands at ``027``, which would
+    otherwise leave the venv at ``750`` and lock other consoles out). Then creates
+    ``<dest>/logs`` mode ``2775`` (setgid, so new audit-log files inherit the
+    directory's group) and, if ``group`` is set, ``chgrp -R`` the venv to it —
+    enabling a shared service-account venv that several consoles read/write. With
+    ``run_as`` set every step runs as that user (so the venv is owned by it). Raises
+    ValueError on a non-executable interpreter / bad name, or CommandError on a
+    failed step.
     """
     if not (os.path.isfile(python) and os.access(python, os.X_OK)):
         raise ValueError(f"not an executable file: {python!r} (pick a real interpreter, not the system default)")
@@ -114,6 +119,8 @@ def create_venv(
 
     _check(_run(_become([python, "-m", "venv", *flags, dest], run_as, become_method)), "venv creation", run_as)
 
+    _check(_run(_become(["chmod", "-R", "u=rwX,go=rX", dest], run_as, become_method)), "chmod venv", run_as)
+
     logs_dir = os.path.join(dest, "logs")
     _check(_run(_become(["mkdir", "-p", logs_dir], run_as, become_method)), "logs dir", run_as)
     if group:

runspec_linux_core-0.3.4/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("   ")

{runspec_linux_core-0.3.2 → runspec_linux_core-0.3.4}/tests/test_venvs.py

@@ -69,9 +69,12 @@ def test_create_venv_uses_symlinks_and_logs(monkeypatch: pytest.MonkeyPatch) ->
     venv_cmd = calls[0]
     assert venv_cmd[:4] == [sys.executable, "-m", "venv", "--symlinks"]
     assert venv_cmd[-1] == "/opt/v1"
+    # chmod -R u=rwX,go=rX normalises the tree to 755-dirs/644-files regardless of
+    # the caller's umask (a sudo -u <svc> shell often lands at 027 → 750).
+    assert calls[1] == ["chmod", "-R", "u=rwX,go=rX", "/opt/v1"]
     # mkdir -p logs, then chmod 2775 logs (no group → no chgrp step).
-    assert calls[1] == ["mkdir", "-p", "/opt/v1/logs"]
-    assert calls[2] == ["chmod", "2775", "/opt/v1/logs"]
+    assert calls[2] == ["mkdir", "-p", "/opt/v1/logs"]
+    assert calls[3] == ["chmod", "2775", "/opt/v1/logs"]
     assert result == {
         "python": sys.executable,
         "dest": "/opt/v1",
@@ -100,7 +103,8 @@ def test_create_venv_run_as_escalates_every_step(monkeypatch: pytest.MonkeyPatch
     venvs.create_venv(sys.executable, "/opt/v1", run_as="svc", group="consoles")
     for cmd in calls:
         assert cmd[:4] == ["sudo", "-n", "-u", "svc"]
-    # chgrp -R consoles /opt/v1 runs between mkdir and chmod.
+    # The umask-normalising chmod and the chgrp both run as svc too.
+    assert ["sudo", "-n", "-u", "svc", "chmod", "-R", "u=rwX,go=rX", "/opt/v1"] in calls
     assert ["sudo", "-n", "-u", "svc", "chgrp", "-R", "consoles", "/opt/v1"] in calls