runcorder 0.5.1__tar.gz

runcorder-0.5.1/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

runcorder-0.5.1/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+__pycache__/
+.pytest_cache/
+uv.lock
+/dist/

runcorder-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sasha Ovsankin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runcorder-0.5.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: runcorder
+Version: 0.5.1
+Summary: Always-on flight recorder for Python scripts: live watch line while it runs, compact Markdown report when it crashes or gets stuck.
+Project-URL: Homepage, https://github.com/SashaOv/runcorder
+Project-URL: Source, https://github.com/SashaOv/runcorder
+Project-URL: Documentation, https://github.com/SashaOv/runcorder/blob/main/docs/user.md
+Author: Sasha Ovsankin
+License: MIT License
+        
+        Copyright (c) 2026 Sasha Ovsankin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.13
+Requires-Dist: cyclopts>=3
+Description-Content-Type: text/markdown
+
+# Runcorder
+
+An always-on flight recorder for Python scripts: live watch line while it runs, compact Markdown report when it crashes or gets stuck.
+
+See [docs/user.md](docs/user.md).
+
+## Development
+
+Runcorder uses [uv](https://docs.astral.sh/uv/) for environment management. Requires Python 3.13+.
+
+### Set up
+
+```bash
+uv sync
+```
+
+### Test
+
+```bash
+uv run pytest
+```
+
+### Build
+
+```bash
+uv build
+```
+
+Artifacts land in `dist/` (wheel and sdist).

runcorder-0.5.1/README.md

@@ -0,0 +1,29 @@
+# Runcorder
+
+An always-on flight recorder for Python scripts: live watch line while it runs, compact Markdown report when it crashes or gets stuck.
+
+See [docs/user.md](docs/user.md).
+
+## Development
+
+Runcorder uses [uv](https://docs.astral.sh/uv/) for environment management. Requires Python 3.13+.
+
+### Set up
+
+```bash
+uv sync
+```
+
+### Test
+
+```bash
+uv run pytest
+```
+
+### Build
+
+```bash
+uv build
+```
+
+Artifacts land in `dist/` (wheel and sdist).

runcorder-0.5.1/docs/user.md

@@ -0,0 +1,168 @@
+# Runcorder User Manual
+
+## Why Runcorder
+
+Runcorder is an always-on flight recorder for yout Python scripts. While your script runs it shows a live watch line — elapsed time, custom context, and the current call chain — so you can see what the script is actually doing instead of staring at a silent terminal. If the script crashes or gets stuck, Runcorder writes a compact Markdown report with the filtered traceback, recent watch snapshots, and the surrounding run context.
+
+It sits in the gap between a raw traceback and a full tracing system. There is no setup cost beyond adding it to the command line, it stays out of your way on successful runs, and the failure artifact is designed to paste straight into an intelligent-tool workflow without extra cleanup. Start with Runcorder on every script; escalate to deeper tracing only when you need it.
+
+## Quickstart
+
+### Install from PyPI
+
+```bash
+pip install runcorder
+```
+
+Runcorder requires Python 3.13 or newer.
+
+### Run a script
+
+No code changes required — just run your script under Runcorder:
+
+```bash
+python -m runcorder my_script.py --arg1 --arg2
+```
+
+The script runs as if you had launched it directly with `python my_script.py`, except that a watch line appears on stderr while it runs and a report is written on failure.
+
+### Add context (optional)
+
+Inside your script, call `runcorder.context(...)` to surface variables on the live watch line and in the final report:
+
+```python
+import runcorder
+
+for epoch in range(10):
+    runcorder.context(epoch=epoch, loss=current_loss)
+    train_one_epoch()
+```
+
+### Explicit integration
+
+If you prefer to instrument from inside the program rather than using the CLI wrapper:
+
+```python
+import runcorder
+
+@runcorder.instrument
+def main():
+    run_pipeline()
+```
+
+or as a scoped context manager:
+
+```python
+with runcorder.session(tail=True):
+    run_pipeline()
+```
+
+### Find and clean reports
+
+Reports land in `~/.cache/runcorder/logs/YYMMDD-HHMMSS.md` by default (platform cache dir on systems without `~/.cache`). The path is printed to stderr the first time a report is written.
+
+```bash
+runcorder clean          # delete reports older than 1 day
+runcorder clean 7d       # older than 7 days
+runcorder clean 12h      # older than 12 hours
+```
+
+## API Reference
+
+### `python -m runcorder <script.py> [args...]`
+
+Run `<script.py>` in the same interpreter with Runcorder instrumentation installed before user code executes. Extra arguments are forwarded to the script.
+
+Exit behavior:
+
+- script exits normally → exit status `0`
+- script raises `SystemExit` → that status is propagated
+- any other uncaught exception → report is written, non-zero exit
+
+### `runcorder clean [AGE]`
+
+Delete reports older than `AGE` from the default log directory. `AGE` is a positive integer followed by `d` (days), `h` (hours), or `m` (minutes). Default: `1d`.
+
+### `runcorder.session(**options)`
+
+Return a context manager that records a session for the enclosed block:
+
+```python
+with runcorder.session(output="report.md", tail=True, watch_interval=3.0):
+    run_pipeline()
+```
+
+### `runcorder.instrument`
+
+Decorator form of `session()`. Supports both bare and keyword forms:
+
+```python
+@runcorder.instrument
+def main(): ...
+
+@runcorder.instrument(output="run.md", tail=True)
+def main(): ...
+```
+
+### `runcorder.context(**kwargs)`
+
+Set or update session-level key/value pairs. Keys are additive across calls; pass `None` to remove a key. The current context renders as `key=value` pairs on every watch line and is attached to each watch snapshot in the report. Called outside an active session, it warns once and is otherwise a no-op.
+
+```python
+runcorder.context(epoch=5, loss=0.312)
+runcorder.context(loss=None)            # remove "loss"
+```
+
+### Session options
+
+Shared by `session()` and `instrument`:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `output` | auto-named | Report path. When unset, Runcorder writes to `~/.cache/runcorder/logs/YYMMDD-HHMMSS.md`. Applied only when a report is actually emitted. |
+| `tail` | `False` | Buffer stdout/stderr and include a rolling tail in the report. |
+| `watch_interval` | `3.0` | Seconds between stack samples. Minimum `0.5`. |
+| `watch_inplace` | `True` | Rewrite the previous status line in place when no foreign output has appeared and the stderr sink supports in-place updates. Set `False` for native code or subprocesses that write to the terminal. |
+| `stuck_timeout` | `30.0` | Seconds of unchanged stack before a stuck notice is emitted and a snapshot is captured. Set `0` to disable. |
+| `short_traceback` | `True` | Replace Python's default traceback with a concise two-line notice pointing to the report. Set `False` to keep the full traceback on stderr alongside the report. |
+
+When `short_traceback=True` (the default), an uncaught exception prints:
+
+```
+ExceptionType: message
+[runcorder] see report at <path>
+```
+
+The full traceback is always preserved in the report.
+
+### Integration with logging
+
+Runcorder messages are written using standard Python logging, with one exception: the watch line uses direct stderr writes when `watch_inplace=True` and the process is running interactively on a TTY.
+
+When the watch line is emitted via logging, Runcorder only logs it when the line has changed from the previous sample. Runcorder does not modify logging settings.
+
+### When a report is written
+
+A report is produced only when one of these happens:
+
+- the run exits via an uncaught exception
+- stuck detection fires
+
+Successful runs produce no report, even when `output` is set. On the first write, Runcorder prints `[runcorder] report is written to <path>` to stderr.
+
+### Report format
+
+A Markdown file with a YAML front matter block followed by sections:
+
+- **Front matter** — `command`, `cwd`, `python`, `started_at`.
+- **Stuck snapshot** — filtered stack at the moment stuck was detected (when present).
+- **Exception** — type, message, and filtered traceback (on failure). Each stack frame includes function arguments with their `repr()` values at capture time.
+- **Watch snapshots** — recent status lines with context variables.
+- **Output tail** — combined stdout/stderr tail (only when `tail=True`).
+- **Summary** — `ended_at`, `duration_s`, `exit_status` (integer or `"exception"`). Absent if the process is killed before the session finishes.
+
+### Limitations
+
+- Watch samples the main thread only; no C-extension or subprocess frames.
+- Stream tracking is best-effort: native writes that bypass Python stream objects are not detected.
+- Not a TUI — the single-line display degrades to append-only output on non-interactive or non-rewritable sinks (redirected logs, notebook cells, batch-system log collectors).

runcorder-0.5.1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runcorder"
+version = "0.5.1"
+description = "Always-on flight recorder for Python scripts: live watch line while it runs, compact Markdown report when it crashes or gets stuck."
+readme = "README.md"
+requires-python = ">=3.13"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Sasha Ovsankin" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Logging",
+]
+dependencies = [
+    "cyclopts>=3",
+]
+
+[project.urls]
+Homepage = "https://github.com/SashaOv/runcorder"
+Source = "https://github.com/SashaOv/runcorder"
+Documentation = "https://github.com/SashaOv/runcorder/blob/main/docs/user.md"
+
+[project.scripts]
+runcorder = "runcorder.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runcorder"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

runcorder-0.5.1/src/runcorder/__init__.py

@@ -0,0 +1,4 @@
+from runcorder._session import instrument, session
+from runcorder._context import context
+
+__all__ = ["instrument", "session", "context"]

runcorder-0.5.1/src/runcorder/__main__.py

@@ -0,0 +1,45 @@
+"""Entry point for ``python -m runcorder path/to/script.py [args...]``."""
+
+import runpy
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print(
+            "Usage: python -m runcorder <script.py> [args...]\n"
+            "       runcorder clean [--age AGE]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # If the first argument looks like a sub-command, delegate to the CLI app
+    if sys.argv[1] in ("clean",):
+        from runcorder.cli import app
+        app()
+        return
+
+    script = sys.argv[1]
+    # Shift argv so the script sees its own name and arguments
+    sys.argv = sys.argv[1:]
+
+    from runcorder._session import InstrumentContext
+
+    ctx = InstrumentContext()
+    ctx.start()
+    exc_info = None
+    try:
+        runpy.run_path(script, run_name="__main__")
+    except SystemExit:
+        ctx.stop()
+        raise
+    except BaseException:
+        exc_info = sys.exc_info()
+        ctx.stop(exception_info=exc_info)
+        raise
+    else:
+        ctx.stop()
+
+
+if __name__ == "__main__":
+    main()

runcorder-0.5.1/src/runcorder/_capture.py

@@ -0,0 +1,38 @@
+"""sys.excepthook install / uninstall helpers."""
+
+import sys
+from typing import Callable, Optional
+
+_original_excepthook: Optional[Callable] = None
+
+
+def install_exception_hook(on_exception: Callable) -> None:
+    """Wrap ``sys.excepthook`` to call *on_exception* before delegating.
+
+    *on_exception* receives ``(exc_type, exc_value, exc_tb)``.
+    The previously-installed hook (or ``sys.__excepthook__``) is still called
+    afterward so that the default traceback printout is preserved.
+    """
+    global _original_excepthook
+    _original_excepthook = sys.excepthook
+
+    def _hook(exc_type, exc_value, exc_tb):
+        try:
+            on_exception(exc_type, exc_value, exc_tb)
+        except Exception:
+            pass  # never let our callback suppress the original behaviour
+        previous = _original_excepthook
+        if previous is not None and previous is not _hook:
+            previous(exc_type, exc_value, exc_tb)
+        else:
+            sys.__excepthook__(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _hook
+
+
+def uninstall_exception_hook() -> None:
+    """Restore the excepthook that was in place before :func:`install_exception_hook`."""
+    global _original_excepthook
+    if _original_excepthook is not None:
+        sys.excepthook = _original_excepthook
+        _original_excepthook = None

runcorder-0.5.1/src/runcorder/_context.py

@@ -0,0 +1,49 @@
+"""Session-level key/value store for runcorder context variables."""
+
+import warnings
+
+_active_store: dict | None = None
+_warned: bool = False
+
+
+def context(**kwargs) -> None:
+    """Set or update session-level context variables.
+
+    Keys are additive; setting a key to None removes it.
+    Warns once per process if called outside an active session.
+    """
+    global _active_store, _warned
+    if _active_store is None:
+        if not _warned:
+            warnings.warn(
+                "runcorder.context() called outside an active session; call has no effect",
+                stacklevel=2,
+            )
+            _warned = True
+        return
+    for k, v in kwargs.items():
+        if v is None:
+            _active_store.pop(k, None)
+        else:
+            _active_store[k] = v
+
+
+def _install() -> dict:
+    """Install (activate) the context store. Called by session start."""
+    global _active_store, _warned
+    _active_store = {}
+    _warned = False
+    return _active_store
+
+
+def _uninstall() -> None:
+    """Uninstall (deactivate) the context store. Called by session stop."""
+    global _active_store
+    _active_store = None
+
+
+def get() -> dict:
+    """Return a copy of the current context store, or empty dict if no session."""
+    if _active_store is None:
+        return {}
+    return dict(_active_store)

runcorder-0.5.1/src/runcorder/_display.py

@@ -0,0 +1,147 @@
+"""Centralised output for runcorder.
+
+All runcorder-originated messages go through the ``runcorder`` logger so they
+route predictably under batch-job logging configurations.  The watch line is
+special-cased: when ``watch_inplace=True`` and the session is writing to a
+tty, it uses ANSI escape sequences for in-place updates; otherwise it falls
+through to the logger with per-line dedup against the previous sample.
+
+Per spec: runcorder does not change logging settings.  If the ``runcorder``
+logger (or any ancestor) already has handlers, we respect that and do not
+install our own.  When nothing is configured, we attach a minimal stderr
+handler so default installs are usable out of the box.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from runcorder._tracker import _WriteTracker
+
+
+logger = logging.getLogger("runcorder")
+
+
+class _StderrHandler(logging.Handler):
+    """StreamHandler variant that reads ``sys.stderr`` on every emit.
+
+    The stdlib StreamHandler captures ``sys.stderr`` at construction time.
+    That breaks when ``sys.stderr`` is later redirected (pytest's capsys,
+    batch-job log collectors, etc.), so we resolve it dynamically.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            msg = self.format(record)
+            sys.stderr.write(msg + "\n")
+            sys.stderr.flush()
+        except Exception:
+            self.handleError(record)
+
+
+def _ensure_handler() -> None:
+    """Install a default stderr handler if neither the runcorder logger nor
+    any ancestor has been configured.  Called on every message so that a
+    user who calls ``logging.basicConfig()`` *before* the first runcorder
+    message wins — their root handler is used instead of ours, and records
+    propagate without duplication."""
+    if logger.hasHandlers():
+        return
+    handler = _StderrHandler()
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    if logger.level == logging.NOTSET:
+        logger.setLevel(logging.INFO)
+
+
+def info(msg: str) -> None:
+    _ensure_handler()
+    logger.info(msg)
+
+
+def warning(msg: str) -> None:
+    _ensure_handler()
+    logger.warning(msg)
+
+
+def error(msg: str) -> None:
+    _ensure_handler()
+    logger.error(msg)
+
+
+# ---------------------------------------------------------------------------
+# WatchSink
+
+
+class WatchSink:
+    """Routes the watch line to either a tty (in-place escape updates) or the
+    runcorder logger (with dedup against the previous line)."""
+
+    def __init__(
+        self,
+        orig_stderr,
+        tracker: Optional["_WriteTracker"],
+        watch_inplace: bool,
+    ) -> None:
+        self._orig_stderr = orig_stderr
+        self._tracker = tracker
+        self._watch_inplace = watch_inplace
+        self._wrote_last_inplace: bool = False
+        self._last_logged_line: Optional[str] = None
+
+    @property
+    def tty_sink(self):
+        return self._orig_stderr if self._orig_stderr is not None else sys.stderr
+
+    def _is_tty(self) -> bool:
+        sink = self.tty_sink
+        try:
+            return hasattr(sink, "isatty") and sink.isatty()
+        except Exception:
+            return False
+
+    def emit(self, line: str) -> None:
+        if self._watch_inplace and self._is_tty():
+            self._emit_inplace(line)
+        else:
+            self._emit_logged(line)
+
+    def _emit_inplace(self, line: str) -> None:
+        sink = self.tty_sink
+        if self._tracker is not None and self._tracker.foreign_wrote:
+            self._tracker.reset_foreign()
+            self._wrote_last_inplace = False
+        try:
+            if self._wrote_last_inplace:
+                sink.write(f"\033[A\r\033[K{line}\n")
+            else:
+                sink.write(f"{line}\n")
+            sink.flush()
+        except Exception:
+            pass
+        self._wrote_last_inplace = True
+        self._last_logged_line = None
+
+    def _emit_logged(self, line: str) -> None:
+        if line == self._last_logged_line:
+            return
+        _ensure_handler()
+        logger.info(line)
+        self._last_logged_line = line
+        self._wrote_last_inplace = False
+
+    def clear_inplace(self) -> None:
+        """Erase the last in-place status line (tty path only)."""
+        if not self._wrote_last_inplace:
+            return
+        sink = self.tty_sink
+        try:
+            if self._is_tty():
+                sink.write("\r\033[K")
+                sink.flush()
+        except Exception:
+            pass
+        self._wrote_last_inplace = False