penrun 0.2.0__tar.gz → 0.2.2__tar.gz

penrun-0.2.2/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.3
+Name: penrun
+Version: 0.2.2
+Summary: Run any command inside a well-defined, timestamped artifacts directory.
+Author: AISEC Pentesting Team
+License: Apache-2.0
+Maintainer: Stefan Tatschner, Tobias Specht
+Maintainer-email: Stefan Tatschner <stefan.tatschner@aisec.fraunhofer.de>, Tobias Specht <tobias.specht@aisec.fraunhofer.de>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: AISEC Pentesting Team
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# penrun
+
+This tool was initially rescued from the gallia [commit history](https://github.com/Fraunhofer-AISEC/gallia/commit/985664905b6ef352db6fdc895af2ac79492539da) and ported to Python.
+
+`penrun` runs any command inside a well-defined, timestamped artifacts directory. Point it at a test,
+scan, or anything else you invoke repeatedly, and every run gets its own directory with the command's
+compressed output and exit code - so results are never overwritten and old runs stay reproducible.
+
+## Requirements
+
+Python 3.14+, standard library only. No runtime dependencies.
+
+## Installation
+
+```console
+$ uvx penrun -h
+```
+
+Without installing, `uv run penrun` also works straight out of a checkout.
+
+## Quick start: normal mode
+
+Run any command; `penrun` creates `penrun-artifacts/<command>/run-<timestamp>/` for it:
+
+```console
+$ penrun ls -lah
+$ tree penrun-artifacts/ls
+penrun-artifacts/ls
+├── LATEST -> run-20260723-101334.123456
+└── run-20260723-101334.123456
+    ├── META.json  # command, start/end time, exit code, environment (with -e), error (on failure)
+    └── OUTPUT.zst # combined stdout+stderr, zstd-compressed
+```
+
+`LATEST` always points at the most recent run of that command, regardless of tags or where
+`artifacts_template` places the timestamped directory (see below).
+
+`penrun` sets these environment variables for COMMAND:
+
+- `PENRUN_COMMAND` - the command as run, shell-quoted.
+- `PENRUN_ARTIFACTS` - the absolute path of this run's artifacts directory.
+- `PENRUN_BATCH_MODE=1` - only in batch mode.
+- `PENRUN_PWD_CONF`/`PENRUN_GIT_ROOT_CONF`/`PENRUN_USER_CONF` - path of each config file found while
+  searching (see [Configuration](#configuration)), regardless of which one was actually used.
+
+Run `penrun -h` for the full list of flags.
+
+## Quick start: batch mode
+
+Batch mode (`-b`) reads a command - or command fragment - per line from stdin and runs each one,
+sequentially by default (`-j N` for up to `N` in parallel):
+
+```console
+$ printf 'true\nfalse\ntrue\n' | penrun -b
+```
+
+Pass `-T` with a template to turn plain input lines into full commands; `{1}` is replaced with the
+line. Since every job below runs `curl`, add `-N` to name each job's directory after its input line
+instead of the program name - otherwise they'd all land in the same `curl/` directory:
+
+```console
+$ printf 'example.com\nexample.org\n' | penrun -b -N -T 'curl -Lo {1}.html https://{1}'
+$ tree -L 2 penrun-artifacts/curl
+penrun-artifacts/curl
+├── LATEST -> run-20260723-101334.123456
+└── run-20260723-101334.123456
+    ├── example.com
+    └── example.org
+```
+
+For programmatic callers that already know each job's command and artifacts directory name, `-J`/`--json`
+reads newline-delimited JSON objects instead of plain lines - one `{"executable": "...", "args": [...],
+"dirname": "..."}` per line (`dirname` is optional, falling back to `executable`'s name):
+
+```console
+$ printf '%s\n' \
+    '{"executable": "curl", "args": ["-Lo", "example.com.html", "https://example.com"], "dirname": "example.com"}' \
+    '{"executable": "curl", "args": ["-Lo", "example.org.html", "https://example.org"], "dirname": "example.org"}' \
+  | penrun -b -J
+```
+
+Run `penrun -h` for the rest of the batch flags (`-S`, `-u`, ...).
+
+## Python API
+
+`penrun` exposes the same functionality as an importable library, so other Python tools can drive it
+without going through the CLI.
+
+Single command - equivalent to `penrun -t staging curl https://example.com`:
+
+```python
+import penrun
+
+options = penrun.RunOptions(config=penrun.Config(artifacts_base="penrun-artifacts"), tag="staging")
+penrun.run(["curl", "https://example.com"], options)
+```
+
+Batch, every job running the same program - equivalent to the `-J` example above:
+
+```python
+batch = penrun.Batch(
+    executable="curl",
+    shared_args=["-Lo"],
+    jobs=[
+        penrun.BatchJob(args=["example.com.html", "https://example.com"], dirname="example.com"),
+        penrun.BatchJob(args=["example.org.html", "https://example.org"], dirname="example.org"),
+    ],
+)
+penrun.run_batched(batch, options, group_by_executable=True, schedule=penrun.ScheduleOptions(max_workers=2))
+```
+
+Batch mixing completely different programs, by overriding `executable` on the jobs that don't run
+`Batch.executable`:
+
+```python
+batch = penrun.Batch(
+    executable="nmap",
+    jobs=[
+        penrun.BatchJob(args=["-oA", "scan", "example.com"], dirname="nmap"),
+        penrun.BatchJob(executable="curl", args=["-I", "https://example.com"], dirname="curl-head"),
+    ],
+)
+penrun.run_batched(batch, options)
+```
+
+Errors raise `penrun.PenrunError` subclasses (e.g. `penrun.CommandNotFoundError`, `penrun.ConfigError`,
+each carrying a matching `.exit_code`) instead of exiting the process. If `RunOptions.timeout`/`-w` fires,
+COMMAND is killed and Python's built-in `TimeoutError` is raised instead.
+
+## Configuration
+
+`penrun` looks for a config file in this order and stops at the first match: `./.penrun.toml`,
+`$(git rev-parse --show-toplevel)/.penrun.toml`, then `~/.config/penrun/config.toml`. See
+[`config.toml`](config.toml) for all available keys with explanations.
+
+## Development
+
+```console
+$ just lint
+$ just fmt
+$ just test
+```

penrun-0.2.2/README.md

@@ -0,0 +1,148 @@
+<!--
+SPDX-FileCopyrightText: AISEC Pentesting Team
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# penrun
+
+This tool was initially rescued from the gallia [commit history](https://github.com/Fraunhofer-AISEC/gallia/commit/985664905b6ef352db6fdc895af2ac79492539da) and ported to Python.
+
+`penrun` runs any command inside a well-defined, timestamped artifacts directory. Point it at a test,
+scan, or anything else you invoke repeatedly, and every run gets its own directory with the command's
+compressed output and exit code - so results are never overwritten and old runs stay reproducible.
+
+## Requirements
+
+Python 3.14+, standard library only. No runtime dependencies.
+
+## Installation
+
+```console
+$ uvx penrun -h
+```
+
+Without installing, `uv run penrun` also works straight out of a checkout.
+
+## Quick start: normal mode
+
+Run any command; `penrun` creates `penrun-artifacts/<command>/run-<timestamp>/` for it:
+
+```console
+$ penrun ls -lah
+$ tree penrun-artifacts/ls
+penrun-artifacts/ls
+├── LATEST -> run-20260723-101334.123456
+└── run-20260723-101334.123456
+    ├── META.json  # command, start/end time, exit code, environment (with -e), error (on failure)
+    └── OUTPUT.zst # combined stdout+stderr, zstd-compressed
+```
+
+`LATEST` always points at the most recent run of that command, regardless of tags or where
+`artifacts_template` places the timestamped directory (see below).
+
+`penrun` sets these environment variables for COMMAND:
+
+- `PENRUN_COMMAND` - the command as run, shell-quoted.
+- `PENRUN_ARTIFACTS` - the absolute path of this run's artifacts directory.
+- `PENRUN_BATCH_MODE=1` - only in batch mode.
+- `PENRUN_PWD_CONF`/`PENRUN_GIT_ROOT_CONF`/`PENRUN_USER_CONF` - path of each config file found while
+  searching (see [Configuration](#configuration)), regardless of which one was actually used.
+
+Run `penrun -h` for the full list of flags.
+
+## Quick start: batch mode
+
+Batch mode (`-b`) reads a command - or command fragment - per line from stdin and runs each one,
+sequentially by default (`-j N` for up to `N` in parallel):
+
+```console
+$ printf 'true\nfalse\ntrue\n' | penrun -b
+```
+
+Pass `-T` with a template to turn plain input lines into full commands; `{1}` is replaced with the
+line. Since every job below runs `curl`, add `-N` to name each job's directory after its input line
+instead of the program name - otherwise they'd all land in the same `curl/` directory:
+
+```console
+$ printf 'example.com\nexample.org\n' | penrun -b -N -T 'curl -Lo {1}.html https://{1}'
+$ tree -L 2 penrun-artifacts/curl
+penrun-artifacts/curl
+├── LATEST -> run-20260723-101334.123456
+└── run-20260723-101334.123456
+    ├── example.com
+    └── example.org
+```
+
+For programmatic callers that already know each job's command and artifacts directory name, `-J`/`--json`
+reads newline-delimited JSON objects instead of plain lines - one `{"executable": "...", "args": [...],
+"dirname": "..."}` per line (`dirname` is optional, falling back to `executable`'s name):
+
+```console
+$ printf '%s\n' \
+    '{"executable": "curl", "args": ["-Lo", "example.com.html", "https://example.com"], "dirname": "example.com"}' \
+    '{"executable": "curl", "args": ["-Lo", "example.org.html", "https://example.org"], "dirname": "example.org"}' \
+  | penrun -b -J
+```
+
+Run `penrun -h` for the rest of the batch flags (`-S`, `-u`, ...).
+
+## Python API
+
+`penrun` exposes the same functionality as an importable library, so other Python tools can drive it
+without going through the CLI.
+
+Single command - equivalent to `penrun -t staging curl https://example.com`:
+
+```python
+import penrun
+
+options = penrun.RunOptions(config=penrun.Config(artifacts_base="penrun-artifacts"), tag="staging")
+penrun.run(["curl", "https://example.com"], options)
+```
+
+Batch, every job running the same program - equivalent to the `-J` example above:
+
+```python
+batch = penrun.Batch(
+    executable="curl",
+    shared_args=["-Lo"],
+    jobs=[
+        penrun.BatchJob(args=["example.com.html", "https://example.com"], dirname="example.com"),
+        penrun.BatchJob(args=["example.org.html", "https://example.org"], dirname="example.org"),
+    ],
+)
+penrun.run_batched(batch, options, group_by_executable=True, schedule=penrun.ScheduleOptions(max_workers=2))
+```
+
+Batch mixing completely different programs, by overriding `executable` on the jobs that don't run
+`Batch.executable`:
+
+```python
+batch = penrun.Batch(
+    executable="nmap",
+    jobs=[
+        penrun.BatchJob(args=["-oA", "scan", "example.com"], dirname="nmap"),
+        penrun.BatchJob(executable="curl", args=["-I", "https://example.com"], dirname="curl-head"),
+    ],
+)
+penrun.run_batched(batch, options)
+```
+
+Errors raise `penrun.PenrunError` subclasses (e.g. `penrun.CommandNotFoundError`, `penrun.ConfigError`,
+each carrying a matching `.exit_code`) instead of exiting the process. If `RunOptions.timeout`/`-w` fires,
+COMMAND is killed and Python's built-in `TimeoutError` is raised instead.
+
+## Configuration
+
+`penrun` looks for a config file in this order and stops at the first match: `./.penrun.toml`,
+`$(git rev-parse --show-toplevel)/.penrun.toml`, then `~/.config/penrun/config.toml`. See
+[`config.toml`](config.toml) for all available keys with explanations.
+
+## Development
+
+```console
+$ just lint
+$ just fmt
+$ just test
+```

{penrun-0.2.0 → penrun-0.2.2}/pyproject.toml

@@ -8,11 +8,16 @@ build-backend = "uv_build"
 
 [project]
 name = "penrun"
-version = "0.2.0"
+version = "0.2.2"
 description = "Run any command inside a well-defined, timestamped artifacts directory."
+readme = "README.md"
 requires-python = ">=3.14"
 license = { text = "Apache-2.0" }
 authors = [{ name = "AISEC Pentesting Team" }]
+maintainers = [
+    { name = "Stefan Tatschner", email = "stefan.tatschner@aisec.fraunhofer.de" },
+    { name = "Tobias Specht", email = "tobias.specht@aisec.fraunhofer.de" },
+]
 
 [project.scripts]
 penrun = "penrun.cli:main"
@@ -32,29 +37,16 @@ target-version = "py314"
 line-length = 110
 
 [tool.ruff.lint]
-select = [
-    "B",    # flake8-bugbear
+# extend-select adds to ruff's own (already fairly broad) default rule set,
+# instead of replacing it like `select` would - so only list rules here that
+# the default doesn't already cover.
+extend-select = [
     "A",    # flake8-builtins
-    "ASYNC",# flake8-async
-    "C4",   # flake8-comprehensions
-    "E",    # pycodestlye
-    "F",    # pyflakes
-    "FA",   # flake8-future-annotations
-    "FLY",  # flynt
-    "FURB", # refurb
-    "I",    # isort
     "IC",   # flake8-import-conventions
-    "LOG",  # flake8-logging
-    "PGH",  # pygrep-hooks
-    "PIE",  # flake8-pie
-    "PL",   # pylint
-    "PTH",  # flake8-use-pathlib
     "Q",    # flake8-quotes
     "RSE",  # flake8-raise
-    "RUF100",  # unused-noqa
     "TD",   # flake8-todos
     "TID",  # flake8-tidy-imports
-    "UP",   # pyupgrade
 ]
 
 [tool.mypy]

{penrun-0.2.0 → penrun-0.2.2}/src/penrun/artifacts.py

@@ -45,7 +45,7 @@ def render_artifactsdir(template: str, placeholders: ArtifactsPlaceholders) -> P
 
 
 def timestamp_now() -> str:
-    return datetime.now().strftime("%Y%m%d-%H%M%S.%f")
+    return datetime.now().astimezone().strftime("%Y%m%d-%H%M%S.%f")
 
 
 def now_iso() -> str:

{penrun-0.2.0 → penrun-0.2.2}/src/penrun/locking.py

@@ -6,6 +6,7 @@ import fcntl
 import os
 from pathlib import Path
 from types import TracebackType
+from typing import Self
 
 from penrun.output import log
 
@@ -15,7 +16,7 @@ class FileLock:
         self._path = path
         self._fd: int | None = None
 
-    def __enter__(self) -> FileLock:
+    def __enter__(self) -> Self:
         self._path.parent.mkdir(parents=True, exist_ok=True)
         self._path.touch(exist_ok=True)
         self._fd = os.open(self._path, os.O_RDONLY)

penrun-0.2.0/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.3
-Name: penrun
-Version: 0.2.0
-Summary: Run any command inside a well-defined, timestamped artifacts directory.
-Author: AISEC Pentesting Team
-License: Apache-2.0
-Requires-Python: >=3.14