ipy-runlog 0.1.0__tar.gz

ipy_runlog-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,159 @@
+# 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/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ipy-runlog"
+version = "0.1.0"
+description = "Lightweight JSONL execution logging for IPython."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Hiroyuki Kuromiya", email = "contact@kromiii.info" }
+]
+keywords = ["ipython", "jupyter", "logging", "jsonl", "experiment", "notebook"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["ipython>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/kromiii/ipy-runlog"
+Repository = "https://github.com/kromiii/ipy-runlog"
+"Bug Tracker" = "https://github.com/kromiii/ipy-runlog/issues"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

ipy_runlog-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ipy_runlog-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/ipy_runlog.egg-info/PKG-INFO

@@ -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/src/ipy_runlog.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/ipy_runlog/__init__.py
+src/ipy_runlog/config.py
+src/ipy_runlog/extension.py
+src/ipy_runlog/logger.py
+src/ipy_runlog.egg-info/PKG-INFO
+src/ipy_runlog.egg-info/SOURCES.txt
+src/ipy_runlog.egg-info/dependency_links.txt
+src/ipy_runlog.egg-info/requires.txt
+src/ipy_runlog.egg-info/top_level.txt
+tests/test_extension.py
+tests/test_logger.py

ipy_runlog-0.1.0/src/ipy_runlog.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ipy_runlog-0.1.0/src/ipy_runlog.egg-info/requires.txt

@@ -0,0 +1 @@
+ipython>=8.0

ipy_runlog-0.1.0/src/ipy_runlog.egg-info/top_level.txt

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

ipy_runlog-0.1.0/tests/test_extension.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from ipy_runlog.extension import RunLogMagics, _parse_new_args, _resolve_output_path
+
+
+# ---------------------------------------------------------------------------
+# _parse_new_args
+# ---------------------------------------------------------------------------
+
+
+def test_parse_new_args_defaults() -> None:
+    assert _parse_new_args("") == (None, None, False)
+
+
+def test_parse_new_args_with_name() -> None:
+    assert _parse_new_args("analysis") == ("analysis", None, False)
+
+
+def test_parse_new_args_with_directory() -> None:
+    assert _parse_new_args("analysis -d './run logs'") == (
+        "analysis",
+        "./run logs",
+        False,
+    )
+
+
+def test_parse_new_args_with_directory_only() -> None:
+    assert _parse_new_args("-d ~/runlogs") == (None, "~/runlogs", False)
+
+
+def test_parse_new_args_with_output() -> None:
+    assert _parse_new_args("analysis --output") == ("analysis", None, True)
+
+
+def test_parse_new_args_output_and_directory() -> None:
+    assert _parse_new_args("analysis -d ./logs --output") == (
+        "analysis",
+        "./logs",
+        True,
+    )
+
+
+def test_parse_new_args_rejects_unknown_option() -> None:
+    with pytest.raises(ValueError, match="unknown option: --only-input"):
+        _parse_new_args("--only-input")
+
+
+def test_parse_new_args_rejects_duplicate_name() -> None:
+    with pytest.raises(ValueError, match="only one log name may be specified"):
+        _parse_new_args("foo bar")
+
+
+# ---------------------------------------------------------------------------
+# %runlog new --help
+# ---------------------------------------------------------------------------
+
+
+def test_runlog_new_help_lists_options(capsys) -> None:
+    magics = RunLogMagics(shell=SimpleNamespace())
+
+    magics.runlog("new --help")
+
+    output = capsys.readouterr().out
+    assert "Usage: %runlog new [NAME] [OPTIONS]" in output
+    assert "-d PATH" in output
+    assert "--output" in output
+
+
+# ---------------------------------------------------------------------------
+# %runlog help / unknown command
+# ---------------------------------------------------------------------------
+
+
+def test_runlog_help_lists_commands(capsys) -> None:
+    magics = RunLogMagics(shell=SimpleNamespace())
+
+    magics.runlog("help")
+
+    output = capsys.readouterr().out
+    assert "Usage: %runlog <command>" in output
+    assert "new" in output
+    assert "rename" in output
+    assert "stop" in output
+    assert "status" in output
+
+
+def test_runlog_unknown_command(capsys) -> None:
+    magics = RunLogMagics(shell=SimpleNamespace())
+
+    magics.runlog("unknown")
+
+    output = capsys.readouterr().out
+    assert "unknown command 'unknown'" in output
+
+
+def test_runlog_stop_when_not_running(capsys) -> None:
+    shell = SimpleNamespace()
+    magics = RunLogMagics(shell=shell)
+
+    from ipy_runlog.extension import _STATE_ATTR
+
+    setattr(shell, _STATE_ATTR, {"logger": None, "magics_registered": True})
+
+    magics.runlog("stop")
+
+    output = capsys.readouterr().out
+    assert "runlog is not running" in output
+
+
+# ---------------------------------------------------------------------------
+# %runlog rename
+# ---------------------------------------------------------------------------
+
+
+def test_runlog_rename_updates_path(tmp_path, capsys) -> None:
+    shell = SimpleNamespace()
+    magics = RunLogMagics(shell=shell)
+
+    from ipy_runlog.logger import RunLogger
+    from ipy_runlog.extension import _STATE_ATTR
+
+    log_file = tmp_path / "old.jsonl"
+    log_file.write_text("", encoding="utf-8")
+    logger = RunLogger(None, log_file)
+    logger._active = True
+
+    setattr(shell, _STATE_ATTR, {"logger": logger, "magics_registered": True})
+
+    with patch.object(logger, "rename") as mock_rename:
+        magics.runlog("rename newname")
+        mock_rename.assert_called_once_with("newname")
+
+
+def test_runlog_rename_requires_name(capsys) -> None:
+    shell = SimpleNamespace()
+    magics = RunLogMagics(shell=shell)
+
+    from ipy_runlog.extension import _STATE_ATTR
+
+    setattr(shell, _STATE_ATTR, {"logger": None, "magics_registered": True})
+
+    magics.runlog("rename")
+
+    output = capsys.readouterr().out
+    assert "a name is required" in output
+
+
+# ---------------------------------------------------------------------------
+# _resolve_output_path
+# ---------------------------------------------------------------------------
+
+
+def test_resolve_output_path_uses_default_directory() -> None:
+    with patch("ipy_runlog.extension.Path.cwd", return_value=Path("/work")):
+        output_path = _resolve_output_path("analysis", None)
+
+    assert output_path == Path("/work/.ipy_runlog/analysis.jsonl")
+
+
+def test_resolve_output_path_uses_specified_directory() -> None:
+    output_path = _resolve_output_path("analysis.jsonl", "./logs")
+
+    assert output_path == Path("logs/analysis.jsonl")

ipy_runlog-0.1.0/tests/test_logger.py

@@ -0,0 +1,159 @@
+import json
+from types import SimpleNamespace
+
+from ipy_runlog.logger import RunLogger
+
+
+def _read_events(path) -> list[dict]:
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines()]
+
+
+def _read_last_event(path) -> dict:
+    return _read_events(path)[-1]
+
+
+def _make_shell():
+    return SimpleNamespace(events=SimpleNamespace(register=lambda *a: None, unregister=lambda *a: None))
+
+
+def test_start_and_stop_record_recording_lifecycle_events(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(_make_shell(), output_path)
+
+    logger.start()
+    assert _read_last_event(output_path)["event"] == "recording_started"
+
+    logger.stop()
+    assert _read_last_event(output_path)["event"] == "recording_stopped"
+
+
+def test_stop_writes_stopped_event_without_reason(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(_make_shell(), output_path)
+    logger.start()
+
+    logger.stop()
+
+    event = _read_last_event(output_path)
+    assert event["event"] == "recording_stopped"
+    assert "reason" not in event
+
+
+def test_on_exit_writes_stopped_event_with_session_ended_reason(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(_make_shell(), output_path)
+    logger.start()
+
+    logger._on_exit()
+
+    event = _read_last_event(output_path)
+    assert event["event"] == "recording_stopped"
+    assert event["reason"] == "session_ended"
+
+
+def test_on_exit_is_idempotent_after_stop(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(_make_shell(), output_path)
+    logger.start()
+    logger.stop()
+
+    # _on_exit should do nothing since _active is already False
+    logger._on_exit()
+
+    events = _read_events(output_path)
+    assert sum(1 for e in events if e["event"] == "recording_stopped") == 1
+
+
+def test_rename_moves_file_and_updates_path(tmp_path) -> None:
+    output_path = tmp_path / "old.jsonl"
+    logger = RunLogger(None, output_path)
+    logger._active = True
+    output_path.write_text('{"event":"recording_started"}\n', encoding="utf-8")
+
+    logger.rename("newname")
+
+    assert not output_path.exists()
+    assert logger.output_path == tmp_path / "newname.jsonl"
+    assert logger.output_path.exists()
+    events = _read_events(logger.output_path)
+    assert events[-1]["event"] == "recording_renamed"
+
+
+def test_rename_adds_jsonl_extension_if_missing(tmp_path) -> None:
+    output_path = tmp_path / "old.jsonl"
+    output_path.write_text("", encoding="utf-8")
+    logger = RunLogger(None, output_path)
+    logger._active = True
+
+    logger.rename("newname")
+
+    assert logger.output_path.suffix == ".jsonl"
+
+
+def test_rename_preserves_existing_jsonl_extension(tmp_path) -> None:
+    output_path = tmp_path / "old.jsonl"
+    output_path.write_text("", encoding="utf-8")
+    logger = RunLogger(None, output_path)
+    logger._active = True
+
+    logger.rename("newname.jsonl")
+
+    assert logger.output_path.name == "newname.jsonl"
+
+
+def test_cell_event_records_code_and_error_by_default(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(None, output_path)
+    error = ValueError("invalid value")
+
+    logger._on_pre_run_cell(SimpleNamespace(raw_cell="raise ValueError()"))
+    logger._on_post_run_cell(
+        SimpleNamespace(
+            execution_count=1,
+            result=None,
+            error_in_exec=error,
+            error_before_exec=None,
+        )
+    )
+
+    event = _read_last_event(output_path)
+    assert event["code"] == "raise ValueError()"
+    assert event["error"]["type"] == "ValueError"
+    assert "output" not in event
+
+
+def test_cell_event_can_record_output_and_omit_error(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(None, output_path, record_output=True, record_error=False)
+
+    logger._on_pre_run_cell(SimpleNamespace(raw_cell="{'answer': 42}"))
+    logger._on_post_run_cell(
+        SimpleNamespace(
+            execution_count=2,
+            result={"answer": 42},
+            error_in_exec=None,
+            error_before_exec=None,
+        )
+    )
+
+    event = _read_last_event(output_path)
+    assert event["output"] == {"answer": 42}
+    assert "error" not in event
+
+
+def test_non_json_output_is_recorded_as_repr(tmp_path) -> None:
+    output_path = tmp_path / "run.jsonl"
+    logger = RunLogger(None, output_path, record_output=True)
+
+    logger._on_pre_run_cell(SimpleNamespace(raw_cell="{1, 2}"))
+    logger._on_post_run_cell(
+        SimpleNamespace(
+            execution_count=3,
+            result={1, 2},
+            error_in_exec=None,
+            error_before_exec=None,
+        )
+    )
+
+    event = _read_last_event(output_path)
+    assert event["output"] == "{1, 2}"