snapshot-kernel 0.1.0__tar.gz

snapshot_kernel-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Luca de Alfaro
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

snapshot_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: snapshot-kernel
+Version: 0.1.0
+Summary: A snapshotting Python kernel with REST API
+Author-email: Luca de Alfaro <dealfaro@acm.org>
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: bottle
+Requires-Dist: cheroot
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file

snapshot_kernel-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snapshot-kernel"
+version = "0.1.0"
+description = "A snapshotting Python kernel with REST API"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{name = "Luca de Alfaro", email = "dealfaro@acm.org"}]
+dependencies = ["bottle", "cheroot"]
+requires-python = ">=3.9"
+
+[project.optional-dependencies]
+test = ["pytest"]

snapshot_kernel-0.1.0/setup.cfg

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

snapshot_kernel-0.1.0/snapshot_kernel/__init__.py

@@ -0,0 +1,3 @@
+from .kernel import SnapshotKernel
+
+__all__ = ["SnapshotKernel"]

snapshot_kernel-0.1.0/snapshot_kernel/kernel.py

@@ -0,0 +1,461 @@
+"""Snapshot Checkpointing Python Kernel.
+
+Stores immutable execution states (snapshots of variables, modules, timestamps)
+and creates new states by executing code against existing ones.
+"""
+
+import ast
+import base64
+import copy
+import ctypes
+import datetime
+import io
+import os
+import sys
+import threading
+import traceback
+import types
+import uuid
+
+
+def _snapshot_namespace(namespace):
+    """Create a snapshot of a namespace dict.
+
+    Modules are stored by reference (they are singletons).
+    Everything else is deep-copied when possible, with a fallback
+    to storing a direct reference for non-copyable objects.
+    """
+    snapshot = {}
+    for key, value in namespace.items():
+        if key.startswith("__") and key.endswith("__"):
+            continue
+        if isinstance(value, types.ModuleType):
+            snapshot[key] = value
+        else:
+            try:
+                snapshot[key] = copy.deepcopy(value)
+            except Exception:
+                snapshot[key] = value
+    return snapshot
+
+
+def _format_object(obj):
+    """Extract all available rich representations from a Python object.
+
+    Returns (data_dict, metadata_dict) where data_dict maps MIME types
+    to their string content.  Binary representations (PNG, JPEG, PDF) are
+    base64-encoded.
+    """
+    data = {}
+    metadata = {}
+
+    # Always provide text/plain.
+    try:
+        data["text/plain"] = repr(obj)
+    except Exception:
+        data["text/plain"] = "<repr failed>"
+
+    # Prefer _repr_mimebundle_() when available.
+    mimebundle_method = getattr(obj, "_repr_mimebundle_", None)
+    if callable(mimebundle_method):
+        try:
+            result = mimebundle_method()
+            if isinstance(result, tuple):
+                bundle_data, bundle_meta = result
+                data.update(bundle_data)
+                metadata.update(bundle_meta)
+            elif isinstance(result, dict):
+                data.update(result)
+            return data, metadata
+        except Exception:
+            pass
+
+    # Fall back to individual _repr_*_() methods.
+    _repr_methods = [
+        ("_repr_html_", "text/html", False),
+        ("_repr_markdown_", "text/markdown", False),
+        ("_repr_latex_", "text/latex", False),
+        ("_repr_json_", "application/json", False),
+        ("_repr_svg_", "image/svg+xml", False),
+        ("_repr_png_", "image/png", True),
+        ("_repr_jpeg_", "image/jpeg", True),
+        ("_repr_pdf_", "application/pdf", True),
+    ]
+    for method_name, mime_type, is_binary in _repr_methods:
+        method = getattr(obj, method_name, None)
+        if not callable(method):
+            continue
+        try:
+            result = method()
+        except Exception:
+            continue
+        if result is None:
+            continue
+        if is_binary and isinstance(result, bytes):
+            result = base64.b64encode(result).decode("ascii")
+        data[mime_type] = result
+
+    return data, metadata
+
+
+class State:
+    """An immutable snapshot of an execution environment."""
+
+    def __init__(self, name, namespace):
+        self.name = name
+        self.namespace = namespace
+        self.timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+class ThreadSafeWriter:
+    """A writer that redirects writes to per-thread StringIO buffers.
+
+    When a per-thread buffer is set, writes go there. Otherwise, writes
+    go to the original stream. This allows capturing stdout/stderr per
+    execution thread without interfering with other threads.
+    """
+
+    def __init__(self, original):
+        self._original = original
+        self._local = threading.local()
+
+    def set_buffer(self, buf):
+        """Set a StringIO buffer for the current thread."""
+        self._local.buffer = buf
+
+    def clear_buffer(self):
+        """Remove the buffer for the current thread."""
+        self._local.buffer = None
+
+    def get_buffer(self):
+        """Return the current thread's buffer, or None."""
+        return getattr(self._local, "buffer", None)
+
+    def write(self, text):
+        buf = self.get_buffer()
+        if buf is not None:
+            buf.write(text)
+        else:
+            self._original.write(text)
+
+    def flush(self):
+        buf = self.get_buffer()
+        if buf is not None:
+            buf.flush()
+        else:
+            self._original.flush()
+
+    # Pass through attributes like encoding, isatty, etc.
+    def __getattr__(self, name):
+        return getattr(self._original, name)
+
+
+class DisplayCollector:
+    """Thread-safe collector for display_data outputs.
+
+    Each execution thread gets its own list of outputs so that
+    concurrent executions do not interfere with each other.
+    """
+
+    def __init__(self):
+        self._local = threading.local()
+
+    def set_list(self):
+        """Initialise an empty output list for the current thread."""
+        self._local.outputs = []
+
+    def clear_list(self):
+        """Remove the output list for the current thread."""
+        self._local.outputs = None
+
+    def get_outputs(self):
+        """Return the current thread's collected outputs."""
+        return getattr(self._local, "outputs", None) or []
+
+    def add(self, obj):
+        """Format *obj* via _format_object and append a display_data entry."""
+        data, metadata = _format_object(obj)
+        outputs = getattr(self._local, "outputs", None)
+        if outputs is not None:
+            outputs.append({
+                "output_type": "display_data",
+                "data": data,
+                "metadata": metadata,
+            })
+
+    def add_raw(self, entry):
+        """Append a pre-formatted output entry directly."""
+        outputs = getattr(self._local, "outputs", None)
+        if outputs is not None:
+            outputs.append(entry)
+
+
+def _capture_figures(collector):
+    """If matplotlib.pyplot is loaded, save all open figures as PNG and
+    append them to *collector*, then close them."""
+    plt = sys.modules.get("matplotlib.pyplot")
+    if plt is None:
+        return
+    for fig_num in plt.get_fignums():
+        fig = plt.figure(fig_num)
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", bbox_inches="tight")
+        buf.seek(0)
+        png_b64 = base64.b64encode(buf.read()).decode("ascii")
+        collector.add_raw({
+            "output_type": "display_data",
+            "data": {"image/png": png_b64, "text/plain": "<Figure>"},
+            "metadata": {},
+        })
+    plt.close("all")
+
+
+class SnapshotKernel:
+    """Checkpointing Python kernel that stores and forks execution states."""
+
+    def __init__(self):
+        self._states = {}
+        self._lock = threading.Lock()
+        self._executions = {}
+        self._exec_lock = threading.Lock()
+        self._io_lock = threading.Lock()
+        self._display_collector = DisplayCollector()
+        os.environ.setdefault("MPLBACKEND", "Agg")
+        self.reset()
+
+    def _ensure_writers(self):
+        """Install ThreadSafeWriter wrappers if they are not already in place.
+
+        This is called at the start of every execution so that
+        external code (e.g. pytest) that replaces sys.stdout/stderr
+        does not break per-thread capture.
+        """
+        with self._io_lock:
+            if not isinstance(sys.stdout, ThreadSafeWriter):
+                sys.stdout = ThreadSafeWriter(sys.stdout)
+            if not isinstance(sys.stderr, ThreadSafeWriter):
+                sys.stderr = ThreadSafeWriter(sys.stderr)
+
+    def reset(self):
+        """Clear all states and create a fresh 'initial' state."""
+        with self._lock:
+            self._states.clear()
+            self._states["initial"] = State("initial", {})
+
+    def list_states(self):
+        """Return a list of all stored state names."""
+        with self._lock:
+            return list(self._states.keys())
+
+    def get_state(self, state_name):
+        """Return a serializable dict describing the given state, or None."""
+        with self._lock:
+            state = self._states.get(state_name)
+        if state is None:
+            return None
+        variables = {}
+        for key, value in state.namespace.items():
+            variables[key] = {
+                "type": type(value).__name__,
+                "repr": repr(value),
+            }
+        return {
+            "name": state.name,
+            "timestamp": state.timestamp,
+            "variables": variables,
+        }
+
+    def delete_state(self, state_name):
+        """Remove the named state. Returns True if it existed."""
+        with self._lock:
+            return self._states.pop(state_name, None) is not None
+
+    def _make_display_func(self):
+        """Create a ``display(*objs)`` function for use inside executed code.
+
+        The function formats each object and appends it to the
+        thread-local DisplayCollector.
+        """
+        collector = self._display_collector
+
+        def display(*objs):
+            for obj in objs:
+                ipython_display = getattr(obj, "_ipython_display_", None)
+                if callable(ipython_display):
+                    ipython_display(display=display)
+                else:
+                    collector.add(obj)
+
+        return display
+
+    def _install_matplotlib_hook(self):
+        """Replace ``plt.show()`` with a wrapper that captures figures.
+
+        Returns a cleanup function that restores the original ``plt.show()``,
+        or *None* if matplotlib is not loaded.
+        """
+        plt = sys.modules.get("matplotlib.pyplot")
+        if plt is None:
+            return None
+        original_show = plt.show
+        collector = self._display_collector
+
+        def _hooked_show(*args, **kwargs):
+            _capture_figures(collector)
+
+        plt.show = _hooked_show
+        return lambda: setattr(plt, "show", original_show)
+
+    def execute(self, code, exec_id, state_name, new_state_name=None):
+        """Execute code against a state and store the resulting state.
+
+        Returns a dict with keys: output, state_name, error.
+        """
+        if new_state_name is None:
+            new_state_name = uuid.uuid4().hex
+
+        # Snapshot the source state's namespace.
+        with self._lock:
+            source = self._states.get(state_name)
+        if source is None:
+            return {
+                "output": [],
+                "state_name": None,
+                "error": {"ename": "StateNotFound", "evalue": state_name, "traceback": []},
+            }
+        namespace = _snapshot_namespace(source.namespace)
+        namespace["__builtins__"] = __builtins__
+
+        # Register this execution for possible interruption.
+        with self._exec_lock:
+            self._executions[exec_id] = threading.current_thread().ident
+
+        # Ensure ThreadSafeWriter wrappers are in place.
+        self._ensure_writers()
+
+        # Set up per-thread output capture.
+        stdout_writer = sys.stdout
+        stderr_writer = sys.stderr
+        stdout_buf = io.StringIO()
+        stderr_buf = io.StringIO()
+        stdout_writer.set_buffer(stdout_buf)
+        stderr_writer.set_buffer(stderr_buf)
+
+        # Set up display collector and inject display() into namespace.
+        self._display_collector.set_list()
+        display_func = self._make_display_func()
+        namespace["display"] = display_func
+
+        # Hook plt.show() if matplotlib is already imported.
+        restore_show = self._install_matplotlib_hook()
+
+        output = []
+        error = None
+        last_expr_value = None
+
+        try:
+            # Parse the code and split out the last expression if applicable.
+            tree = ast.parse(code)
+            last_expr_node = None
+            if tree.body and isinstance(tree.body[-1], ast.Expr):
+                last_expr_node = tree.body.pop()
+
+            # Execute all statements except the last expression.
+            if tree.body:
+                exec(compile(tree, "<cell>", "exec"), namespace)
+
+            # Evaluate the last expression to capture its value.
+            if last_expr_node is not None:
+                expr_code = compile(
+                    ast.Expression(body=last_expr_node.value), "<cell>", "eval"
+                )
+                last_expr_value = eval(expr_code, namespace)
+
+            # If matplotlib was imported during execution, install hook and
+            # capture any remaining open figures.
+            if restore_show is None:
+                restore_show = self._install_matplotlib_hook()
+            _capture_figures(self._display_collector)
+
+        except KeyboardInterrupt:
+            error = {
+                "ename": "KeyboardInterrupt",
+                "evalue": "",
+                "traceback": ["KeyboardInterrupt"],
+            }
+        except Exception as exc:
+            error = {
+                "ename": type(exc).__name__,
+                "evalue": str(exc),
+                "traceback": traceback.format_exception(type(exc), exc, exc.__traceback__),
+            }
+        finally:
+            # Collect captured output.
+            stdout_writer.clear_buffer()
+            stderr_writer.clear_buffer()
+
+            stdout_text = stdout_buf.getvalue()
+            stderr_text = stderr_buf.getvalue()
+
+            if stdout_text:
+                output.append({"output_type": "stream", "name": "stdout", "text": stdout_text})
+            if stderr_text:
+                output.append({"output_type": "stream", "name": "stderr", "text": stderr_text})
+
+            # Display data outputs collected via display() and matplotlib.
+            collected = self._display_collector.get_outputs()
+            prev_count = len(collected)
+            output.extend(collected)
+
+            # Last expression result with rich MIME types.
+            if last_expr_value is not None:
+                ipython_display = getattr(last_expr_value, "_ipython_display_", None)
+                if callable(ipython_display):
+                    ipython_display(display=display_func)
+                    output.extend(self._display_collector.get_outputs()[prev_count:])
+                else:
+                    data, metadata = _format_object(last_expr_value)
+                    output.append({
+                        "output_type": "execute_result",
+                        "data": data,
+                        "metadata": metadata,
+                    })
+
+            # Clean up display collector and matplotlib hook.
+            self._display_collector.clear_list()
+            if restore_show is not None:
+                restore_show()
+
+            # Remove display from namespace so it doesn't persist in state.
+            namespace.pop("display", None)
+
+            # Unregister execution.
+            with self._exec_lock:
+                self._executions.pop(exec_id, None)
+
+        # On success, store the new state; on error, do not.
+        result_state_name = None
+        if error is None:
+            new_ns = _snapshot_namespace(namespace)
+            new_state = State(new_state_name, new_ns)
+            with self._lock:
+                self._states[new_state_name] = new_state
+            result_state_name = new_state_name
+
+        return {
+            "output": output,
+            "state_name": result_state_name,
+            "error": error,
+        }
+
+    def interrupt(self, exec_id):
+        """Interrupt a running execution by raising KeyboardInterrupt in its thread."""
+        with self._exec_lock:
+            thread_ident = self._executions.get(exec_id)
+        if thread_ident is None:
+            return False
+        res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
+            ctypes.c_ulong(thread_ident),
+            ctypes.py_object(KeyboardInterrupt),
+        )
+        return res == 1

snapshot_kernel-0.1.0/snapshot_kernel/main.py

@@ -0,0 +1,105 @@
+"""Bottle REST API server for the Snapshot Kernel."""
+
+import argparse
+import json
+
+import bottle
+
+from .kernel import SnapshotKernel
+
+app = bottle.Bottle()
+kernel = SnapshotKernel()
+_token = None
+
+
+@app.hook("before_request")
+def check_auth():
+    """Verify the token URL parameter on every request."""
+    if _token is not None:
+        if bottle.request.params.get("token") != _token:
+            bottle.abort(401, "Invalid or missing token.")
+
+
+@app.post("/execute")
+def execute():
+    """Execute code against a state."""
+    body = bottle.request.json
+    if not body:
+        bottle.abort(400, "Request body must be JSON.")
+    code = body.get("code", "")
+    exec_id = body.get("exec_id")
+    state_name = body.get("state_name")
+    new_state_name = body.get("new_state_name")
+    if exec_id is None or state_name is None:
+        bottle.abort(400, "exec_id and state_name are required.")
+    result = kernel.execute(code, exec_id, state_name, new_state_name)
+    bottle.response.content_type = "application/json"
+    return json.dumps(result)
+
+
+@app.get("/states")
+def list_states():
+    """Return all stored state names."""
+    bottle.response.content_type = "application/json"
+    return json.dumps({"states": kernel.list_states()})
+
+
+@app.get("/states/<name>")
+def get_state(name):
+    """Return details of a single state."""
+    state = kernel.get_state(name)
+    if state is None:
+        bottle.abort(404, "State not found.")
+    bottle.response.content_type = "application/json"
+    return json.dumps(state)
+
+
+@app.delete("/states/<name>")
+def delete_state(name):
+    """Delete a state."""
+    if kernel.delete_state(name):
+        return json.dumps({"deleted": name})
+    bottle.abort(404, "State not found.")
+
+
+@app.post("/reset")
+def reset():
+    """Reset the kernel to its initial state."""
+    kernel.reset()
+    bottle.response.content_type = "application/json"
+    return json.dumps({"status": "ok"})
+
+
+@app.post("/interrupt")
+def interrupt():
+    """Interrupt a running execution."""
+    body = bottle.request.json
+    if not body or "exec_id" not in body:
+        bottle.abort(400, "exec_id is required.")
+    success = kernel.interrupt(body["exec_id"])
+    bottle.response.content_type = "application/json"
+    return json.dumps({"interrupted": success})
+
+
+def main():
+    """Entry point: parse arguments and start the Cheroot-backed server."""
+    parser = argparse.ArgumentParser(description="Snapshot Kernel Server")
+    parser.add_argument(
+        "--bind", default="127.0.0.1:8080",
+        help="Address to bind to (default: 127.0.0.1:8080)",
+    )
+    parser.add_argument(
+        "--token", required=True,
+        help="Secret token for request authentication",
+    )
+    args = parser.parse_args()
+
+    global _token
+    _token = args.token
+
+    host, port = args.bind.rsplit(":", 1)
+    bottle.run(app, server="cheroot", host=host, port=int(port))
+
+
+if __name__ == "__main__":
+    main()

snapshot_kernel-0.1.0/snapshot_kernel.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: snapshot-kernel
+Version: 0.1.0
+Summary: A snapshotting Python kernel with REST API
+Author-email: Luca de Alfaro <dealfaro@acm.org>
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: bottle
+Requires-Dist: cheroot
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file

snapshot_kernel-0.1.0/snapshot_kernel.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+pyproject.toml
+snapshot_kernel/__init__.py
+snapshot_kernel/kernel.py
+snapshot_kernel/main.py
+snapshot_kernel.egg-info/PKG-INFO
+snapshot_kernel.egg-info/SOURCES.txt
+snapshot_kernel.egg-info/dependency_links.txt
+snapshot_kernel.egg-info/requires.txt
+snapshot_kernel.egg-info/top_level.txt
+tests/test_api.py
+tests/test_kernel.py

snapshot_kernel-0.1.0/snapshot_kernel.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

snapshot_kernel-0.1.0/snapshot_kernel.egg-info/requires.txt

@@ -0,0 +1,5 @@
+bottle
+cheroot
+
+[test]
+pytest

snapshot_kernel-0.1.0/snapshot_kernel.egg-info/top_level.txt

@@ -0,0 +1 @@
+snapshot_kernel

snapshot_kernel-0.1.0/tests/test_api.py

@@ -0,0 +1,229 @@
+"""Integration tests for the Bottle REST API — starts a real Cheroot server."""
+
+import json
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+
+import pytest
+
+import bottle
+from snapshot_kernel import main as main_module
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+TOKEN = "test123"
+
+
+def _free_port():
+    """Find an available TCP port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _wait_for_port(port, timeout=5):
+    """Block until the server is accepting connections."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.1):
+                return
+        except OSError:
+            time.sleep(0.05)
+    raise RuntimeError(f"Server never started on port {port}")
+
+
+def _request(port, method, path, body=None, token=TOKEN):
+    """Send an HTTP request and return (status_code, parsed_json_or_None)."""
+    url = f"http://127.0.0.1:{port}{path}"
+    if token is not None:
+        url += f"?token={token}"
+
+    data = None
+    if body is not None:
+        data = json.dumps(body).encode()
+
+    req = urllib.request.Request(url, data=data, method=method)
+    if data is not None:
+        req.add_header("Content-Type", "application/json")
+
+    try:
+        with urllib.request.urlopen(req) as resp:
+            raw = resp.read()
+            try:
+                return resp.status, json.loads(raw)
+            except (json.JSONDecodeError, ValueError):
+                return resp.status, None
+    except urllib.error.HTTPError as exc:
+        raw = exc.read()
+        try:
+            return exc.code, json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            return exc.code, None
+
+
+# ------------------------------------------------------------------
+# Fixtures
+# ------------------------------------------------------------------
+
+@pytest.fixture(scope="module")
+def server():
+    """Start the Cheroot-backed Bottle server once for the whole module."""
+    port = _free_port()
+    main_module._token = TOKEN
+
+    def run():
+        bottle.run(main_module.app, server="cheroot",
+                    host="127.0.0.1", port=port, quiet=True)
+
+    t = threading.Thread(target=run, daemon=True)
+    t.start()
+    _wait_for_port(port)
+    return port
+
+
+@pytest.fixture(autouse=True)
+def _reset_kernel(server):
+    """Reset the kernel before every test so tests are independent."""
+    _request(server, "POST", "/reset")
+
+
+# ------------------------------------------------------------------
+# Tests
+# ------------------------------------------------------------------
+
+def test_list_states(server):
+    """GET /states returns only 'initial' after reset."""
+    status, body = _request(server, "GET", "/states")
+    assert status == 200
+    assert body["states"] == ["initial"]
+
+
+def test_execute_and_retrieve(server):
+    """POST /execute creates a state retrievable via GET /states/<name>."""
+    status, body = _request(server, "POST", "/execute", {
+        "code": "x = 42",
+        "exec_id": "e1",
+        "state_name": "initial",
+        "new_state_name": "s1",
+    })
+    assert status == 200
+    assert body["state_name"] == "s1"
+    assert body["error"] is None
+
+    status, state = _request(server, "GET", "/states/s1")
+    assert status == 200
+    assert state["variables"]["x"]["repr"] == "42"
+
+
+def test_chained_execution(server):
+    """Two sequential executions where the second reads the first's variable."""
+    _request(server, "POST", "/execute", {
+        "code": "x = 10",
+        "exec_id": "e1",
+        "state_name": "initial",
+        "new_state_name": "s1",
+    })
+    status, body = _request(server, "POST", "/execute", {
+        "code": "x + 5",
+        "exec_id": "e2",
+        "state_name": "s1",
+    })
+    assert status == 200
+    expr_items = [o for o in body["output"]
+                  if o["output_type"] == "execute_result"]
+    assert expr_items[0]["data"]["text/plain"] == "15"
+
+
+def test_delete_state(server):
+    """DELETE /states/<name> removes the state."""
+    _request(server, "POST", "/execute", {
+        "code": "1",
+        "exec_id": "e1",
+        "state_name": "initial",
+        "new_state_name": "tmp",
+    })
+    status, _ = _request(server, "DELETE", "/states/tmp")
+    assert status == 200
+
+    status, _ = _request(server, "GET", "/states/tmp")
+    assert status == 404
+
+
+def test_reset(server):
+    """POST /reset removes all derived states."""
+    _request(server, "POST", "/execute", {
+        "code": "1",
+        "exec_id": "e1",
+        "state_name": "initial",
+        "new_state_name": "s1",
+    })
+    _request(server, "POST", "/reset")
+
+    status, body = _request(server, "GET", "/states")
+    assert status == 200
+    assert body["states"] == ["initial"]
+
+
+def test_auth_wrong_token(server):
+    """A request with the wrong token gets 401."""
+    status, _ = _request(server, "GET", "/states", token="wrong")
+    assert status == 401
+
+
+def test_auth_missing_token(server):
+    """A request with no token gets 401."""
+    status, _ = _request(server, "GET", "/states", token=None)
+    assert status == 401
+
+
+def test_state_not_found(server):
+    """GET /states/<name> returns 404 for unknown names."""
+    status, _ = _request(server, "GET", "/states/nope")
+    assert status == 404
+
+
+def test_execute_error(server):
+    """POST /execute with bad code returns an error payload."""
+    status, body = _request(server, "POST", "/execute", {
+        "code": "1/0",
+        "exec_id": "e1",
+        "state_name": "initial",
+    })
+    assert status == 200
+    assert body["error"] is not None
+    assert body["error"]["ename"] == "ZeroDivisionError"
+    assert body["state_name"] is None
+
+
+def test_interrupt(server):
+    """POST /interrupt stops a long-running execution."""
+    result_holder = {}
+    code = "import time\nfor _ in range(200):\n    time.sleep(0.1)"
+
+    def run_long():
+        _, body = _request(server, "POST", "/execute", {
+            "code": code,
+            "exec_id": "long_run",
+            "state_name": "initial",
+        })
+        result_holder["body"] = body
+
+    t = threading.Thread(target=run_long)
+    t.start()
+
+    # Give the execution a moment to enter the loop.
+    time.sleep(1.0)
+    _request(server, "POST", "/interrupt", {"exec_id": "long_run"})
+    t.join(timeout=5)
+
+    body = result_holder.get("body")
+    assert body is not None, "Execution request did not finish"
+    assert body["error"] is not None
+    assert body["error"]["ename"] == "KeyboardInterrupt"

snapshot_kernel-0.1.0/tests/test_kernel.py

@@ -0,0 +1,398 @@
+"""Unit tests for SnapshotKernel — exercises the kernel class directly."""
+
+import base64
+import threading
+import time
+
+import pytest
+
+from snapshot_kernel.kernel import SnapshotKernel
+
+
+@pytest.fixture()
+def kernel():
+    """Provide a fresh kernel for every test."""
+    k = SnapshotKernel()
+    k.reset()
+    return k
+
+
+# ------------------------------------------------------------------
+# Basic state management
+# ------------------------------------------------------------------
+
+def test_initial_state(kernel):
+    """After init, only 'initial' exists with no user variables."""
+    assert kernel.list_states() == ["initial"]
+    state = kernel.get_state("initial")
+    assert state is not None
+    assert state["variables"] == {}
+
+
+# ------------------------------------------------------------------
+# Execution: output capture
+# ------------------------------------------------------------------
+
+def test_execute_print(kernel):
+    """print() output is captured as stream/stdout."""
+    result = kernel.execute("x = 42\nprint(x)", "e1", "initial")
+    assert result["error"] is None
+    assert result["state_name"] is not None
+
+    stdout_items = [o for o in result["output"]
+                    if o["output_type"] == "stream" and o["name"] == "stdout"]
+    assert len(stdout_items) == 1
+    assert "42\n" == stdout_items[0]["text"]
+
+
+def test_execute_last_expression(kernel):
+    """A trailing expression produces an execute_result."""
+    result = kernel.execute("1 + 2", "e1", "initial")
+    assert result["error"] is None
+
+    expr_items = [o for o in result["output"]
+                  if o["output_type"] == "execute_result"]
+    assert len(expr_items) == 1
+    assert expr_items[0]["data"]["text/plain"] == "3"
+
+
+def test_execute_named_state(kernel):
+    """Providing new_state_name stores under that exact name."""
+    result = kernel.execute("x = 1", "e1", "initial", new_state_name="my_state")
+    assert result["state_name"] == "my_state"
+    assert "my_state" in kernel.list_states()
+
+
+def test_chained_execution(kernel):
+    """Executing from a derived state sees variables set earlier."""
+    r1 = kernel.execute("x = 42", "e1", "initial")
+    r2 = kernel.execute("x + 1", "e2", r1["state_name"])
+    assert r2["error"] is None
+
+    expr_items = [o for o in r2["output"]
+                  if o["output_type"] == "execute_result"]
+    assert expr_items[0]["data"]["text/plain"] == "43"
+
+
+def test_import_module(kernel):
+    """Imports are available and persisted in the state."""
+    result = kernel.execute("import math\nmath.sqrt(144)", "e1", "initial")
+    assert result["error"] is None
+
+    expr_items = [o for o in result["output"]
+                  if o["output_type"] == "execute_result"]
+    assert expr_items[0]["data"]["text/plain"] == "12.0"
+
+    state = kernel.get_state(result["state_name"])
+    assert "math" in state["variables"]
+    assert state["variables"]["math"]["type"] == "module"
+
+
+def test_stderr_capture(kernel):
+    """sys.stderr.write() output is captured as stream/stderr."""
+    result = kernel.execute("import sys; sys.stderr.write('err')", "e1", "initial")
+
+    stderr_items = [o for o in result["output"]
+                    if o["output_type"] == "stream" and o["name"] == "stderr"]
+    assert len(stderr_items) == 1
+    assert stderr_items[0]["text"] == "err"
+
+
+# ------------------------------------------------------------------
+# Error handling
+# ------------------------------------------------------------------
+
+def test_execute_error(kernel):
+    """A runtime error is reported; no new state is created."""
+    result = kernel.execute("1/0", "e1", "initial")
+    assert result["error"] is not None
+    assert result["error"]["ename"] == "ZeroDivisionError"
+    assert result["state_name"] is None
+
+
+def test_execute_error_no_state_stored(kernel):
+    """After a failed execution the state list has not grown."""
+    before = set(kernel.list_states())
+    kernel.execute("1/0", "e1", "initial")
+    after = set(kernel.list_states())
+    assert before == after
+
+
+def test_state_not_found(kernel):
+    """Executing against a non-existent state returns a StateNotFound error."""
+    result = kernel.execute("1", "e1", "no_such_state")
+    assert result["error"]["ename"] == "StateNotFound"
+    assert result["state_name"] is None
+
+
+# ------------------------------------------------------------------
+# State retrieval & deletion
+# ------------------------------------------------------------------
+
+def test_get_state_details(kernel):
+    """get_state returns variable types, reprs, and a timestamp."""
+    r = kernel.execute("x = 42", "e1", "initial")
+    state = kernel.get_state(r["state_name"])
+    assert state is not None
+    assert "x" in state["variables"]
+    assert state["variables"]["x"]["type"] == "int"
+    assert state["variables"]["x"]["repr"] == "42"
+    assert "timestamp" in state
+
+
+def test_get_state_nonexistent(kernel):
+    """get_state returns None for unknown names."""
+    assert kernel.get_state("nope") is None
+
+
+def test_delete_state(kernel):
+    """A deleted state is removed from list_states."""
+    r = kernel.execute("x = 1", "e1", "initial", new_state_name="tmp")
+    assert "tmp" in kernel.list_states()
+    assert kernel.delete_state("tmp") is True
+    assert "tmp" not in kernel.list_states()
+
+
+def test_delete_nonexistent(kernel):
+    """Deleting an unknown state returns False."""
+    assert kernel.delete_state("nope") is False
+
+
+def test_reset(kernel):
+    """reset() removes all states except a fresh 'initial'."""
+    kernel.execute("x = 1", "e1", "initial", new_state_name="a")
+    kernel.execute("x = 2", "e2", "initial", new_state_name="b")
+    kernel.reset()
+    assert kernel.list_states() == ["initial"]
+    assert kernel.get_state("initial")["variables"] == {}
+
+
+# ------------------------------------------------------------------
+# State isolation
+# ------------------------------------------------------------------
+
+def test_state_isolation(kernel):
+    """Forking from the same state produces independent snapshots."""
+    kernel.execute("x = 1", "e1", "initial", new_state_name="a")
+    kernel.execute("x = 2", "e2", "initial", new_state_name="b")
+
+    a = kernel.get_state("a")
+    b = kernel.get_state("b")
+    initial = kernel.get_state("initial")
+
+    assert a["variables"]["x"]["repr"] == "1"
+    assert b["variables"]["x"]["repr"] == "2"
+    assert "x" not in initial["variables"]
+
+
+# ------------------------------------------------------------------
+# Interrupt
+# ------------------------------------------------------------------
+
+def test_interrupt(kernel):
+    """Interrupting a long-running execution raises KeyboardInterrupt."""
+    result_holder = {}
+    code = "import time\nfor _ in range(200):\n    time.sleep(0.1)"
+
+    def run():
+        result_holder["result"] = kernel.execute(code, "long", "initial")
+
+    t = threading.Thread(target=run)
+    t.start()
+
+    # Give the execution a moment to start the loop.
+    time.sleep(0.5)
+    kernel.interrupt("long")
+    t.join(timeout=5)
+
+    result = result_holder.get("result")
+    assert result is not None, "Execution thread did not finish"
+    assert result["error"] is not None
+    assert result["error"]["ename"] == "KeyboardInterrupt"
+    assert result["state_name"] is None
+
+
+# ------------------------------------------------------------------
+# Rich output capture
+# ------------------------------------------------------------------
+
+def test_rich_repr_html(kernel):
+    """An object with _repr_html_() produces text/html in execute_result."""
+    code = (
+        "class RichObj:\n"
+        "    def _repr_html_(self):\n"
+        "        return '<b>hello</b>'\n"
+        "    def __repr__(self):\n"
+        "        return 'RichObj()'\n"
+        "RichObj()"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    expr_items = [o for o in result["output"] if o["output_type"] == "execute_result"]
+    assert len(expr_items) == 1
+    assert expr_items[0]["data"]["text/html"] == "<b>hello</b>"
+    assert expr_items[0]["data"]["text/plain"] == "RichObj()"
+
+
+def test_rich_repr_png(kernel):
+    """An object with _repr_png_() returns base64-encoded image/png."""
+    code = (
+        "import base64\n"
+        "class PngObj:\n"
+        "    def _repr_png_(self):\n"
+        "        return b'\\x89PNG_fake'\n"
+        "    def __repr__(self):\n"
+        "        return 'PngObj()'\n"
+        "PngObj()"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    expr_items = [o for o in result["output"] if o["output_type"] == "execute_result"]
+    assert len(expr_items) == 1
+    png_data = expr_items[0]["data"]["image/png"]
+    # Verify it is valid base64 that decodes to our bytes.
+    assert base64.b64decode(png_data) == b"\x89PNG_fake"
+
+
+def test_repr_html_returns_none(kernel):
+    """If _repr_html_() returns None, text/html should not appear in data."""
+    code = (
+        "class NoneHtml:\n"
+        "    def _repr_html_(self):\n"
+        "        return None\n"
+        "    def __repr__(self):\n"
+        "        return 'NoneHtml()'\n"
+        "NoneHtml()"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    expr_items = [o for o in result["output"] if o["output_type"] == "execute_result"]
+    assert len(expr_items) == 1
+    assert "text/html" not in expr_items[0]["data"]
+    assert expr_items[0]["data"]["text/plain"] == "NoneHtml()"
+
+
+def test_repr_mimebundle(kernel):
+    """_repr_mimebundle_() returning a dict populates data correctly."""
+    code = (
+        "class BundleObj:\n"
+        "    def _repr_mimebundle_(self):\n"
+        "        return {'text/html': '<i>bundle</i>', 'text/plain': 'bundle'}\n"
+        "    def __repr__(self):\n"
+        "        return 'BundleObj()'\n"
+        "BundleObj()"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    expr_items = [o for o in result["output"] if o["output_type"] == "execute_result"]
+    assert len(expr_items) == 1
+    assert expr_items[0]["data"]["text/html"] == "<i>bundle</i>"
+
+
+def test_repr_mimebundle_tuple(kernel):
+    """_repr_mimebundle_() returning (data, metadata) tuple."""
+    code = (
+        "class TupleBundle:\n"
+        "    def _repr_mimebundle_(self):\n"
+        "        return ({'text/html': '<em>t</em>'}, {'text/html': {'isolated': True}})\n"
+        "    def __repr__(self):\n"
+        "        return 'TupleBundle()'\n"
+        "TupleBundle()"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    expr_items = [o for o in result["output"] if o["output_type"] == "execute_result"]
+    assert len(expr_items) == 1
+    assert expr_items[0]["data"]["text/html"] == "<em>t</em>"
+    assert expr_items[0]["metadata"]["text/html"] == {"isolated": True}
+
+
+def test_display_function(kernel):
+    """Calling display() inside code produces display_data output."""
+    code = (
+        "class Html:\n"
+        "    def _repr_html_(self):\n"
+        "        return '<p>hi</p>'\n"
+        "    def __repr__(self):\n"
+        "        return 'Html()'\n"
+        "display(Html())"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    display_items = [o for o in result["output"] if o["output_type"] == "display_data"]
+    assert len(display_items) == 1
+    assert display_items[0]["data"]["text/html"] == "<p>hi</p>"
+    assert display_items[0]["data"]["text/plain"] == "Html()"
+
+
+def test_display_multiple_calls(kernel):
+    """Multiple display() calls produce multiple display_data entries."""
+    code = "display('first')\ndisplay('second')"
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    display_items = [o for o in result["output"] if o["output_type"] == "display_data"]
+    assert len(display_items) == 2
+    assert display_items[0]["data"]["text/plain"] == "'first'"
+    assert display_items[1]["data"]["text/plain"] == "'second'"
+
+
+def test_display_multiple_args(kernel):
+    """display('a', 'b') produces two display_data entries."""
+    code = "display('a', 'b')"
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    display_items = [o for o in result["output"] if o["output_type"] == "display_data"]
+    assert len(display_items) == 2
+    assert display_items[0]["data"]["text/plain"] == "'a'"
+    assert display_items[1]["data"]["text/plain"] == "'b'"
+
+
+def test_display_not_in_state(kernel):
+    """The injected display function must not persist in the saved state."""
+    result = kernel.execute("x = 1", "e1", "initial")
+    assert result["error"] is None
+    state = kernel.get_state(result["state_name"])
+    assert "display" not in state["variables"]
+
+
+def test_matplotlib_figure_capture(kernel):
+    """A matplotlib figure is captured as display_data with image/png."""
+    pytest.importorskip("matplotlib")
+    code = (
+        "import matplotlib\n"
+        "matplotlib.use('Agg')\n"
+        "import matplotlib.pyplot as plt\n"
+        "fig, ax = plt.subplots()\n"
+        "ax.plot([1, 2, 3])\n"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    display_items = [o for o in result["output"] if o["output_type"] == "display_data"]
+    assert len(display_items) >= 1
+    png_item = display_items[0]
+    assert "image/png" in png_item["data"]
+    # Verify it's valid base64.
+    raw = base64.b64decode(png_item["data"]["image/png"])
+    assert raw[:4] == b"\x89PNG"
+
+
+def test_matplotlib_show_capture(kernel):
+    """plt.show() captures the current figure; a second figure is captured at end."""
+    pytest.importorskip("matplotlib")
+    code = (
+        "import matplotlib\n"
+        "matplotlib.use('Agg')\n"
+        "import matplotlib.pyplot as plt\n"
+        "plt.figure()\n"
+        "plt.plot([1, 2])\n"
+        "plt.show()\n"
+        "plt.figure()\n"
+        "plt.plot([3, 4])\n"
+    )
+    result = kernel.execute(code, "e1", "initial")
+    assert result["error"] is None
+    display_items = [o for o in result["output"] if o["output_type"] == "display_data"]
+    # First figure from plt.show(), second from end-of-cell capture.
+    assert len(display_items) >= 2
+    for item in display_items:
+        assert "image/png" in item["data"]