runcorder 0.5.1__py3-none-any.whl

runcorder/__init__.py

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

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/_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/_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/_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

runcorder/_frames.py

@@ -0,0 +1,72 @@
+"""Frame inspection utilities shared by watch display and report writer."""
+
+from __future__ import annotations
+
+import sys
+import sysconfig
+from pathlib import Path
+
+
+def _build_exclusion_prefixes() -> tuple[str, ...]:
+    prefixes: set[str] = set()
+    paths = sysconfig.get_paths()
+    for key in ("stdlib", "platstdlib", "purelib", "platlib"):
+        p = paths.get(key)
+        if p:
+            try:
+                prefixes.add(str(Path(p).resolve()))
+            except (OSError, ValueError):
+                pass
+    for attr in ("prefix", "exec_prefix", "base_prefix"):
+        p = getattr(sys, attr, None)
+        if p:
+            lib_dir = Path(p) / "lib"
+            try:
+                prefixes.add(str(lib_dir.resolve()))
+            except (OSError, ValueError):
+                pass
+    return tuple(prefixes)
+
+
+_EXCLUSION_PREFIXES: tuple[str, ...] = _build_exclusion_prefixes()
+_RUNCORDER_PREFIX: str = str(Path(__file__).parent.resolve())
+
+
+def _is_user_frame(frame) -> bool:
+    """Return True if *frame* is from user code (not stdlib/site-packages/runcorder)."""
+    filename = frame.f_code.co_filename
+    if not filename or filename.startswith("<"):
+        return False
+    try:
+        p = str(Path(filename).resolve())
+    except (OSError, ValueError):
+        return False
+    if p.startswith(_RUNCORDER_PREFIX):
+        return False
+    for prefix in _EXCLUSION_PREFIXES:
+        if p.startswith(prefix):
+            return False
+    return True
+
+
+def _get_param_names(code) -> list[str]:
+    """Return parameter names (excluding non-param locals) from a code object."""
+    n = code.co_argcount + code.co_kwonlyargcount
+    return list(code.co_varnames[:n])
+
+
+def _read_param_reprs(frame) -> dict[str, str]:
+    """Return {param_name: repr(value)} for up to 4 parameters of a frame."""
+    param_names = _get_param_names(frame.f_code)
+    if not param_names:
+        return {}
+    try:
+        locals_dict = frame.f_locals
+    except Exception:
+        return {}
+    result: dict[str, str] = {}
+    for name in param_names[:4]:
+        if name not in locals_dict:
+            continue
+        result[name] = repr(locals_dict[name])
+    return result

runcorder/_location.py

@@ -0,0 +1,86 @@
+"""Report path resolution and log-space management."""
+
+import os
+import sys
+import time
+from pathlib import Path
+
+from runcorder import _display
+
+
+def default_log_dir() -> Path:
+    """Return the default log directory for runcorder reports.
+
+    On macOS or Windows, if ``~/.cache`` already exists, uses
+    ``~/.cache/runcorder/logs/`` instead of the platform-specific location.
+    On Linux, always uses ``~/.cache/runcorder/logs/``.
+    """
+    home = Path.home()
+    dot_cache = home / ".cache"
+    if sys.platform == "linux":
+        return dot_cache / "runcorder" / "logs"
+    # macOS or Windows: prefer ~/.cache if it already exists
+    if dot_cache.is_dir():
+        return dot_cache / "runcorder" / "logs"
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            return Path(local) / "runcorder" / "logs"
+        return home / "AppData" / "Local" / "runcorder" / "logs"
+    # macOS without ~/.cache
+    return home / "Library" / "Caches" / "runcorder" / "logs"
+
+
+def auto_name() -> Path:
+    """Return a timestamped report path inside the default log dir.
+
+    Format: ``YYMMDD-HHMMSS.md``
+    The directory is created if it does not exist.
+    """
+    log_dir = default_log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    from datetime import datetime
+    ts = datetime.now().strftime("%y%m%d-%H%M%S")
+    return log_dir / f"{ts}.md"
+
+
+def check_log_size() -> None:
+    """Check whether the log directory exceeds 100 MB and warn if so.
+
+    Uses a ``size_check`` sentinel file to cache the result; only
+    recalculates when the file is absent or older than 1 day.
+    """
+    log_dir = default_log_dir()
+    if not log_dir.exists():
+        return
+
+    size_check = log_dir / "size_check"
+    total: int | None = None
+
+    if size_check.exists():
+        age = time.time() - size_check.stat().st_mtime
+        if age < 86400:  # 1 day in seconds
+            try:
+                total = int(size_check.read_text().strip())
+            except (ValueError, OSError):
+                pass
+
+    if total is None:
+        total = sum(
+            f.stat().st_size
+            for f in log_dir.iterdir()
+            if f.is_file() and f.name != "size_check"
+        )
+        try:
+            size_check.write_text(str(total))
+            # Touch to reset mtime explicitly (write_text already does this,
+            # but be explicit for clarity)
+            os.utime(size_check, None)
+        except OSError:
+            pass
+
+    mb = total / (1024 * 1024)
+    if mb > 100:
+        _display.warning(
+            f"runcorder log size is {mb:.0f} MB. Clean with `runcorder clean`"
+        )