ipy-runlog 0.1.0__py3-none-any.whl

ipy_runlog/__init__.py

@@ -0,0 +1,3 @@
+from .extension import load_ipython_extension, unload_ipython_extension
+
+__all__ = ["load_ipython_extension", "unload_ipython_extension"]

ipy_runlog/config.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib  # type: ignore[no-redef]
+    except ImportError:
+        try:
+            import tomli as tomllib  # type: ignore[no-redef]
+        except ImportError:
+            tomllib = None  # type: ignore[assignment]
+
+
+def load_config(cwd: Path) -> dict[str, Any]:
+    """Load ipy-runlog config from pyproject.toml or .ipy_runlog.toml.
+
+    Search order:
+      1. [tool.ipy-runlog] in pyproject.toml
+      2. .ipy_runlog.toml in cwd
+    """
+    if tomllib is None:
+        return {}
+
+    # 1. pyproject.toml
+    pyproject = cwd / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            with pyproject.open("rb") as f:
+                data = tomllib.load(f)
+            config = data.get("tool", {}).get("ipy-runlog", {})
+            if config:
+                return config
+        except Exception:
+            pass
+
+    # 2. .ipy_runlog.toml
+    fallback = cwd / ".ipy_runlog.toml"
+    if fallback.exists():
+        try:
+            with fallback.open("rb") as f:
+                return tomllib.load(f)
+        except Exception:
+            pass
+
+    return {}

ipy_runlog/extension.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import shlex
+from datetime import datetime
+from pathlib import Path
+
+from IPython.core.magic import Magics, line_magic, magics_class
+
+from .config import load_config
+from .logger import RunLogger
+
+_STATE_ATTR = "_ipy_runlog_state"
+
+_HELP = """\
+Usage: %runlog <command> [ARGS]
+
+Commands:
+  new [NAME] [OPTIONS]  Close current log and start a new one.
+  rename NAME           Rename the current log file (recording continues).
+  stop                  Stop recording manually.
+  status                Show current recording status.
+  help                  Show this help message.
+
+Options for 'new':
+  NAME        Log file name (default: current timestamp)
+  -d PATH     Output directory (default: .ipy_runlog/)
+  --output    Also record cell output (default: off)
+  -h, --help  Show this help message
+"""
+
+_NEW_HELP = """\
+Usage: %runlog new [NAME] [OPTIONS]
+
+Close the current log and start recording to a new file.
+By default, cell input and errors are recorded.
+
+Arguments:
+  NAME        Log file name (default: current timestamp)
+
+Options:
+  -d PATH     Output directory (default: .ipy_runlog/)
+  --output    Also record cell output (default: off)
+  -h, --help  Show this help message"""
+
+
+@magics_class
+class RunLogMagics(Magics):
+    def _state(self) -> dict:
+        state = getattr(self.shell, _STATE_ATTR, None)
+        if state is None:
+            state = {"logger": None, "magics_registered": True}
+            setattr(self.shell, _STATE_ATTR, state)
+        return state
+
+    @line_magic
+    def runlog(self, line: str = "") -> None:
+        try:
+            args = shlex.split(line)
+        except ValueError as exc:
+            print(f"runlog: {exc}")
+            return
+
+        if not args or args[0] in ("-h", "--help", "help"):
+            print(_HELP)
+            return
+
+        command, rest = args[0], " ".join(args[1:])
+
+        if command == "new":
+            self._runlog_new(rest)
+        elif command == "rename":
+            self._runlog_rename(rest)
+        elif command == "stop":
+            self._runlog_stop()
+        elif command == "status":
+            self._runlog_status()
+        else:
+            print(f"runlog: unknown command '{command}'. Run '%runlog help' for usage.")
+
+    def _runlog_new(self, line: str = "") -> None:
+        if _help_requested(line):
+            print(_NEW_HELP)
+            return
+        try:
+            name, directory, record_output = _parse_new_args(line)
+        except ValueError as exc:
+            print(f"runlog new: {exc}")
+            return
+
+        state = self._state()
+        logger: RunLogger | None = state.get("logger")
+        if logger and logger.active:
+            logger.stop()
+
+        config = load_config(Path.cwd())
+        output_path = _resolve_output_path(
+            name or config.get("name"),
+            directory or config.get("directory"),
+        )
+        logger = RunLogger(
+            self.shell,
+            output_path,
+            record_output=record_output or bool(config.get("output", False)),
+            record_error=True,
+        )
+        logger.start()
+        state["logger"] = logger
+        print(f"runlog started: {output_path}")
+
+    def _runlog_rename(self, line: str = "") -> None:
+        try:
+            args = shlex.split(line)
+        except ValueError as exc:
+            print(f"runlog rename: {exc}")
+            return
+
+        if not args:
+            print("runlog rename: a name is required")
+            return
+        if len(args) > 1:
+            print("runlog rename: only one name may be specified")
+            return
+
+        state = self._state()
+        logger: RunLogger | None = state.get("logger")
+        if not logger or not logger.active:
+            print("runlog is not running")
+            return
+
+        old_path = logger.output_path
+        logger.rename(args[0])
+        print(f"runlog renamed: {old_path.name} -> {logger.output_path.name}")
+
+    def _runlog_stop(self) -> None:
+        state = self._state()
+        logger: RunLogger | None = state.get("logger")
+        if not logger or not logger.active:
+            print("runlog is not running")
+            return
+        logger.stop()
+        print("runlog stopped")
+
+    def _runlog_status(self) -> None:
+        state = self._state()
+        logger: RunLogger | None = state.get("logger")
+        if logger and logger.active:
+            print(f"running: {logger.output_path}")
+            return
+        print("stopped")
+
+
+def load_ipython_extension(ipython) -> None:
+    state = getattr(ipython, _STATE_ATTR, None)
+    if state and state.get("magics_registered"):
+        return
+    ipython.register_magics(RunLogMagics)
+    state = {"logger": None, "magics_registered": True}
+    setattr(ipython, _STATE_ATTR, state)
+
+    config = load_config(Path.cwd())
+    output_path = _resolve_output_path(
+        config.get("name"),
+        config.get("directory"),
+    )
+    logger = RunLogger(
+        ipython,
+        output_path,
+        record_output=bool(config.get("output", False)),
+        record_error=True,
+    )
+    logger.start()
+    state["logger"] = logger
+
+
+def unload_ipython_extension(ipython) -> None:
+    state = getattr(ipython, _STATE_ATTR, None)
+    if not state:
+        return
+    logger = state.get("logger")
+    if logger and logger.active:
+        logger.stop()
+    ipython.magics_manager.magics["line"].pop("runlog", None)
+    delattr(ipython, _STATE_ATTR)
+
+
+def _help_requested(line: str) -> bool:
+    try:
+        return any(arg in ("-h", "--help") for arg in shlex.split(line))
+    except ValueError:
+        return False
+
+
+def _parse_new_args(line: str) -> tuple[str | None, str | None, bool]:
+    try:
+        args = shlex.split(line)
+    except ValueError as exc:
+        raise ValueError(str(exc)) from exc
+
+    name = None
+    directory = None
+    record_output = False
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "-d":
+            index += 1
+            if index >= len(args):
+                raise ValueError("-d requires a path")
+            directory = args[index]
+        elif arg == "--output":
+            record_output = True
+        elif arg.startswith("-"):
+            raise ValueError(f"unknown option: {arg}")
+        elif name is None:
+            name = arg
+        else:
+            raise ValueError("only one log name may be specified")
+        index += 1
+
+    return name, directory, record_output
+
+
+def _resolve_output_path(name: str | None, directory: str | None = None) -> Path:
+    filename = name or datetime.now().strftime("%Y%m%d-%H%M%S")
+    if not filename.endswith(".jsonl"):
+        filename = f"{filename}.jsonl"
+    output_directory = Path(directory).expanduser() if directory else Path.cwd() / ".ipy_runlog"
+    return output_directory / filename

ipy_runlog/logger.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import atexit
+import json
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+class RunLogger:
+    def __init__(
+        self,
+        ipython: Any,
+        output_path: Path,
+        *,
+        record_output: bool = False,
+        record_error: bool = True,
+    ) -> None:
+        self._ipython = ipython
+        self.output_path = output_path
+        self._record_output = record_output
+        self._record_error = record_error
+        self._active = False
+        self._last_started_at: str | None = None
+        self._last_code: str = ""
+        self._last_started_dt: datetime | None = None
+
+    @property
+    def active(self) -> bool:
+        return self._active
+
+    def start(self) -> None:
+        if self._active:
+            return
+        self.output_path.parent.mkdir(parents=True, exist_ok=True)
+        self._ipython.events.register("pre_run_cell", self._on_pre_run_cell)
+        self._ipython.events.register("post_run_cell", self._on_post_run_cell)
+        self._active = True
+        atexit.register(self._on_exit)
+        started_at = _now_iso()
+        self._last_started_at = started_at
+        self._append_event(
+            {
+                "event": "recording_started",
+                "started_at": started_at,
+                "path": str(self.output_path),
+            }
+        )
+
+    def stop(self) -> None:
+        if not self._active:
+            return
+        atexit.unregister(self._on_exit)
+        self._ipython.events.unregister("pre_run_cell", self._on_pre_run_cell)
+        self._ipython.events.unregister("post_run_cell", self._on_post_run_cell)
+        self._active = False
+        self._append_event(
+            {
+                "event": "recording_stopped",
+                "stopped_at": _now_iso(),
+                "path": str(self.output_path),
+            }
+        )
+
+    def rename(self, new_name: str) -> None:
+        """Rename the current log file. Recording continues uninterrupted."""
+        if not new_name.endswith(".jsonl"):
+            new_name = f"{new_name}.jsonl"
+        new_path = self.output_path.parent / new_name
+        self.output_path.rename(new_path)
+        self.output_path = new_path
+        self._append_event(
+            {
+                "event": "recording_renamed",
+                "renamed_at": _now_iso(),
+                "path": str(self.output_path),
+            }
+        )
+
+    def _on_exit(self) -> None:
+        """Called by atexit when the Python process exits normally."""
+        if not self._active:
+            return
+        self._ipython.events.unregister("pre_run_cell", self._on_pre_run_cell)
+        self._ipython.events.unregister("post_run_cell", self._on_post_run_cell)
+        self._active = False
+        self._append_event(
+            {
+                "event": "recording_stopped",
+                "stopped_at": _now_iso(),
+                "path": str(self.output_path),
+                "reason": "session_ended",
+            }
+        )
+
+    def _on_pre_run_cell(self, info: Any) -> None:
+        self._last_code = getattr(info, "raw_cell", "") or ""
+        self._last_started_dt = datetime.now()
+        self._last_started_at = self._last_started_dt.isoformat(timespec="microseconds")
+
+    def _on_post_run_cell(self, result: Any) -> None:
+        started_dt = self._last_started_dt or datetime.now()
+        started_at = self._last_started_at or started_dt.isoformat(timespec="microseconds")
+        ended_dt = datetime.now()
+        error = getattr(result, "error_in_exec", None) or getattr(result, "error_before_exec", None)
+        status = "failed" if error else "success"
+        event = {
+            "event": "cell_executed",
+            "started_at": started_at,
+            "ended_at": ended_dt.isoformat(timespec="microseconds"),
+            "elapsed_sec": (ended_dt - started_dt).total_seconds(),
+            "status": status,
+            "execution_count": getattr(result, "execution_count", None),
+            "code": self._last_code,
+        }
+        if self._record_output:
+            event["output"] = _format_output(getattr(result, "result", None))
+        if self._record_error:
+            event["error"] = _format_error(error)
+        self._append_event(event)
+
+    def _append_event(self, payload: dict[str, Any]) -> None:
+        with self.output_path.open("a", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False)
+            f.write("\n")
+
+
+def _now_iso() -> str:
+    return datetime.now().isoformat(timespec="microseconds")
+
+
+def _format_error(error: BaseException | None) -> dict[str, str] | None:
+    if error is None:
+        return None
+    tb = "".join(traceback.format_exception(type(error), error, error.__traceback__))
+    return {
+        "type": type(error).__name__,
+        "message": str(error),
+        "traceback": tb,
+    }
+
+
+def _format_output(output: Any) -> Any:
+    try:
+        json.dumps(output, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return repr(output)
+    return output

ipy_runlog-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: ipy-runlog
+Version: 0.1.0
+Summary: Lightweight JSONL execution logging for IPython.
+Author-email: Hiroyuki Kuromiya <contact@kromiii.info>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kromiii/ipy-runlog
+Project-URL: Repository, https://github.com/kromiii/ipy-runlog
+Project-URL: Bug Tracker, https://github.com/kromiii/ipy-runlog/issues
+Keywords: ipython,jupyter,logging,jsonl,experiment,notebook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipython>=8.0
+Dynamic: license-file
+
+# ipy-runlog
+
+A lightweight IPython extension that records code cell execution history as
+JSON Lines (JSONL).
+
+## Motivation
+
+Experiments are shaped by failed attempts as well as successful ones.
+Recording both preserves the trial-and-error process, giving an experiment
+notebook a coherent story instead of showing only its final results.
+
+## Installation
+
+With `pip`:
+
+```bash
+pip install ipy-runlog
+```
+
+In a `uv` project:
+
+```bash
+uv add ipy-runlog
+```
+
+## Usage
+
+Load the extension — recording starts automatically:
+
+```python
+%load_ext ipy_runlog
+```
+
+The log is written to `.ipy_runlog/` in the current working directory. The
+file name is generated from the current date and time, for example:
+
+```text
+.ipy_runlog/20260611-123456.jsonl
+```
+
+Recording stops automatically when the IPython session ends.
+
+### Commands
+
+Check the current status:
+
+```python
+%runlog status
+```
+
+Switch to a new log file mid-session (closes the current log):
+
+```python
+%runlog new experiment-01
+%runlog new experiment-01 --output   # also record cell output
+%runlog new experiment-01 -d ./logs  # custom output directory
+```
+
+Rename the current log file without interrupting recording:
+
+```python
+%runlog rename feature-extraction
+```
+
+Stop recording manually:
+
+```python
+%runlog stop
+```
+
+Show help:
+
+```python
+%runlog help
+%runlog new --help
+```
+
+### Configuration
+
+You can set defaults in `pyproject.toml`:
+
+```toml
+[tool.ipy-runlog]
+directory = "./logs"
+output = true
+```
+
+Or in `.ipy_runlog.toml` at the project root (used as a fallback when
+`pyproject.toml` is absent or has no `[tool.ipy-runlog]` section):
+
+```toml
+directory = "./logs"
+output = true
+```
+
+Available config keys:
+
+| Key         | Type   | Default          | Description                          |
+|-------------|--------|------------------|--------------------------------------|
+| `directory` | string | `.ipy_runlog/`   | Output directory                     |
+| `output`    | bool   | `false`          | Record cell output                   |
+| `name`      | string | current timestamp| Default log file name                |
+
+> **Note**: Python 3.11+ uses the built-in `tomllib`. For Python 3.9–3.10,
+> install `tomli` to enable config file support: `pip install tomli`.
+
+## How It Works
+
+The extension uses IPython event handlers to monitor cell execution:
+
+- **`pre_run_cell`**: Triggered before a cell is executed. The extension captures the source code of the cell at this point.
+- **`post_run_cell`**: Triggered after a cell finishes executing. The extension calculates the elapsed time, determines if it was successful or failed (including error details), and optionally captures the output.
+
+Each event is appended as a single JSON line to the log file. On normal
+session exit, a final `recording_stopped` event is written automatically via
+`atexit`.
+
+## Log Format
+
+Logs use UTF-8 encoded JSON Lines, with one event per line. New events are
+appended when the target file already exists.
+
+Event types:
+
+- `recording_started`: recording started
+- `cell_executed`: a cell finished executing
+- `recording_renamed`: log file was renamed with `%runlog rename`
+- `recording_stopped`: recording stopped (includes `"reason": "session_ended"` on automatic stop)
+
+A `cell_executed` event contains:
+
+- `started_at` and `ended_at`: local timestamps in ISO 8601 format
+- `elapsed_sec`: execution time in seconds
+- `status`: `success` or `failed`
+- `execution_count`: the IPython execution count
+- `code`: the cell source code
+- `output`: the cell result when `--output` is enabled; non-JSON values are
+  stored using `repr()`
+- `error`: error type, message, and traceback (always recorded on failure)
+
+## Development
+
+Install this repository in editable mode:
+
+```bash
+python -m pip install -e .
+```
+
+With `uv`:
+
+```bash
+uv pip install -e .
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```

ipy_runlog-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ipy_runlog/__init__.py,sha256=prfA4xsdXVbog-8szs_VgnDRom9zzXiAboqr4sRh8Fs,138
+ipy_runlog/config.py,sha256=XzFoL1qEeR_g-cjHBRFc6OxMS3rndn1dskEBAMV6TP0,1252
+ipy_runlog/extension.py,sha256=OQ546uKC3pR_UVgDmxOveKyeScNSGMVFsAa13KODrCc,6812
+ipy_runlog/logger.py,sha256=BqX7MJPNiPXoPJMFVgxRtuXFuoUnxGt5BjyESMICC-4,5066
+ipy_runlog-0.1.0.dist-info/licenses/LICENSE,sha256=ZPYo_6NjzuLSvib6puzPpirM8GfeJr4RLpxYfNR11XA,1074
+ipy_runlog-0.1.0.dist-info/METADATA,sha256=U0THj3_w9Hck4d1BiKhnCVeR7UOOQlHkqMOC5Ip9dIA,4943
+ipy_runlog-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ipy_runlog-0.1.0.dist-info/top_level.txt,sha256=4_HSWhmaP8HbR9C4BSfk35oy_INgNe7WsCqfXmsBCSo,11
+ipy_runlog-0.1.0.dist-info/RECORD,,

ipy_runlog-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ipy_runlog-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hiroyuki Kuromiya
+
+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.

ipy_runlog-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ipy_runlog