ok-subprocess-runner 0.3__tar.gz

ok_subprocess_runner-0.3/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.3
+Name: ok-subprocess-runner
+Version: 0.3
+Summary: Wrapper for subprocess.run() with defaults and logging
+Author: Dan Egnor
+Author-email: Dan Egnor <egnor@ofb.net>
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/egnor/ok-py-subprocess-runner#readme
+Project-URL: Repository, https://github.com/egnor/ok-py-subprocess-runner.git
+Description-Content-Type: text/markdown
+
+# ok-subprocess-runner for Python
+
+Trivial wrapper for [Python subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run) with defaults and logging.
+
+You probably won't want to use this. Just call `subprocess.run` directly (it's perfectly lovely), write your own trivial helper, or use one of these libraries:
+
+- [sh](https://github.com/amoffat/sh) - call any shell command as if it were a function
+- [Plumbum](https://github.com/tomerfiliba/plumbum) - shell-like syntax for Python
+- [zxpy](https://github.com/tusharsadhwani/zxpy) - `~` string operator to run shell commands
+- [shellpy](https://github.com/lamerman/shellpy) - `\`` string operator to run shell commands
+- [shell](https://github.com/toastdriven/shell) - another wrapper for subprocess
+- [pipepy](https://github.com/kbairak/pipepy) - pipe operators and function wrappers for shell commands
+- [python-shell](https://github.com/ATCode-space/python-shell) - another shell command runner
+
+But, this is _my_ wrapper, and it does these things:
+
+- Checks command return (`check=True`) by default
+- Uses explicit argument vectors (`shell=False`) by default
+- Includes easy-peasy methods to capture stdout as text or lines
+- Logs all commands run, escaped for cut-and-paste rerunning
+- Lets you set defaults for `cwd` and `env` (merged with `os.environ`)
+- Converts [Path-like](https://docs.python.org/3/library/pathlib.html) arguments to strings
+- Passes extra keyword arguments through to `subprocess.run`
+
+Collectively, this is what I want for subprocesses -- tweaks to `subprocess.run` (or `subprocess.check_call`) to make it super easy to [never](https://databio.org/posts/shell_scripts.html) [write](https://news.ycombinator.com/item?id=26682981) [shell](https://samgrayson.me/essays/stop-writing-shell-scripts/) [scripts](https://pythonspeed.com/articles/shell-scripts/) [again](https://dev.to/taikedz/your-bash-scripts-are-rubbish-use-another-language-5dh7). Your mileage will almost certainly vary!
+
+## Usage
+
+Add this package as a dependency:
+
+- `pip install ok-subprocess-runner`
+- OR just copy the `ok_subprocess_runner/` module (it has no dependencies)
+
+Import the module, create an `ok_subprocess_runner.SubprocessRunner` object, and call it to run commands:
+
+```python
+import logging
+import ok_subprocess_runner
+...
+sub = ok_subprocess_runner.SubprocessRunner()
+...
+logging.basicConfig(level=logging.INFO)  # to show the logging
+...
+sub("echo", "Hello World!")
+```
+
+Command arguments are individual function arguments; otherwise, usage is identical to [subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run) including keyword arguments and return value.
+
+The logging output looks like this:
+
+```sh
+$ python test.py
+INFO:root:🐚 echo 'Hello World!'
+Hello World!
+```
+
+Note that arguments are escaped so you can cut-and-paste the command.
+
+## Configuring defaults
+
+`SubprocessRunner` objects have properties that set defaults:
+
+- `.args_prefix` (list of string or Path-like) - prepended to all commands run
+- `.check` (bool) - default for `check` arg (default true)
+- `.cwd` (string or Path-like) - default for `cwd` arg (default empty)
+- `.env` (string dict) - merged with `os.environ` as default `env` arg
+- `.log_level` (int) - level for command logging (default `logging.INFO`)
+
+## Capturing output
+
+`SubprocessRunner` objects have some utility wrappers to capture output:
+
+- `.stdout_text(args, ...)` - returns captured stdout as a text string
+- `.stdout_lines(args, ...)` - returns captured stdout split into lines
+
+## Pass-through
+
+All calls pass keyword arguments through to `subprocess.run`.
+
+```python
+sub = ok_subprocess_runner.SubprocessRunner()
+sub("echo", "Hello World!", check=False, cwd="/tmp", env={"FOO": "BAR"})
+```

ok_subprocess_runner-0.3/README.md

@@ -0,0 +1,83 @@
+# ok-subprocess-runner for Python
+
+Trivial wrapper for [Python subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run) with defaults and logging.
+
+You probably won't want to use this. Just call `subprocess.run` directly (it's perfectly lovely), write your own trivial helper, or use one of these libraries:
+
+- [sh](https://github.com/amoffat/sh) - call any shell command as if it were a function
+- [Plumbum](https://github.com/tomerfiliba/plumbum) - shell-like syntax for Python
+- [zxpy](https://github.com/tusharsadhwani/zxpy) - `~` string operator to run shell commands
+- [shellpy](https://github.com/lamerman/shellpy) - `\`` string operator to run shell commands
+- [shell](https://github.com/toastdriven/shell) - another wrapper for subprocess
+- [pipepy](https://github.com/kbairak/pipepy) - pipe operators and function wrappers for shell commands
+- [python-shell](https://github.com/ATCode-space/python-shell) - another shell command runner
+
+But, this is _my_ wrapper, and it does these things:
+
+- Checks command return (`check=True`) by default
+- Uses explicit argument vectors (`shell=False`) by default
+- Includes easy-peasy methods to capture stdout as text or lines
+- Logs all commands run, escaped for cut-and-paste rerunning
+- Lets you set defaults for `cwd` and `env` (merged with `os.environ`)
+- Converts [Path-like](https://docs.python.org/3/library/pathlib.html) arguments to strings
+- Passes extra keyword arguments through to `subprocess.run`
+
+Collectively, this is what I want for subprocesses -- tweaks to `subprocess.run` (or `subprocess.check_call`) to make it super easy to [never](https://databio.org/posts/shell_scripts.html) [write](https://news.ycombinator.com/item?id=26682981) [shell](https://samgrayson.me/essays/stop-writing-shell-scripts/) [scripts](https://pythonspeed.com/articles/shell-scripts/) [again](https://dev.to/taikedz/your-bash-scripts-are-rubbish-use-another-language-5dh7). Your mileage will almost certainly vary!
+
+## Usage
+
+Add this package as a dependency:
+
+- `pip install ok-subprocess-runner`
+- OR just copy the `ok_subprocess_runner/` module (it has no dependencies)
+
+Import the module, create an `ok_subprocess_runner.SubprocessRunner` object, and call it to run commands:
+
+```python
+import logging
+import ok_subprocess_runner
+...
+sub = ok_subprocess_runner.SubprocessRunner()
+...
+logging.basicConfig(level=logging.INFO)  # to show the logging
+...
+sub("echo", "Hello World!")
+```
+
+Command arguments are individual function arguments; otherwise, usage is identical to [subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run) including keyword arguments and return value.
+
+The logging output looks like this:
+
+```sh
+$ python test.py
+INFO:root:🐚 echo 'Hello World!'
+Hello World!
+```
+
+Note that arguments are escaped so you can cut-and-paste the command.
+
+## Configuring defaults
+
+`SubprocessRunner` objects have properties that set defaults:
+
+- `.args_prefix` (list of string or Path-like) - prepended to all commands run
+- `.check` (bool) - default for `check` arg (default true)
+- `.cwd` (string or Path-like) - default for `cwd` arg (default empty)
+- `.env` (string dict) - merged with `os.environ` as default `env` arg
+- `.log_level` (int) - level for command logging (default `logging.INFO`)
+
+## Capturing output
+
+`SubprocessRunner` objects have some utility wrappers to capture output:
+
+- `.stdout_text(args, ...)` - returns captured stdout as a text string
+- `.stdout_lines(args, ...)` - returns captured stdout split into lines
+
+## Pass-through
+
+All calls pass keyword arguments through to `subprocess.run`.
+
+```python
+sub = ok_subprocess_runner.SubprocessRunner()
+sub("echo", "Hello World!", check=False, cwd="/tmp", env={"FOO": "BAR"})
+```

ok_subprocess_runner-0.3/ok_subprocess_runner/__init__.py

@@ -0,0 +1,123 @@
+"""
+Minor utilities and wrappers for the Python subprocess library
+"""
+
+import dataclasses
+import logging
+import os
+import shlex
+import subprocess
+
+
+@dataclasses.dataclass
+class SubprocessRunner:
+    """Wrapper for subprocess.run, plus some convenience methods.
+
+    sub = SubprocessRunner()
+    sub("echo", "Hello", "World")
+    """
+
+    args_prefix: list = dataclasses.field(default_factory=list)
+    """Arguments (including command) to prepend to args for run methods."""
+
+    check: bool = True
+    """Default subprocess.run setting, True to raise on non-zero exit codes."""
+
+    cwd: str = ""
+    """Default directory for subprocess."""
+
+    env: dict = dataclasses.field(default_factory=dict)
+    """Default environment variables **added** to os.environ for subprocess."""
+
+    log_level: int = logging.INFO
+    """Logging level to print commands, or logging.NOTSET to disable."""
+
+    def __call__(self, *args, **kw):
+        """Wraps subprocess.run (with args directly listed), logging the
+        command (per log_level) and applying defaults from this object."""
+
+        cwd = _path_str(self.cwd) if self.cwd else None
+
+        env = None
+        if self.env:
+            env = {**os.environ, **self.env}
+            env = {k: _path_str(v) for k, v in env.items() if v is not None}
+
+        run_args = [_path_str(a) for a in [*self.args_prefix, *args]]
+        run_kw = {"check": self.check, "cwd": cwd, "env": env, **kw}
+
+        if self.log_level and self.log_level > logging.NOTSET:
+            _log_command(self.log_level, run_args, run_kw)
+
+        return subprocess.run(run_args, **run_kw)
+
+    def stdout_text(self, *args, **kw):
+        """Like run, but captures and directly returns stdout text."""
+
+        kw = {"stdout": subprocess.PIPE, "text": True, **kw}
+        return self(*args, **kw).stdout
+
+    def stdout_lines(self, *args, **kw):
+        """Like stdout_text, but splits the text into lines."""
+
+        return self.stdout_text(*args, **kw).splitlines()
+
+    def copy(self):
+        """Returns a copy of this object with the same defaults."""
+
+        return dataclasses.replace(
+            self, args_prefix=self.args_prefix.copy(), env=self.env.copy()
+        )
+
+
+def _path_str(path_or_str: os.PathLike | str) -> str:
+    if isinstance(path_or_str, str):
+        return path_or_str
+    if isinstance(path_or_str, os.PathLike):
+        return str(path_or_str)
+    raise TypeError(f"Expected str or os.PathLike, got {path_or_str!r}")
+
+
+def _log_command(log_level, args, kw):
+    cd_parts = []
+    if new_cwd := kw.get("cwd"):
+        old_path = os.path.realpath(os.getcwd())
+        new_path = os.path.realpath(new_cwd)
+        if new_path != old_path:
+            try:
+                rel_path = os.path.relpath(new_path, old_path)
+                if len(rel_path) < len(new_path):
+                    new_path = rel_path
+            except ValueError:
+                pass  # different drives on Windows
+            cd_parts = ["cd", shlex.quote(str(new_path)), "&&"]
+
+    env_parts = []
+    if new_env := kw.get("env"):
+        old_env = os.environ
+        repeats, updates = [], []
+        for k, new_v in new_env.items():
+            old_v = old_env.get(k)
+            v_quoted = shlex.quote(new_v) if new_v else ""
+            v_parts = new_v.split(old_v) if old_v else [new_v]
+            if len(v_parts) > 1:
+                v_parts_quoted = [shlex.quote(p) if p else "" for p in v_parts]
+                v_spliced = f"${{{k}}}".join(v_parts_quoted)
+                if len(v_spliced) < len(v_quoted):
+                    v_quoted = v_spliced
+
+            (repeats if old_v == new_v else updates).append(f"{k}={v_quoted}")
+
+        def parts_len(parts):
+            return sum(len(p) for p in parts)
+
+        env_parts = updates
+        if del_keys := old_env.keys() - new_env.keys():
+            env_parts = ["env", *(f"-u{k}" for k in del_keys), *updates, "--"]
+            env_reset_parts = ["env -i", *repeats, *updates, "--"]
+            if parts_len(env_reset_parts) < parts_len(env_parts):
+                env_parts = env_reset_parts
+
+    command_text = " ".join(shlex.quote(arg) for arg in args)
+    log_parts = [*cd_parts, *env_parts, command_text]
+    logging.log(log_level, "🐚 %s", " ".join(log_parts))

ok_subprocess_runner-0.3/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+authors = [{ name = "Dan Egnor", email = "egnor@ofb.net" }]
+description = "Wrapper for subprocess.run() with defaults and logging"
+name = "ok-subprocess-runner"
+readme = "README.md"
+requires-python = ">=3.10"
+urls.Homepage = "https://github.com/egnor/ok-py-subprocess-runner#readme"
+urls.Repository = "https://github.com/egnor/ok-py-subprocess-runner.git"
+version = "0.3"
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["mypy", "pytest", "ruff"]
+
+[tool.mypy]
+exclude_gitignore = true
+files = "."
+
+[tool.ruff]
+line-length = 80
+
+[tool.uv.build-backend]
+module-root = ""