From c4e9e1f26cbf5575a545e2e60ee8ce83ef2a2554 Mon Sep 17 00:00:00 2001
From: Tam Nguyen Duc <1218621+tamnd@users.noreply.github.com>
Date: Wed, 19 Aug 2026 03:14:04 +0700
Subject: [PATCH] a result a notebook can read

Jupyter asks an object for _repr_html_ before it falls back to repr, so
a result printed in a cell is a line saying how many rows it has. The
rows are already in memory and a table of them is a strictly better
answer, so this draws one, and draws nodes, edges and walks the same way
whether they turn up on their own or inside a cell.

The markup is a table and a stylesheet and no script, which means it
survives nbconvert, an exported HTML file and a notebook diff, and there
is nothing to install for it to work. Colours come from the notebook
through currentColor and opacity, because a light theme and a dark one
are both in the room and a guess about which would be wrong half the
time. A hundred rows is the cut, since a million rows of markup is a
notebook file nobody can open again, and the note underneath says how
many rows there really were. Two hundred characters is the cut on a
cell, so a column holding a document does not become a page holding one.
Values are escaped, because a string column holding a tag is a string
column and pasting one into the page unescaped would run a caller's
data as code in their notebook.

zudb.magic goes with it: %gql opens a connection and %%gql runs a
statement on it, with --conn to say which of several, --params to name a
dict, and --out to put the result in a variable instead of showing it. A
notebook that already called zudb.connect needs no %gql at all, since a
cell with one connection in the namespace finds it, and a cell with two
says which names it saw. The magic is a way in and not a layer: the
statement goes straight to execute and the engine's exception arrives as
the engine's exception.

IPython is a dev dependency and not a wheel dependency, and the tests
skip without it the way the pyarrow and pandas ones do. They run against
a real InteractiveShell with %load_ext rather than a mock, so what is
checked is what a notebook does.
---
 .github/workflows/ci.yml |   2 +-
 README.md                |  22 +++-
 pyproject.toml           |   5 +
 python/zudb/_zudb.pyi    |  12 +++
 python/zudb/magic.py     | 187 ++++++++++++++++++++++++++++++++++
 src/conn.rs              |  41 ++++++++
 src/html.rs              | 215 +++++++++++++++++++++++++++++++++++++++
 src/lib.rs               |   1 +
 src/value.rs             |  21 ++++
 tests/test_html.py       | 155 ++++++++++++++++++++++++++++
 tests/test_magic.py      | 198 +++++++++++++++++++++++++++++++++++
 11 files changed, 857 insertions(+), 2 deletions(-)
 create mode 100644 python/zudb/magic.py
 create mode 100644 src/html.rs
 create mode 100644 tests/test_html.py
 create mode 100644 tests/test_magic.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 973357a..3e96859 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -59,7 +59,7 @@ jobs:
       # griffe reads the stub and inspects the installed extension, so
       # the check runs against the wheel rather than against the
       # checkout it was built from.
-      - run: pip install pytest griffe
+      - run: pip install pytest griffe ipython
       - run: pytest
 
   # The shared corpus, which is the same 945 cases the engine runs
diff --git a/README.md b/README.md
index eab13c2..8a38d54 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,26 @@ result.record_batches()  # a reader, for a result larger than memory
 
 `Result` implements `__arrow_c_stream__`, so anything that reads the protocol reads a result directly and none of the four methods above is needed: `pyarrow.table(result)` and `polars.DataFrame(result)` both work. Batches are 65,536 rows. A column holds one type, which the values decide, and integers beside floats are the one mixture that widens rather than being refused. Nodes, rels and paths go across as structs. The copy runs with the GIL released, and on this machine 300,000 rows across three columns take 44 ms as Arrow against 67 ms as Python objects, and a single integer column takes 13.8 ms against 44.5 ms.
 
+## In a notebook
+
+A result in a cell draws itself as a table, because Jupyter asks an object for `_repr_html_` before it falls back to `repr` and a line saying how many rows there are is a strictly worse answer than the rows. Nodes, rels and paths draw themselves too, a path as the walk it is: `(person #0) -[knows]-> (person #1)`.
+
+```python
+%load_ext zudb.magic
+%gql social.zu1
+```
+
+```python
+%%gql
+MATCH (p:person) WHERE p.score > 40 RETURN p.name AS name, p.score AS score
+```
+
+The cell is one statement, it runs on the current connection, and the result is the value of the cell, so `_` is a `zudb.Result` and everything a result can do is still there. `%gql` is about which connection and `%%gql` is about the statement, and neither guesses the other's job. A notebook that already called `zudb.connect` needs no `%gql` at all: if exactly one connection is lying about the namespace `%%gql` uses it, and if there is more than one it names them and asks which. `%%gql --conn other --params args --out rows` says which connection, where the parameters are, and where to put the result instead of showing it, each of them naming a variable because a notebook has the values already.
+
+The markup is a table, a stylesheet and no script, so it survives `nbconvert`, an exported HTML file and a notebook diff, and there is nothing to install for any of it. Colours come from the notebook through `currentColor` and opacity, because a light theme and a dark one are both in the room. Values are escaped, since a string column holding `<script>` is a string column and a client that pasted one into the page would run a caller's data as code in their notebook. The first hundred rows are drawn and the note underneath says how many there were, and a value longer than two hundred characters is cut with a mark where it was cut, because a million rows of markup is a notebook file that will not open again.
+
+IPython is not a dependency. It is what a notebook already has, and nothing here imports it until `%load_ext` does.
+
 ## Stopping a statement
 
 A statement that is running can be stopped two ways, and neither of them closes the connection: the session, its plans and its warm readers are all there afterwards, which is the whole difference between stopping a statement and starting again.
@@ -183,7 +203,7 @@ The stub is checked against the module it describes in CI: griffe reads the stub
 
 ## What works today
 
-The list above is what this client is for. What it does so far is the core of it: `connect`, `execute` and `sql` with named parameters, results that iterate and fetch, values as Python objects both ways including dates, times, datetimes and durations, `Node`, `Rel` and `Path` as classes, `load` for building a graph with edges in it, an appender for growing one, transactions as a context manager that commits at the end of a block and rolls back when it raises, every condition as an exception class carrying its code, its position and its documentation link, results as Arrow columns and as pandas and polars frames, `register` for putting a frame under a name a statement can match on and reading it where it lies, stubs inside the wheel with a gate that keeps them true, the GIL released around every statement, every load and every copy out, `Ctrl-C` and `interrupt()` stopping a statement without touching the connection under it, and `zudb.aio` for the same calls awaited on an event loop. A DB-API 2.0 wrapper is next, and each one lands with the tests that say it works.
+The list above is what this client is for. What it does so far is the core of it: `connect`, `execute` and `sql` with named parameters, results that iterate and fetch, values as Python objects both ways including dates, times, datetimes and durations, `Node`, `Rel` and `Path` as classes, `load` for building a graph with edges in it, an appender for growing one, transactions as a context manager that commits at the end of a block and rolls back when it raises, every condition as an exception class carrying its code, its position and its documentation link, results as Arrow columns and as pandas and polars frames, `register` for putting a frame under a name a statement can match on and reading it where it lies, stubs inside the wheel with a gate that keeps them true, the GIL released around every statement, every load and every copy out, `Ctrl-C` and `interrupt()` stopping a statement without touching the connection under it, `zudb.aio` for the same calls awaited on an event loop, and results, nodes, rels and paths that draw themselves in a notebook with `%gql` and `%%gql` to run statements in one. A DB-API 2.0 wrapper is next, and each one lands with the tests that say it works.
 
 ## Wheels
 
diff --git a/pyproject.toml b/pyproject.toml
index 339323f..b561cc7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,6 +47,11 @@ dev = [
   # Reads the stub as text and the built extension by inspection, which
   # is what checks one against the other.
   "griffe>=2",
+  # For `%gql` and `%%gql`, which are tested against a real shell
+  # rather than against a stub of one. Not a dependency of the wheel:
+  # anyone with a notebook has IPython already, and nobody else needs
+  # it.
+  "ipython>=8",
   "pyarrow>=14",
   "pandas>=2.0",
   "polars>=1.3",
diff --git a/python/zudb/_zudb.pyi b/python/zudb/_zudb.pyi
index 2a8fff5..324cd75 100644
--- a/python/zudb/_zudb.pyi
+++ b/python/zudb/_zudb.pyi
@@ -197,6 +197,9 @@ class Result:
     def __arrow_c_stream__(self, requested_schema: object | None = None) -> Any:
         """The rows as an Arrow stream, for anything that speaks Arrow."""
 
+    def _repr_html_(self) -> str:
+        """The rows as an HTML table, which is what a notebook shows."""
+
     def __len__(self) -> int: ...
     def __iter__(self) -> Iterator[tuple[Value, ...]]: ...
     def __repr__(self) -> str: ...
@@ -213,6 +216,9 @@ class Node:
     def offset(self) -> int:
         """The row this node sits at in that table, counting from zero."""
 
+    def _repr_html_(self) -> str:
+        """The node as a notebook draws it, which is the pair that names it."""
+
     def __hash__(self) -> int: ...
     def __repr__(self) -> str: ...
 
@@ -237,6 +243,9 @@ class Rel:
         """Where the edge's properties sit, which is its place in
         the order the table was loaded in."""
 
+    def _repr_html_(self) -> str:
+        """The edge as a notebook draws it, with the rows it joins on either side."""
+
     def __hash__(self) -> int: ...
     def __repr__(self) -> str: ...
 
@@ -256,6 +265,9 @@ class Path:
     def rels(self) -> list[Rel]:
         """The edges of the walk, in the order it crosses them."""
 
+    def _repr_html_(self) -> str:
+        """The walk as a notebook draws it, nodes and arrows alternating."""
+
     def __len__(self) -> int: ...
     def __repr__(self) -> str: ...
 
diff --git a/python/zudb/magic.py b/python/zudb/magic.py
new file mode 100644
index 0000000..2d65074
--- /dev/null
+++ b/python/zudb/magic.py
@@ -0,0 +1,187 @@
+"""`%%gql` in a notebook.
+
+    %load_ext zudb.magic
+    %gql social.zu1
+
+    %%gql
+    MATCH (p:person) WHERE p.score > 40 RETURN p.name AS name, p.score AS score
+
+The cell is one statement, it runs on the current connection, and what
+comes back is a `zudb.Result`, which the notebook draws as a table
+because a result knows how to draw itself. It is the value of the cell
+as well, so `_` is the result and everything a result can do is still
+there.
+
+Two magics and no more. `%gql` is about which connection, `%%gql` is
+about the statement, and neither of them tries to guess the other's
+job: a line magic that took a path or a statement depending on what it
+looked like would guess wrong on the day somebody named a file
+`MATCH`.
+
+`%gql` with a path opens a connection and makes it the current one.
+`%gql` with nothing says which connection that is. `%gql --close` shuts
+it. A notebook that made its own connection does not need any of that:
+if exactly one `zudb.Connection` is lying about the namespace, `%%gql`
+uses it, and if there is more than one it says so and asks which,
+because picking one of them would be picking somebody's read-only
+connection half the time.
+
+The cell magic takes three options, all of them naming variables rather
+than holding values, since a notebook has the values already:
+
+    %%gql --conn other --params args --out rows
+    MATCH (p:person) WHERE p.uid = $uid RETURN p.name AS name
+
+`--conn` is the connection to run on, `--params` is a dict of
+parameters, and `--out` is where to put the result instead of showing
+it.
+"""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+from typing import Any
+
+from IPython.core.error import UsageError
+from IPython.core.magic import Magics, cell_magic, line_magic, magics_class
+
+from ._zudb import Connection, connect
+
+__all__ = ["ZuMagics", "load_ipython_extension"]
+
+
+@magics_class
+class ZuMagics(Magics):
+    """The two magics, and the connection `%gql` opened if it opened one."""
+
+    def __init__(self, shell: Any) -> None:
+        super().__init__(shell)
+        self.connection: Connection | None = None
+
+    @line_magic("gql")
+    def gql(self, line: str) -> Connection | None:
+        """Opens a connection and makes it the one `%%gql` runs on.
+
+            %gql social.zu1
+            %gql --read-only social.zu1
+            %gql
+            %gql --close
+
+        The connection comes back so that a cell can keep it, and it is
+        closed at the end of the session like any other.
+        """
+        words = shlex.split(line)
+        read_only = "--read-only" in words
+        closing = "--close" in words
+        paths = [word for word in words if not word.startswith("-")]
+        unknown = [word for word in words if word.startswith("-")]
+        for word in unknown:
+            if word not in ("--read-only", "--close"):
+                raise UsageError(f"%gql does not take {word}")
+        if closing:
+            if self.connection is not None:
+                self.connection.close()
+                self.connection = None
+            return None
+        if not paths:
+            if self.connection is None:
+                raise UsageError("no connection is open here: %gql <path> opens one")
+            return self.connection
+        if len(paths) > 1:
+            raise UsageError("%gql opens one database, and this named more than one")
+        # The old one is closed rather than left holding a file, since
+        # a notebook that opens a second database has finished with the
+        # first and nothing else here has a name for it.
+        if self.connection is not None:
+            self.connection.close()
+        self.connection = connect(Path(paths[0]).expanduser(), read_only=read_only)
+        return self.connection
+
+    @cell_magic("gql")
+    def gql_cell(self, line: str, cell: str) -> Any:
+        """Runs the cell as one statement on the current connection."""
+        options = self.options(line)
+        conn = self.current(options.get("conn"))
+        statement = cell.strip()
+        # A person types the semicolon out of habit and a statement
+        # does not take one, which is a syntax error about a character
+        # nobody meant to type.
+        while statement.endswith(";"):
+            statement = statement[:-1].rstrip()
+        if not statement:
+            raise UsageError("this cell holds no statement")
+        result = conn.execute(statement, self.params(options.get("params")))
+        out = options.get("out")
+        if out is None:
+            return result
+        self.namespace()[out] = result
+        return None
+
+    def options(self, line: str) -> dict[str, str]:
+        """`--conn`, `--params` and `--out`, each naming a variable."""
+        words = shlex.split(line)
+        taken: dict[str, str] = {}
+        while words:
+            word = words.pop(0)
+            name = word.removeprefix("--")
+            if name == word or name not in ("conn", "params", "out"):
+                raise UsageError(f"%%gql takes --conn, --params and --out, and not {word}")
+            if not words:
+                raise UsageError(f"--{name} names a variable, and this named none")
+            taken[name] = words.pop(0)
+        return taken
+
+    def namespace(self) -> dict[str, Any]:
+        """Where the notebook's own names live."""
+        if self.shell is None:
+            raise UsageError("there is no notebook here to read names out of")
+        return self.shell.user_ns
+
+    def current(self, named: str | None) -> Connection:
+        """The connection to run on: the one named, the one `%gql`
+        opened, or the one the notebook made if it made exactly one.
+        """
+        if named is not None:
+            found = self.namespace().get(named)
+            if not isinstance(found, Connection):
+                raise UsageError(f"'{named}' is not a zudb.Connection in this notebook")
+            return found
+        if self.connection is not None:
+            return self.connection
+        theirs = sorted(
+            name
+            for name, value in self.namespace().items()
+            if isinstance(value, Connection) and not name.startswith("_")
+        )
+        if len(theirs) == 1:
+            return self.namespace()[theirs[0]]
+        if not theirs:
+            raise UsageError(
+                "no connection is open here: %gql <path> opens one, or make one with "
+                "zudb.connect and %%gql will find it"
+            )
+        raise UsageError(
+            "this notebook holds more than one connection ("
+            + ", ".join(theirs)
+            + "), so %%gql --conn <name> has to say which"
+        )
+
+    def params(self, named: str | None) -> dict[str, Any] | None:
+        """The parameters, out of the variable `--params` named."""
+        if named is None:
+            return None
+        found = self.namespace().get(named)
+        if not isinstance(found, dict):
+            raise UsageError(f"'{named}' is not a dict of parameters in this notebook")
+        return found
+
+
+def load_ipython_extension(ipython: Any) -> None:
+    """Registers `%gql` and `%%gql`, which is what `%load_ext` calls.
+
+    Registered by hand rather than on import, because a library that
+    reaches into the interpreter it was imported into is a library that
+    surprises somebody, and `%load_ext zudb.magic` is one line.
+    """
+    ipython.register_magics(ZuMagics)
diff --git a/src/conn.rs b/src/conn.rs
index 9428676..9ebcb52 100644
--- a/src/conn.rs
+++ b/src/conn.rs
@@ -20,6 +20,7 @@ use zudb::{Config, Database, Interrupt};
 use crate::appender::Appender;
 use crate::columns;
 use crate::error::{closed, programming, to_py_err};
+use crate::html;
 use crate::interrupt;
 use crate::register;
 use crate::txn::Transaction;
@@ -571,6 +572,46 @@ impl Result {
             self.result.rows.len()
         )
     }
+
+    /// The rows as an HTML table, which is what a notebook shows.
+    ///
+    /// Jupyter asks for this before it falls back to `repr`, so a
+    /// result in a cell is the rows and not a line about how many
+    /// there are. Only the first hundred are drawn and the note
+    /// underneath says how many there were, because a million rows of
+    /// markup is a notebook file nobody can open.
+    ///
+    /// Reading it does not move the cursor `fetchone` uses, for the
+    /// same reason iterating does not: a person who looked at a result
+    /// has not taken any of its rows.
+    fn _repr_html_(&self, py: Python<'_>) -> PyResult<String> {
+        let rows = &self.result.rows;
+        let columns = &self.result.columns;
+        if columns.is_empty() {
+            return Ok(html::wrap(
+                "<span class=\"zu-note\">no columns, which is what a statement that \
+                 writes gives back</span>",
+            ));
+        }
+        let mut out = String::from("<table class=\"zu-table\"><thead><tr>");
+        for name in columns {
+            out.push_str(&format!("<th>{}</th>", html::escape(name)));
+        }
+        out.push_str("</tr></thead><tbody>");
+        for row in rows.iter().take(html::SHOWN) {
+            out.push_str("<tr>");
+            for value in row {
+                out.push_str(&html::cell(&to_py(py, value, &self.names)?)?);
+            }
+            out.push_str("</tr>");
+        }
+        out.push_str("</tbody></table>");
+        out.push_str(&format!(
+            "<div class=\"zu-note\">{}</div>",
+            html::note(rows.len(), columns.len())
+        ));
+        Ok(html::wrap(&out))
+    }
 }
 
 impl Result {
diff --git a/src/html.rs b/src/html.rs
new file mode 100644
index 0000000..99088bb
--- /dev/null
+++ b/src/html.rs
@@ -0,0 +1,215 @@
+//! What a notebook shows.
+//!
+//! Jupyter asks an object for `_repr_html_` before it falls back to
+//! `repr`, so a result printed in a cell can be a table instead of a
+//! line saying how many rows it has. That is most of what a person
+//! does with this library in a notebook, and a line of text is a
+//! strictly worse answer than the rows themselves.
+//!
+//! Nothing here is a dependency on anything. The markup is a table, a
+//! stylesheet and no script, so it survives `nbconvert`, an exported
+//! HTML file and a notebook diff, and there is nothing to install for
+//! it to work.
+//!
+//! Colours are the notebook's own, through `currentColor` and opacity,
+//! because a light theme and a dark one are both in the room and a
+//! guess about which would be wrong half the time.
+
+use pyo3::prelude::*;
+use pyo3::types::{PyBool, PyFloat, PyInt};
+
+use crate::value::{Node, Path, Rel};
+
+/// Rows a table shows before it stops and says how many there were.
+///
+/// A result is already in memory, so this is not about the cost of
+/// reading it: a hundred rows is more than a person reads and about a
+/// screen and a half of scrolling, and a million rows of markup is a
+/// notebook file nobody can open.
+pub const SHOWN: usize = 100;
+
+/// The longest a cell is shown at, in characters.
+///
+/// A column holding a document would otherwise be a page holding a
+/// document, and the rest of the row would be somewhere below it.
+pub const WIDEST: usize = 200;
+
+/// The stylesheet, written beside every table.
+///
+/// Classes rather than an attribute on every cell, because a hundred
+/// rows of ten columns is a thousand cells and the style repeated on
+/// each of them would be most of what the notebook stores. Repeating
+/// the block itself costs a few hundred bytes per result and defines
+/// exactly the same rules every time.
+const STYLE: &str = "<style>\
+.zu-wrap{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;line-height:1.5}\
+.zu-table{border-collapse:collapse}\
+.zu-table th{text-align:left;font-weight:600;padding:2px 12px 2px 0;\
+border-bottom:1px solid currentColor;opacity:.75;white-space:pre}\
+.zu-table td{padding:2px 12px 2px 0;vertical-align:top;white-space:pre}\
+.zu-num{text-align:right;font-variant-numeric:tabular-nums}\
+.zu-null{opacity:.45;font-style:italic}\
+.zu-note{opacity:.6;padding-top:4px}\
+.zu-at{opacity:.6}\
+</style>";
+
+/// The markup for one thing, with the stylesheet and the wrapper that
+/// the classes hang off.
+pub fn wrap(inner: &str) -> String {
+    format!("{STYLE}<div class=\"zu-wrap\">{inner}</div>")
+}
+
+/// Text that cannot be markup.
+///
+/// A string column holding `<script>` is a string column, and a client
+/// that pasted it into a page unescaped would be a client that runs a
+/// caller's data as code in their notebook.
+pub fn escape(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    for letter in text.chars() {
+        match letter {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            '"' => out.push_str("&quot;"),
+            _ => out.push(letter),
+        }
+    }
+    out
+}
+
+/// Text cut to `WIDEST` characters, with a mark where it was cut.
+///
+/// Characters and not bytes, so a column of Japanese is cut where a
+/// column of English is and nothing is cut through the middle of a
+/// letter.
+fn clipped(text: &str) -> String {
+    let mut out = String::new();
+    for (seen, letter) in text.chars().enumerate() {
+        if seen == WIDEST {
+            out.push('…');
+            break;
+        }
+        out.push(letter);
+    }
+    out
+}
+
+/// A count with its thousands marked, because six digits are read by
+/// counting them and `100,000` is read by looking at it.
+pub fn counted(number: usize) -> String {
+    let digits = number.to_string();
+    let mut out = String::with_capacity(digits.len() + digits.len() / 3);
+    for (seen, digit) in digits.chars().enumerate() {
+        if seen > 0 && (digits.len() - seen).is_multiple_of(3) {
+            out.push(',');
+        }
+        out.push(digit);
+    }
+    out
+}
+
+/// `1 row` and `2 rows`, which is worth the four lines it takes.
+fn many(count: usize, one: &str, more: &str) -> String {
+    format!("{} {}", counted(count), if count == 1 { one } else { more })
+}
+
+/// What a table says underneath itself.
+pub fn note(rows: usize, columns: usize) -> String {
+    let mut text = format!(
+        "{}, {}",
+        many(rows, "row", "rows"),
+        many(columns, "column", "columns")
+    );
+    if rows > SHOWN {
+        text.push_str(&format!(", first {} shown", counted(SHOWN)));
+    }
+    text
+}
+
+/// One node, as the pair that names it.
+pub fn node(node: &Node) -> String {
+    format!(
+        "<span class=\"zu-node\">({} <span class=\"zu-at\">#{}</span>)</span>",
+        escape(&node.table),
+        node.offset
+    )
+}
+
+/// One edge on its own, which has to say what it joins because there
+/// is nothing beside it saying so.
+pub fn rel(rel: &Rel) -> String {
+    format!(
+        "<span class=\"zu-rel\"><span class=\"zu-at\">#{}</span> -[{}]-&gt; \
+         <span class=\"zu-at\">#{}</span></span>",
+        rel.src,
+        escape(&rel.table),
+        rel.dst
+    )
+}
+
+/// One edge inside a walk, where the nodes on either side already say
+/// which rows it joins and repeating them would be noise.
+fn hop(rel: &Rel) -> String {
+    format!(
+        "<span class=\"zu-rel\">-[{}]-&gt;</span>",
+        escape(&rel.table)
+    )
+}
+
+/// A walk, drawn the way a statement writes one.
+pub fn path(py: Python<'_>, path: &Path) -> PyResult<String> {
+    let mut out = String::from("<span class=\"zu-path\">");
+    for (place, element) in path.elements.bind(py).iter().enumerate() {
+        if place > 0 {
+            out.push(' ');
+        }
+        out.push_str(&piece(&element)?);
+    }
+    out.push_str("</span>");
+    Ok(out)
+}
+
+/// One element of a walk, or anything else that turned up in a list
+/// that is supposed to hold nodes and edges.
+fn piece(element: &Bound<'_, PyAny>) -> PyResult<String> {
+    if let Ok(one) = element.cast::<Node>() {
+        return Ok(node(&one.borrow()));
+    }
+    if let Ok(one) = element.cast::<Rel>() {
+        return Ok(hop(&one.borrow()));
+    }
+    Ok(escape(&clipped(&element.str()?.to_string_lossy())))
+}
+
+/// One cell of a table, tag and all.
+///
+/// Values are shown the way `str` shows them rather than the way
+/// `repr` does, so a string is its text and not its quotes, and the
+/// three graph classes are drawn instead. Numbers line up on the
+/// right, which is the one piece of formatting a table of numbers
+/// cannot do without, and booleans are left alone there: Python says a
+/// `bool` is an `int` and a column of `True` is not a column to read
+/// digit by digit.
+pub fn cell(object: &Bound<'_, PyAny>) -> PyResult<String> {
+    if object.is_none() {
+        return Ok("<td class=\"zu-null\">null</td>".to_string());
+    }
+    if let Ok(one) = object.cast::<Node>() {
+        return Ok(format!("<td>{}</td>", node(&one.borrow())));
+    }
+    if let Ok(one) = object.cast::<Rel>() {
+        return Ok(format!("<td>{}</td>", rel(&one.borrow())));
+    }
+    if let Ok(one) = object.cast::<Path>() {
+        return Ok(format!("<td>{}</td>", path(object.py(), &one.borrow())?));
+    }
+    let text = escape(&clipped(&object.str()?.to_string_lossy()));
+    let counts = (object.is_instance_of::<PyInt>() || object.is_instance_of::<PyFloat>())
+        && !object.is_instance_of::<PyBool>();
+    if counts {
+        Ok(format!("<td class=\"zu-num\">{text}</td>"))
+    } else {
+        Ok(format!("<td>{text}</td>"))
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index f3b0864..60eeb47 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -18,6 +18,7 @@ mod columns;
 mod conn;
 mod error;
 mod frame;
+mod html;
 mod interrupt;
 mod load;
 mod register;
diff --git a/src/value.rs b/src/value.rs
index d268cfa..fbaaedf 100644
--- a/src/value.rs
+++ b/src/value.rs
@@ -16,6 +16,8 @@ use zu_common::{DurationKind, Temporal};
 use zudb::query::Value;
 use zudb::zu1::catalog::Catalog;
 
+use crate::html;
+
 /// Microseconds in a day, which is the unit `datetime.timedelta`
 /// normalizes to and the one this has to split a duration across.
 const MICROS_PER_DAY: i64 = 86_400 * 1_000_000;
@@ -103,6 +105,12 @@ impl Node {
     fn __repr__(&self) -> String {
         format!("Node({}, {})", self.table, self.offset)
     }
+
+    /// The node as a notebook draws it, which is the pair that names
+    /// it: the table it is in and the row it sits at.
+    fn _repr_html_(&self) -> String {
+        html::wrap(&html::node(self))
+    }
 }
 
 /// One edge of the graph.
@@ -140,6 +148,13 @@ impl Rel {
     fn __repr__(&self) -> String {
         format!("Rel({}, {} -> {})", self.table, self.src, self.dst)
     }
+
+    /// The edge as a notebook draws it, with the rows it joins on
+    /// either side of the arrow, since nothing beside it says which
+    /// they are.
+    fn _repr_html_(&self) -> String {
+        html::wrap(&html::rel(self))
+    }
 }
 
 /// A walk: nodes and edges alternating, a node at each end.
@@ -179,6 +194,12 @@ impl Path {
     fn __repr__(&self, py: Python<'_>) -> String {
         format!("Path({} hops)", self.__len__(py))
     }
+
+    /// The walk as a notebook draws it, nodes and arrows alternating
+    /// the way a statement writes one.
+    fn _repr_html_(&self, py: Python<'_>) -> PyResult<String> {
+        Ok(html::wrap(&html::path(py, self)?))
+    }
 }
 
 impl Path {
diff --git a/tests/test_html.py b/tests/test_html.py
new file mode 100644
index 0000000..a593cc0
--- /dev/null
+++ b/tests/test_html.py
@@ -0,0 +1,155 @@
+"""What a notebook shows.
+
+A result in a cell is drawn as a table because Jupyter asks an object
+for `_repr_html_` before it falls back to `repr`. What is checked here
+is the markup itself, since nothing else can: a notebook renders it and
+a person looks at it, and neither of those is a test.
+
+The two that matter are the escaping and the cut. A string column
+holding a tag is a string column, and a client that pasted one into the
+page would run a caller's data as code in their notebook. A result of a
+million rows is a result somebody typed by accident, and a million rows
+of markup is a notebook file that will not open again.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import zudb
+
+
+def cells(html: str) -> list[str]:
+    """The text of every body cell, tags taken out."""
+    body = html.split("<tbody>")[1].split("</tbody>")[0]
+    return [re.sub(r"<[^>]+>", "", cell) for cell in re.findall(r"<td[^>]*>(.*?)</td>", body)]
+
+
+def headers(html: str) -> list[str]:
+    return re.findall(r"<th>(.*?)</th>", html)
+
+
+def note(html: str) -> str:
+    return re.findall(r'<div class="zu-note">(.*?)</div>', html)[0]
+
+
+def test_a_result_is_a_table_of_its_rows(social: zudb.Connection) -> None:
+    html = social.execute("MATCH (p:person) RETURN p.uid AS uid, p.name AS name")._repr_html_()
+    assert headers(html) == ["uid", "name"]
+    assert cells(html) == ["10", "ada", "20", "grace", "30", "kay"]
+    assert note(html) == "3 rows, 2 columns"
+
+
+def test_the_stylesheet_travels_with_the_table(social: zudb.Connection) -> None:
+    """No install, no script, and nothing to load from anywhere."""
+    html = social.execute("MATCH (p:person) RETURN p.uid AS uid")._repr_html_()
+    assert html.startswith("<style>")
+    assert "<script" not in html
+    assert "http" not in html
+
+
+def test_a_number_lines_up_on_the_right_and_a_string_does_not(
+    social: zudb.Connection,
+) -> None:
+    html = social.execute(
+        "MATCH (p:person) RETURN p.uid AS uid, p.name AS name, p.score AS score"
+    )._repr_html_()
+    row = re.findall(r"<tr>(.*?)</tr>", html.split("<tbody>")[1])[0]
+    assert row.count('class="zu-num"') == 2, "the integer and the float"
+
+
+def test_a_boolean_is_not_a_number_to_line_up(empty: zudb.Connection) -> None:
+    empty.execute("INSERT (p:person {uid: 1, ok: true})")
+    html = empty.execute("MATCH (p:person) RETURN p.ok AS ok")._repr_html_()
+    assert cells(html) == ["True"]
+    assert 'class="zu-num"' not in html
+
+
+def test_a_null_says_so_rather_than_being_blank(empty: zudb.Connection) -> None:
+    empty.execute("INSERT (p:person {uid: 1, name: 'ada'})")
+    html = empty.execute("MATCH (p:person) RETURN null AS nothing")._repr_html_()
+    assert cells(html) == ["null"]
+    assert 'class="zu-null"' in html
+
+
+def test_a_tag_in_a_value_is_text_and_not_markup(empty: zudb.Connection) -> None:
+    empty.execute("INSERT (p:person {uid: 1, name: '<script>alert(1)</script>'})")
+    html = empty.execute("MATCH (p:person) RETURN p.name AS name")._repr_html_()
+    assert "<script>" not in html
+    assert "&lt;script&gt;alert(1)&lt;/script&gt;" in html
+
+
+def test_a_tag_in_a_column_name_is_text_too(empty: zudb.Connection) -> None:
+    empty.execute("INSERT (p:person {uid: 1})")
+    html = empty.execute("MATCH (p:person) RETURN p.uid AS `<b>uid</b>`")._repr_html_()
+    assert "<b>" not in html
+    assert "&lt;b&gt;uid&lt;/b&gt;" in headers(html)
+
+
+def test_a_long_value_is_cut_and_marked(social: zudb.Connection) -> None:
+    social.execute("INSERT (p:person {uid: 40, name: $name, score: 1.0})", {"name": "a" * 500})
+    html = social.execute("MATCH (p:person) WHERE p.uid = 40 RETURN p.name AS name")._repr_html_()
+    shown = cells(html)[0]
+    assert shown == "a" * 200 + "…"
+
+
+def test_a_long_result_is_cut_and_says_how_long_it_was(tmp_path: Path) -> None:
+    path = tmp_path / "many.zu1"
+    zudb.load(path, nodes="person", columns={"uid": list(range(5_000))})
+    with zudb.connect(path, read_only=True) as conn:
+        html = conn.execute("MATCH (p:person) RETURN p.uid AS uid")._repr_html_()
+    assert len(cells(html)) == 100
+    assert note(html) == "5,000 rows, 1 column, first 100 shown"
+
+
+def test_drawing_a_result_does_not_take_any_of_its_rows(social: zudb.Connection) -> None:
+    """A person who looked at a result has not read it."""
+    result = social.execute("MATCH (p:person) RETURN p.name AS name")
+    result._repr_html_()
+    assert result.fetchone() == ("ada",)
+    result._repr_html_()
+    assert result.fetchone() == ("grace",)
+
+
+def test_a_result_with_no_rows_is_a_table_with_none(social: zudb.Connection) -> None:
+    html = social.execute("MATCH (p:person) WHERE p.uid > 99 RETURN p.name AS name")._repr_html_()
+    assert headers(html) == ["name"]
+    assert cells(html) == []
+    assert note(html) == "0 rows, 1 column"
+
+
+def test_a_statement_that_writes_says_it_has_no_columns(empty: zudb.Connection) -> None:
+    html = empty.execute("INSERT (p:person {uid: 1})")._repr_html_()
+    assert "no columns" in html
+    assert "<table" not in html
+
+
+def test_a_node_is_drawn_as_the_pair_that_names_it(loaded: zudb.Connection) -> None:
+    (node,) = loaded.execute("MATCH (p:person) RETURN p AS p").fetchone()
+    html = node._repr_html_()
+    assert "person" in html and "#0" in html
+
+
+def test_an_edge_says_which_rows_it_joins(loaded: zudb.Connection) -> None:
+    (rel,) = loaded.execute("MATCH ()-[r:knows]->() RETURN r AS r").fetchone()
+    html = rel._repr_html_()
+    assert "#0" in html and "#1" in html and "-[knows]-&gt;" in html
+
+
+def test_a_path_is_drawn_as_a_walk(loaded: zudb.Connection) -> None:
+    (path,) = loaded.execute(
+        "MATCH q = (a:person)-[:knows]->(b:person)-[:knows]->(c:person) RETURN q AS q"
+    ).fetchone()
+    html = path._repr_html_()
+    assert html.count("zu-node") == 3
+    assert html.count("zu-rel") == 2
+    assert "#0" in html and "#1" in html and "#2" in html
+
+
+def test_a_graph_value_in_a_cell_is_drawn_like_it_is_on_its_own(
+    loaded: zudb.Connection,
+) -> None:
+    html = loaded.execute("MATCH (p:person) RETURN p AS p")._repr_html_()
+    assert html.count("zu-node") == 3
+    assert "&lt;" not in html.split("<tbody>")[1].split("</tbody>")[0], "drawn, not escaped repr"
diff --git a/tests/test_magic.py b/tests/test_magic.py
new file mode 100644
index 0000000..671d2d7
--- /dev/null
+++ b/tests/test_magic.py
@@ -0,0 +1,198 @@
+"""`%gql` and `%%gql`, against a real shell.
+
+IPython is not a dependency of the wheel and these skip without it,
+which is the same rule pyarrow and pandas get. What it is not is a
+mock: the magics are registered with `%load_ext` and run through
+`run_line_magic` and `run_cell_magic`, so what is checked is what a
+notebook does rather than what a method returns when called directly.
+
+Most of these are about which connection a cell runs on, because that
+is the whole of the magic's own behaviour. The statement is handed
+straight to `execute` and everything else in the suite says what that
+does.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+import zudb
+
+pytest.importorskip("IPython")
+
+from IPython.core.error import UsageError  # noqa: E402
+from IPython.core.interactiveshell import InteractiveShell  # noqa: E402
+
+
+@pytest.fixture
+def shell() -> Any:
+    """A shell with the extension loaded, thrown away afterwards.
+
+    `InteractiveShell` is a singleton, so the instance is cleared at
+    the end and the next test gets a namespace of its own rather than
+    the connections this one left in it.
+    """
+    shell = InteractiveShell.instance()
+    shell.run_line_magic("load_ext", "zudb.magic")
+    yield shell
+    InteractiveShell.clear_instance()
+
+
+def gql(shell: Any, cell: str, line: str = "") -> Any:
+    return shell.run_cell_magic("gql", line, cell)
+
+
+def test_the_line_magic_opens_a_connection_the_cell_magic_uses(shell: Any, tmp_path: Path) -> None:
+    conn = shell.run_line_magic("gql", str(tmp_path / "opened.zu1"))
+    assert isinstance(conn, zudb.Connection)
+    gql(shell, "INSERT (p:person {uid: 10, name: 'ada'})")
+    result = gql(shell, "MATCH (p:person) RETURN p.name AS name")
+    assert result.fetchall() == [("ada",)]
+
+
+def test_the_result_is_the_value_of_the_cell(shell: Any, tmp_path: Path) -> None:
+    """Which is what makes the notebook draw it as a table."""
+    shell.run_line_magic("gql", str(tmp_path / "shown.zu1"))
+    gql(shell, "INSERT (p:person {uid: 10, name: 'ada'})")
+    result = gql(shell, "MATCH (p:person) RETURN p.name AS name")
+    assert isinstance(result, zudb.Result)
+    assert "<table" in result._repr_html_()
+
+
+def test_the_line_magic_with_nothing_says_which_connection_is_open(
+    shell: Any, tmp_path: Path
+) -> None:
+    opened = shell.run_line_magic("gql", str(tmp_path / "asked.zu1"))
+    assert shell.run_line_magic("gql", "") is opened
+
+
+def test_the_line_magic_with_nothing_and_no_connection_says_how_to_open_one(
+    shell: Any,
+) -> None:
+    with pytest.raises(UsageError, match="%gql <path>"):
+        shell.run_line_magic("gql", "")
+
+
+def test_a_read_only_connection_is_opened_when_asked_for(shell: Any, tmp_path: Path) -> None:
+    path = tmp_path / "readonly.zu1"
+    zudb.load(path, nodes="person", columns={"uid": [1, 2, 3]})
+    conn = shell.run_line_magic("gql", f"--read-only {path}")
+    assert conn.read_only is True
+    assert len(gql(shell, "MATCH (p:person) RETURN p.uid AS uid")) == 3
+
+
+def test_opening_a_second_database_closes_the_first(shell: Any, tmp_path: Path) -> None:
+    """Nothing else here has a name for it, so leaving it open would
+    leave a file held by nobody."""
+    first = shell.run_line_magic("gql", str(tmp_path / "first.zu1"))
+    second = shell.run_line_magic("gql", str(tmp_path / "second.zu1"))
+    assert first.closed is True
+    assert second.closed is False
+
+
+def test_close_shuts_the_connection_the_magic_opened(shell: Any, tmp_path: Path) -> None:
+    conn = shell.run_line_magic("gql", str(tmp_path / "closing.zu1"))
+    assert shell.run_line_magic("gql", "--close") is None
+    assert conn.closed is True
+    with pytest.raises(UsageError, match="no connection is open"):
+        shell.run_line_magic("gql", "")
+
+
+def test_the_cell_magic_finds_the_one_connection_the_notebook_made(
+    shell: Any, tmp_path: Path
+) -> None:
+    """A notebook that already called `zudb.connect` needs no `%gql`."""
+    shell.user_ns["conn"] = zudb.connect(tmp_path / "theirs.zu1")
+    gql(shell, "INSERT (p:person {uid: 10, name: 'ada'})")
+    assert gql(shell, "MATCH (p:person) RETURN p.name AS name").fetchall() == [("ada",)]
+
+
+def test_two_connections_in_the_notebook_means_the_cell_has_to_say_which(
+    shell: Any, tmp_path: Path
+) -> None:
+    shell.user_ns["reader"] = zudb.connect(tmp_path / "one.zu1")
+    shell.user_ns["writer"] = zudb.connect(tmp_path / "two.zu1")
+    with pytest.raises(UsageError, match="reader, writer"):
+        gql(shell, "MATCH (p:person) RETURN p.uid AS uid")
+    shell.user_ns["writer"].execute("INSERT (p:person {uid: 10, name: 'ada'})")
+    result = gql(shell, "MATCH (p:person) RETURN p.name AS name", "--conn writer")
+    assert result.fetchall() == [("ada",)]
+
+
+def test_a_name_that_is_not_a_connection_is_refused(shell: Any, tmp_path: Path) -> None:
+    shell.run_line_magic("gql", str(tmp_path / "named.zu1"))
+    shell.user_ns["other"] = "not a connection"
+    with pytest.raises(UsageError, match="not a zudb.Connection"):
+        gql(shell, "MATCH (p:person) RETURN p.uid AS uid", "--conn other")
+
+
+def test_no_connection_anywhere_says_both_ways_to_get_one(shell: Any) -> None:
+    with pytest.raises(UsageError, match="zudb.connect"):
+        gql(shell, "MATCH (p:person) RETURN p.uid AS uid")
+
+
+def test_parameters_come_out_of_a_variable(shell: Any, tmp_path: Path) -> None:
+    shell.run_line_magic("gql", str(tmp_path / "params.zu1"))
+    gql(shell, "INSERT (p:person {uid: 10, name: 'ada'})")
+    gql(shell, "INSERT (p:person {uid: 20, name: 'grace'})")
+    shell.user_ns["args"] = {"uid": 20}
+    result = gql(
+        shell, "MATCH (p:person) WHERE p.uid = $uid RETURN p.name AS name", "--params args"
+    )
+    assert result.fetchall() == [("grace",)]
+
+
+def test_a_params_variable_that_is_not_a_dict_is_refused(shell: Any, tmp_path: Path) -> None:
+    shell.run_line_magic("gql", str(tmp_path / "wrong.zu1"))
+    shell.user_ns["args"] = [1, 2, 3]
+    with pytest.raises(UsageError, match="not a dict"):
+        gql(shell, "MATCH (p:person) RETURN p.uid AS uid", "--params args")
+
+
+def test_out_puts_the_result_in_a_variable_and_shows_nothing(shell: Any, tmp_path: Path) -> None:
+    shell.run_line_magic("gql", str(tmp_path / "out.zu1"))
+    gql(shell, "INSERT (p:person {uid: 10, name: 'ada'})")
+    assert gql(shell, "MATCH (p:person) RETURN p.name AS name", "--out rows") is None
+    assert shell.user_ns["rows"].fetchall() == [("ada",)]
+
+
+def test_a_trailing_semicolon_is_taken_off(shell: Any, tmp_path: Path) -> None:
+    """A person types it out of habit and a statement does not take one."""
+    shell.run_line_magic("gql", str(tmp_path / "semi.zu1"))
+    gql(shell, "INSERT (p:person {uid: 10, name: 'ada'});")
+    assert gql(shell, "MATCH (p:person) RETURN p.name AS name ;\n").fetchall() == [("ada",)]
+
+
+def test_an_empty_cell_says_so(shell: Any, tmp_path: Path) -> None:
+    shell.run_line_magic("gql", str(tmp_path / "blank.zu1"))
+    with pytest.raises(UsageError, match="no statement"):
+        gql(shell, "\n  \n")
+
+
+def test_an_option_neither_magic_takes_is_refused(shell: Any, tmp_path: Path) -> None:
+    with pytest.raises(UsageError, match="--verbose"):
+        shell.run_line_magic("gql", "--verbose social.zu1")
+    shell.run_line_magic("gql", str(tmp_path / "options.zu1"))
+    with pytest.raises(UsageError, match="--verbose"):
+        gql(shell, "MATCH (p:person) RETURN p.uid AS uid", "--verbose")
+
+
+def test_an_option_with_no_variable_after_it_is_refused(shell: Any, tmp_path: Path) -> None:
+    shell.run_line_magic("gql", str(tmp_path / "dangling.zu1"))
+    with pytest.raises(UsageError, match="names a variable"):
+        gql(shell, "MATCH (p:person) RETURN p.uid AS uid", "--out")
+
+
+def test_two_paths_at_once_is_refused(shell: Any, tmp_path: Path) -> None:
+    with pytest.raises(UsageError, match="more than one"):
+        shell.run_line_magic("gql", f"{tmp_path / 'a.zu1'} {tmp_path / 'b.zu1'}")
+
+
+def test_a_statement_that_is_wrong_raises_what_it_would_have(shell: Any, tmp_path: Path) -> None:
+    """The magic is a way in and not a layer: the engine's exception
+    arrives as the engine's exception."""
+    shell.run_line_magic("gql", str(tmp_path / "wrong.zu1"))
+    with pytest.raises(zudb.SyntaxError):
+        gql(shell, "MATCH (p:person RETURN p")