beatrina 0.8.6

package/engines/python/debugger.py

@@ -0,0 +1,346 @@
+"""debugger.py — breakpoints and stepping for a Python chunk, INSIDE the kernel.
+
+Shipped into the ipykernel as SOURCE by `bootstrap.py` (the way `dataview.py`
+is), because the kernel may be any Python the user chose and Beatrix's engine
+package need not be importable there. It is the Python half of the contract
+`spike/worker.R`'s browser() debugger defines (docs/wp/wp8b-python-debugger.md):
+
+    breakpoints   addressed by the chunk's STABLE srcname, "chunk:<stableId>",
+                  and a 1-based line inside that chunk's source
+    a pause       one `debug` frame: {event: "paused", file, line, reason,
+                  stack: [{call, vars, file, line}] innermost LAST, locals}
+    the commands  continue · over · into · out · where · abort · eval <expr>
+
+WHY A TRACER OF OUR OWN AND NOT DEBUGPY, OR BDB. Measured 2026-09-14 against
+ipykernel 7.3.0 / debugpy 1.8.21 / Python 3.14.4 (the record has the numbers):
+
+  * debugpy over ipykernel's control channel stops at a breakpoint in 0.19 s,
+    but a kernel interrupt sent while it is stopped did not end the run in
+    8 s — Stop, the one control the notebook promises works at every moment,
+    would be a lie exactly while paused. Its breakpoints also address a temp
+    file named by a HASH OF THE CELL'S TEXT, so the page's stable chunk
+    identity would have to be re-derived on every edit.
+  * `bdb` works, but its dispatch internals changed in 3.12, 3.13 and 3.14
+    (`disable_current_event`, a `monitoring` backend, `cmdframe`), and the
+    user's interpreter is any Python 3. A subclass that overrides
+    `break_here` inherits three versions of stop logic to be correct against.
+
+So: `sys.settrace` with a stop rule this file owns, a pause that is an ordinary
+`input()` — which ipykernel turns into an `input_request` the worker already
+drains, and which a kernel interrupt ends with KeyboardInterrupt (measured) —
+and a prompt that carries its state as JSON behind a marker no user prompt
+would begin with.
+
+THE PERFORMANCE RULE. Tracing is installed only while at least one breakpoint
+exists or a step is pending, and only for the cell being run; a notebook with
+no breakpoints runs with no trace function at all.
+"""
+
+import json as _json
+import sys as _sys
+
+#: The prompt marker. ESC bytes: nothing a person types into `input()` starts
+#: with it, and the worker strips it before anything reaches the page.
+PROMPT = "\x1bcarmar-debug\x1b"
+
+MAX_VARS = 40
+MAX_CALL = 300
+MAX_VALUE = 60
+HIDDEN = {"In", "Out", "get_ipython", "exit", "quit", "open"}
+
+
+class CarmarDebugAbort(BaseException):
+    """The debugger's Stop. BASE exception, not Exception: a user's
+    `except Exception:` around the paused line must not swallow it and carry
+    on, which is the promise R keeps with its `carmar_abort_cell` restart."""
+
+
+class _State:
+    def __init__(self):
+        self.breaks = {}          # srcname -> set of 1-based lines
+        self.next_name = None     # the srcname the NEXT compiled cell gets
+        self.mode = None          # None | "step" | "next" | "out" | "file"
+        self.target = None        # the frame a next/out is relative to
+        self.target_file = None   # "file": stop at the next line of this chunk
+        self.paused = False       # never re-enter a pause from inside one
+        self.installed = False
+
+
+S = _State()
+
+
+def is_user_file(filename):
+    """Code the notebook wrote: a chunk, or a cell with no chunk identity."""
+    return isinstance(filename, str) and (
+        filename.startswith("chunk:") or filename.startswith("<ipython-input"))
+
+
+# ── what a frame looks like on the wire ──────────────────────────────────────
+
+def _shape(v):
+    """R's frame_vars `value` column, in Python: a table's dimensions, the word
+    function, a short scalar, or a length — never the object's whole repr."""
+    try:
+        if v is None or isinstance(v, (bool, int, float, complex, str, bytes)):
+            t = repr(v)
+            return t if len(t) <= MAX_VALUE else t[:MAX_VALUE - 3] + "..."
+        shape = getattr(v, "shape", None)
+        if isinstance(shape, tuple) and len(shape) == 2:
+            return "%d x %d" % (int(shape[0]), int(shape[1]))
+        if callable(v):
+            return "function"
+        if hasattr(v, "__len__"):
+            return "length %d" % len(v)
+        return type(v).__name__
+    except Exception:
+        return "?"
+
+
+def _vars(mapping, module_level):
+    import types
+    rows = []
+    try:
+        names = sorted(k for k in mapping.keys() if isinstance(k, str))
+    except Exception:
+        return rows
+    for name in names:
+        if module_level and (name.startswith("_") or name in HIDDEN):
+            continue
+        try:
+            v = mapping[name]
+        except Exception:
+            continue
+        if module_level and isinstance(v, types.ModuleType):
+            continue
+        rows.append({"name": name, "class": type(v).__name__, "value": _shape(v)})
+        if len(rows) >= MAX_VARS:
+            break
+    return rows
+
+
+def _call_text(frame):
+    code = frame.f_code
+    name = getattr(code, "co_qualname", code.co_name)
+    args = []
+    for arg in code.co_varnames[:code.co_argcount + code.co_kwonlyargcount]:
+        if arg in frame.f_locals:
+            args.append("%s = %s" % (arg, _shape(frame.f_locals[arg])))
+    text = "%s(%s)" % (name, ", ".join(args))
+    return text if len(text) <= MAX_CALL else text[:MAX_CALL - 3] + "..."
+
+
+def _stack(frame):
+    """User frames, innermost LAST. A chunk's own top level is not a frame in
+    R's stack either (a top-level breakpoint shows "(top level)"), so module
+    frames are the position, not a row."""
+    rows = []
+    f = frame
+    while f is not None:
+        code = f.f_code
+        if is_user_file(code.co_filename) and code.co_name != "<module>":
+            rows.append({"call": _call_text(f), "vars": _vars(f.f_locals, False),
+                         "file": code.co_filename if code.co_filename.startswith("chunk:") else None,
+                         "line": f.f_lineno})
+        f = f.f_back
+    rows.reverse()
+    return rows[-40:]
+
+
+def _locals(frame):
+    module = frame.f_code.co_name == "<module>"
+    return _vars(frame.f_globals if module else frame.f_locals, module)
+
+
+def _position(frame):
+    name = frame.f_code.co_filename
+    return {"file": name if name.startswith("chunk:") else None, "line": frame.f_lineno}
+
+
+# ── the stop rule ────────────────────────────────────────────────────────────
+
+def _on_stack(target, frame):
+    f = frame
+    while f is not None:
+        if f is target:
+            return True
+        f = f.f_back
+    return False
+
+
+def _should_stop(frame):
+    name = frame.f_code.co_filename
+    lines = S.breaks.get(name)
+    if lines and frame.f_lineno in lines:
+        return "breakpoint"
+    if S.mode == "step":
+        return "step"
+    if S.mode == "next":
+        if frame is S.target or not _on_stack(S.target, frame):
+            return "step"
+    if S.mode == "out":
+        if not _on_stack(S.target, frame):
+            return "step"
+    if S.mode == "file" and name == S.target_file:
+        return "step"
+    return None
+
+
+def _local(frame, event, arg):
+    if S.paused:
+        return _local
+    if event == "line":
+        reason = _should_stop(frame)
+        if reason:
+            _pause(frame, reason)
+    elif event == "return" and S.mode in ("next", "out") and frame is S.target:
+        caller = frame.f_back
+        if caller is not None and is_user_file(caller.f_code.co_filename):
+            # Stop at the caller's next line: make sure the caller is traced.
+            S.target = caller
+            S.mode = "next"
+            caller.f_trace = _local
+        else:
+            # A chunk's top-level statement finished and control went back to
+            # IPython, which runs the NEXT statement as its own code object:
+            # "execute next line" means the chunk's next line, not the cell's end.
+            S.mode = "file"
+            S.target_file = frame.f_code.co_filename
+            S.target = None
+    return _local
+
+
+def _global(frame, event, arg):
+    if S.paused or event != "call":
+        return None
+    name = frame.f_code.co_filename
+    if not is_user_file(name):
+        return None
+    if name in S.breaks or S.mode is not None:
+        return _local
+    return None
+
+
+def _install():
+    if not S.installed and (S.breaks or S.mode is not None):
+        _sys.settrace(_global)
+        S.installed = True
+
+
+def _uninstall():
+    if S.installed:
+        _sys.settrace(None)
+        S.installed = False
+    S.mode = None
+    S.target = None
+    S.target_file = None
+    S.paused = False
+
+
+# ── a pause ──────────────────────────────────────────────────────────────────
+
+def _eval_in(frame, expr):
+    """Evaluate one console line IN THE PAUSED FRAME, the way R's Browse
+    prompt does: an expression prints its value, a statement runs."""
+    import traceback
+    glb = frame.f_globals
+    loc = frame.f_locals
+    try:
+        try:
+            code = compile(expr, "<debug>", "eval")
+        except SyntaxError:
+            exec(compile(expr, "<debug>", "exec"), glb, loc)
+            return
+        value = eval(code, glb, loc)
+        if value is not None:
+            print(repr(value))
+    except (KeyboardInterrupt, CarmarDebugAbort):
+        raise
+    except BaseException:
+        text = traceback.format_exception_only(*_sys.exc_info()[:2])
+        _sys.stderr.write("".join(text))
+
+
+def _pause(frame, reason):
+    """Emit the pause, then read commands until one resumes execution.
+
+    `input()` is the transport both ways: its prompt carries the frame (the
+    worker turns it into `debug`), its answer carries the command and the
+    current breakpoints (the worker writes them). A Stop pressed while paused
+    arrives as KeyboardInterrupt out of this `input()` and unwinds the chunk.
+    """
+    S.paused = True
+    try:
+        payload = {"event": "paused", "reason": reason, **_position(frame),
+                   "stack": _stack(frame), "locals": _locals(frame)}
+        while True:
+            answer = input(PROMPT + _json.dumps(payload, default=str, separators=(",", ":")))
+            payload = {"event": "prompt"}
+            try:
+                cmd = _json.loads(answer)
+            except Exception:
+                cmd = {"action": "eval", "expr": answer}
+            if isinstance(cmd.get("breaks"), dict):
+                S.breaks = {k: set(v) for k, v in cmd["breaks"].items() if v}
+            action = cmd.get("action")
+            if action == "continue":
+                S.mode, S.target = None, None
+                return
+            if action == "over":
+                S.mode, S.target = "next", frame
+                return
+            if action == "into":
+                S.mode, S.target = "step", None
+                return
+            if action == "out":
+                S.mode, S.target = "out", frame
+                return
+            if action == "abort":
+                raise CarmarDebugAbort("Stopped from the debugger")
+            if action == "where":
+                payload = {"event": "where", **_position(frame),
+                           "stack": _stack(frame), "locals": _locals(frame)}
+                continue
+            if action == "eval" and isinstance(cmd.get("expr"), str):
+                _eval_in(frame, cmd["expr"])
+    finally:
+        S.paused = False
+
+
+# ── the worker's entry points ────────────────────────────────────────────────
+
+def prepare(spec_json):
+    """Called by the worker immediately before a chunk runs: the chunk's
+    srcname for the next compile, and every breakpoint the page has set."""
+    spec = _json.loads(spec_json)
+    name = spec.get("srcname")
+    S.next_name = name if isinstance(name, str) and name else None
+    breaks = spec.get("breaks")
+    if isinstance(breaks, dict):
+        S.breaks = {k: set(int(x) for x in v) for k, v in breaks.items()
+                    if isinstance(k, str) and isinstance(v, list) and v}
+
+
+def install(ip):
+    """Hook the kernel: name the next cell after its chunk, and trace a cell
+    only while a breakpoint or a step exists."""
+    compiler = ip.compile
+    original = compiler.get_code_name
+
+    def get_code_name(raw_code, transformed_code, number):
+        name = S.next_name
+        if name:
+            S.next_name = None
+            return name
+        return original(raw_code, transformed_code, number)
+
+    compiler.get_code_name = get_code_name
+
+    def pre(*a, **k):
+        S.mode, S.target, S.target_file = None, None, None
+        _install()
+
+    def post(*a, **k):
+        _uninstall()
+
+    ip.events.register("pre_run_cell", pre)
+    ip.events.register("post_run_cell", post)

package/engines/python/document_exec.py

@@ -0,0 +1,158 @@
+"""document_exec.py — the notebook exec envelope: setup chunks as a Ready snapshot.
+
+The page sends every chunk run with a `document` descriptor
+(`page/lib/document-execution.js`, `executionDocument()`), and refuses to run
+at all against a kernel that does not announce `document_exec_v1` on its ready
+frame. So carmapy must either implement what the envelope asks for or be a
+kernel no page can run a chunk on. This module is the implementation, ported
+from `spike/knitr-run.R`'s `run_document_cell()` — the DECISIONS, kept pure so
+they can be tested on plain dicts; the running is `serve.py`'s.
+
+What the R side does with the envelope, and what carmapy keeps:
+
+  * A document's `setup` chunk runs ONCE per (document, setup source) and is
+    then a "Ready snapshot": dependent chunks reuse it without re-running it.
+    A changed setup source, an explicit run of the setup chunk (`isSetup`), or
+    a previously failed setup re-runs it. KEPT — same rules, same messages.
+  * A setup that failed BLOCKS dependent chunks until it is fixed, re-run
+    explicitly, or retried (`retrySetup`). KEPT.
+  * The setup's own output is not shown (knitr `include = FALSE`); its
+    tracebacks are. KEPT — `serve.py` forwards a setup run's error frames only.
+  * knitr chunk options — `cache`, `fig.width`, `comment`, `warning`, … — are
+    applied to the chunk's evaluation. NOT KEPT, by decision: chunk options
+    are render-time for Python (`docs/python-plan.md` §8; knitr has no Python
+    equivalent and a session-side option cache was refused on the R side).
+    The done frame therefore reports `cacheHit: false` and
+    `effectiveOptions: null` — nothing was applied, so nothing is claimed.
+  * `optionExpressions` are R expressions evaluated at run time. NOT KEPT
+    (they would be evaluated as Python by a kernel that never promised to).
+
+The error sentences are R's, verbatim, because the page shows them to the
+user and its tests assert them.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+LABEL_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+#: The one feature this module lets the ready frame claim.
+FEATURE = "document_exec_v1"
+
+
+class DocumentExecError(Exception):
+    """The envelope cannot be run. The message is the user-facing sentence."""
+
+
+@dataclass(frozen=True)
+class Plan:
+    """What one exec envelope asks for, decided before anything runs.
+
+    doc_id         the document identity (`document.id`)
+    label          the chunk label (validated when the chunk itself will run)
+    setup_source   the setup chunk's source, or None when the document has none
+    setup_srcname  the setup chunk's `srcname`, for the `setup` frames
+    run_setup      run the setup chunk first (changed, explicit, or retrying)
+    run_chunk      run the chunk itself (False for an explicit setup-only run)
+    execution      the provenance stamp the page stores with the result
+    """
+    doc_id: str
+    label: str | None
+    setup_source: str | None
+    setup_srcname: str | None
+    run_setup: bool
+    run_chunk: bool
+    execution: dict = field(default_factory=dict)
+
+
+@dataclass
+class _Snapshot:
+    source: str          # the setup source this snapshot is FOR ("" for none)
+    status: str          # "ok" | "failed"
+
+
+class DocumentSetups:
+    """Per-document setup state for ONE evaluating session.
+
+    Port of `KNIT_DOCS` in knitr-run.R: keyed by document id, remembering
+    which setup source last ran and whether it succeeded. A fresh worker has
+    no Ready snapshots — `reset()` on every restart.
+    """
+
+    def __init__(self) -> None:
+        self._docs: dict[str, _Snapshot] = {}
+
+    def reset(self) -> None:
+        self._docs.clear()
+
+    def snapshot(self, doc_id: str) -> tuple[str, str] | None:
+        """`(setup_source, status)` for a document, or None (never ran)."""
+        snap = self._docs.get(doc_id)
+        return (snap.source, snap.status) if snap else None
+
+    def plan(self, source: str, document: object) -> Plan:
+        """Decide what an envelope asks for. Raises `DocumentExecError`.
+
+        Mirrors the validation and the setup rules of `run_document_cell()`
+        in the order R applies them, so the same bad envelope gets the same
+        sentence.
+        """
+        if not isinstance(document, dict) or not isinstance(document.get("id"), str) \
+                or not document["id"]:
+            raise DocumentExecError("A notebook run needs its document identity.")
+        doc_id = document["id"]
+        setup = document.get("setup")
+        if setup is not None and (not isinstance(setup, dict)
+                                  or not isinstance(setup.get("source"), str)):
+            raise DocumentExecError("Invalid setup chunk descriptor.")
+        is_setup = document.get("isSetup") is True
+        retry = document.get("retrySetup") is True
+        selection = document.get("selection") is True
+        setup_key = setup["source"] if setup is not None else ""
+        previous = self._docs.get(doc_id)
+        if previous is not None and previous.source == setup_key \
+                and previous.status == "failed" and not is_setup and not retry:
+            raise DocumentExecError("Setup previously failed. Fix it or explicitly run the "
+                                    "setup chunk before running dependent chunks.")
+        setup_changed = previous is None or previous.source != setup_key
+        run_setup = setup is not None and (
+            setup_changed or is_setup or previous.status == "failed")
+        label = None
+        if not is_setup:
+            label = document.get("label")
+            if not isinstance(label, str) or not LABEL_RE.match(label):
+                raise DocumentExecError("Use a unique chunk label containing letters, "
+                                        "numbers, dots, hyphens or underscores.")
+            options = document.get("options", {})
+            expressions = document.get("expressions", {})
+            if not isinstance(options, dict) or not isinstance(expressions, dict):
+                raise DocumentExecError("Invalid chunk options.")
+        execution = {
+            "source": setup["source"] if (is_setup and setup is not None) else source,
+            "setupSource": setup["source"] if setup is not None else "",
+            "optionsKey": document.get("optionsKey"),
+            "full": not selection,
+        }
+        return Plan(doc_id=doc_id, label=label, setup_source=setup_key if setup else None,
+                    setup_srcname=setup.get("srcname") if setup else None,
+                    run_setup=run_setup, run_chunk=not is_setup, execution=execution)
+
+    # ---- the ledger, written by serve.py as the run proceeds ---------------
+
+    def setup_started(self, doc_id: str) -> None:
+        """Invalidate BEFORE running: a failed partial setup must never leave
+        a previous Ready snapshot available to dependent chunks."""
+        self._docs.pop(doc_id, None)
+
+    def setup_ok(self, doc_id: str, setup_source: str) -> None:
+        self._docs[doc_id] = _Snapshot(source=setup_source, status="ok")
+
+    def setup_failed(self, doc_id: str, setup_source: str) -> None:
+        self._docs[doc_id] = _Snapshot(source=setup_source, status="failed")
+
+    def no_setup(self, doc_id: str) -> None:
+        """A document with no setup chunk: its snapshot is the empty source,
+        so a setup chunk added later counts as a CHANGE and runs."""
+        self._docs[doc_id] = _Snapshot(source="", status="ok")

package/engines/python/engine.json

@@ -0,0 +1,28 @@
+{
+  "name": "python",
+  "label": "Python",
+  "language": "python",
+  "fences": ["python", "py"],
+  "adapter": "host/engine-python.mjs",
+  "worker": "engines/python/worker.py",
+  "boot": "on-demand",
+  "runtime": {
+    "env": "CARMAR_PYTHON",
+    "ladder": [
+      "VIRTUAL_ENV",
+      "CONDA_PREFIX",
+      "PYENV",
+      "PATH",
+      "/opt/homebrew/bin/python3",
+      "/usr/local/bin/python3",
+      "/usr/bin/python3"
+    ],
+    "requires": ["ipykernel", "jupyter_client"]
+  },
+  "controls": {
+    "interrupt": "signal:SIGINT:group",
+    "console": "stdin:tagged-json:input_reply",
+    "commands": "stdin:tagged-json"
+  },
+  "note": "The engine process is worker.py; it evaluates nothing itself — an ipykernel one process further out does, and jupyter_client starts that kernel in its OWN session, which is why the host's group SIGINT reaches worker.py and worker.py forwards interrupt_request. R is spawned at boot; this engine starts the first time a {python} chunk runs."
+}

package/engines/python/handoff.py

@@ -0,0 +1,118 @@
+"""handoff.py — share() and use() for the Python engine.
+
+The explicit bridge between a Beatrix session's languages (engines/r/handoff.R,
+engines/js/worker.mjs): a value crosses only when a chunk names it. The format
+is one JSON file per name in CARMAR_HANDOFF_DIR:
+
+    {"format": "beatrix-columns-v1", "name": ..., "from": "python",
+     "columns": [...], "data": {"<column>": [values]}}
+
+Python's json writes a float with repr(), the shortest string that reads back
+as the same double, so numbers cross exactly. NaN, inf and None travel as null.
+
+Installed into the kernel's namespace by bootstrap.py as SOURCE (the kernel may
+be any Python the user chose), so it imports nothing that is not the standard
+library; pandas is used when it is there and never required.
+
+share(name, value) and share(value, name) are both accepted: R's natural order
+is share(df) with the name taken from the symbol, and a language that cannot
+see the symbol has to be told the name — whichever order the author reaches for.
+"""
+
+import json as _json
+import math as _math
+import os as _os
+import re as _re
+
+_NAME_RE = _re.compile(r"^[A-Za-z_][A-Za-z0-9_.]*$")
+
+
+def _handoff_path(name):
+    folder = _os.environ.get("CARMAR_HANDOFF_DIR", "")
+    if not folder or not _os.path.isdir(folder):
+        raise RuntimeError("share()/use() need the Beatrina host's hand-off directory; "
+                           "this Python was started without one.")
+    if not isinstance(name, str) or not _NAME_RE.match(name):
+        raise TypeError("A shared name is letters, digits, dots and underscores, "
+                        "starting with a letter or underscore.")
+    return _os.path.join(folder, name + ".json")
+
+
+def _plain(v):
+    if v is None:
+        return None
+    item = getattr(v, "item", None)          # numpy scalars
+    if callable(item) and not isinstance(v, (str, bytes)):
+        try:
+            v = item()
+        except Exception:
+            pass
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, float):
+        return v if _math.isfinite(v) else None
+    if isinstance(v, int):
+        return v
+    if isinstance(v, str):
+        return v
+    try:
+        if v != v:                            # pandas NA / NaT
+            return None
+    except Exception:
+        pass
+    iso = getattr(v, "isoformat", None)
+    return iso() if callable(iso) else str(v)
+
+
+def _columns(value):
+    to_dict = getattr(value, "to_dict", None)
+    if callable(to_dict) and hasattr(value, "columns"):
+        cols = [str(c) for c in value.columns]
+        return cols, {str(c): [_plain(x) for x in value[c].tolist()] for c in value.columns}
+    if isinstance(value, dict) and value and all(isinstance(v, (list, tuple)) for v in value.values()):
+        lengths = {len(v) for v in value.values()}
+        if len(lengths) != 1:
+            raise ValueError("share(): every column must have the same length.")
+        return [str(k) for k in value], {str(k): [_plain(x) for x in v] for k, v in value.items()}
+    if isinstance(value, (list, tuple)) and all(isinstance(r, dict) for r in value):
+        cols = []
+        for r in value:
+            for k in r:
+                if str(k) not in cols:
+                    cols.append(str(k))
+        return cols, {c: [_plain(r.get(c)) for r in value] for c in cols}
+    raise TypeError("share() takes a pandas DataFrame, a dict of equal-length columns, "
+                    "or a list of row dicts.")
+
+
+def share(a, b=None):
+    """Share a table with the other languages of this session. Returns None."""
+    name, value = (a, b) if isinstance(a, str) else (b, a)
+    path = _handoff_path(name)
+    cols, data = _columns(value)
+    tmp = "%s.%d.tmp" % (path, _os.getpid())
+    with open(tmp, "w", encoding="utf-8") as fh:
+        _json.dump({"format": "beatrix-columns-v1", "name": name, "from": "python",
+                    "columns": cols, "data": data}, fh, allow_nan=False)
+    _os.chmod(tmp, 0o600)
+    _os.replace(tmp, path)
+
+
+def use(name):
+    """A table another language shared: a pandas DataFrame when pandas is
+    installed, otherwise a list of row dicts."""
+    path = _handoff_path(name)
+    if not _os.path.exists(path):
+        raise LookupError('Nothing has been shared as "%s" in this session. Share it first '
+                          'with share("%s", ...) here or share(%s) in R.' % (name, name, name))
+    with open(path, "r", encoding="utf-8") as fh:
+        rec = _json.load(fh)
+    if rec.get("format") != "beatrix-columns-v1":
+        raise ValueError('"%s" is not a Beatrina hand-off table.' % name)
+    cols = rec["columns"]
+    try:
+        import pandas as _pd
+        return _pd.DataFrame({c: rec["data"][c] for c in cols}, columns=cols)
+    except ImportError:
+        n = len(rec["data"][cols[0]]) if cols else 0
+        return [{c: rec["data"][c][i] for c in cols} for i in range(n)]