table3 0.3.0__tar.gz → 0.4.0__tar.gz

{table3-0.3.0 → table3-0.4.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0 — 2026-11-03
+
+### Added
+
+- `table3.view(data)` opens a data explorer over the first 10,000 rows, as
+  R's `View()`: one grid to scroll, with row numbers, a search box, headers
+  that sort on a click (ascending, descending, off; nulls last), and a filter
+  under each column: from–to for numbers and dates (`2008` matches a year),
+  "contains" for text, and a pick-list for booleans and columns of at most
+  50 values. The status line counts the rows that pass ("120 of 344 rows").
+  It runs in the notebook's browser, so it works in saved notebooks; the
+  rows are JSON drawn a screen at a time, about 1 MB for 10,000 rows of a
+  dozen columns. Where output scripts don't run, it shows the first 100
+  rows as `show()` does. [docs/explorer.md](docs/explorer.md) has the design.
+
 ## 0.3.0 — 2026-11-02
 
 table3 is view3 renamed: the table is how a frame prints in a notebook, as

{table3-0.3.0/src/table3.egg-info → table3-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: table3
-Version: 0.3.0
+Version: 0.4.0
 Summary: Paged, theme-aware tables in notebook output: shared by tidy3, tidy3a and stats3
 Author: Rigoberto Leyva Salmeron
 License-Expression: MIT
@@ -19,6 +19,8 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ipython>=8.0; extra == "dev"
 Requires-Dist: pandas>=2.1.4; extra == "dev"
 Requires-Dist: pyarrow>=15.0; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: pytest-playwright>=0.5; extra == "browser"
 Dynamic: license-file
 
 # table3
@@ -51,7 +53,20 @@ full value on hover. Wide tables show as many columns as fit, with
 arrows to the rest. The table follows the notebook's light or dark theme in
 VS Code, JupyterLab and SolveIt.
 
-`show()` returns what it was given, so it can sit in the middle of a pipe.
+## Explore
+
+`table3.view(penguins)` opens a data explorer, as R's `View()` does: one
+grid of up to 10,000 rows with a search box, headers that sort on a click,
+and a filter under each column (from–to for numbers and dates, "contains"
+for text, a pick-list for columns of few values).
+
+```python
+table3.view(penguins);
+table3.view(penguins, n=50_000, height=600);  # more rows, a taller grid
+```
+
+`show()` and `view()` return what they were given, so they can sit in the
+middle of a pipe.
 As a cell's last line the notebook also prints that value; end the line with
 `;` to hide it.
 
@@ -72,6 +87,6 @@ def _repr_html_(self):
 ## More
 
 [docs/design.md](docs/design.md) records the design and what each package
-adds. table3 was first released as view3 0.1 and 0.2, where `show()` was
-`view()`, and its versions continue from them. The name `view` is kept for a
-data explorer, as R's `View()` opens one.
+adds, and [docs/explorer.md](docs/explorer.md) the explorer's. table3 was
+first released as view3 0.1 and 0.2, where `show()` was `view()`; its
+versions continue from them, and `view()` is now the explorer.

{table3-0.3.0 → table3-0.4.0}/README.md

@@ -28,7 +28,20 @@ full value on hover. Wide tables show as many columns as fit, with
 arrows to the rest. The table follows the notebook's light or dark theme in
 VS Code, JupyterLab and SolveIt.
 
-`show()` returns what it was given, so it can sit in the middle of a pipe.
+## Explore
+
+`table3.view(penguins)` opens a data explorer, as R's `View()` does: one
+grid of up to 10,000 rows with a search box, headers that sort on a click,
+and a filter under each column (from–to for numbers and dates, "contains"
+for text, a pick-list for columns of few values).
+
+```python
+table3.view(penguins);
+table3.view(penguins, n=50_000, height=600);  # more rows, a taller grid
+```
+
+`show()` and `view()` return what they were given, so they can sit in the
+middle of a pipe.
 As a cell's last line the notebook also prints that value; end the line with
 `;` to hide it.
 
@@ -49,6 +62,6 @@ def _repr_html_(self):
 ## More
 
 [docs/design.md](docs/design.md) records the design and what each package
-adds. table3 was first released as view3 0.1 and 0.2, where `show()` was
-`view()`, and its versions continue from them. The name `view` is kept for a
-data explorer, as R's `View()` opens one.
+adds, and [docs/explorer.md](docs/explorer.md) the explorer's. table3 was
+first released as view3 0.1 and 0.2, where `show()` was `view()`; its
+versions continue from them, and `view()` is now the explorer.

{table3-0.3.0 → table3-0.4.0}/docs/design.md

@@ -2,7 +2,7 @@
 
 Status: accepted 2026-11-02. Released first as view3 (0.1.0 phase 1 of §6,
 0.2.0 `digits=` of §2.1); renamed table3 for 0.3.0, with `show()` and the
-table as tidy3's notebook display (§5).
+table as tidy3's notebook display (§5), which tidy3 0.18.0 uses (phase 2).
 
 tidy3 previews showed ten rows. To see more, a notebook user had to `pull()`
 a column and call `.to_list()` on the parenthesized pipe, losing column
@@ -119,5 +119,6 @@ leaves the names alone.
 2. tidy3: dependency, `__table3__`, the table as `_repr_html_`, reference docs,
    release.
 3. stats3 and tidy3a: hooks and docs.
-4. Later: tidy3's ordinary notebook table formats through table3 (its floats
-   print in full today); loading further rows while paging.
+4. Later: loading further rows while paging.
+5. A data explorer, `table3.view()`, as R's `View()`: planned in
+   [explorer.md](explorer.md).

table3-0.4.0/docs/explorer.md

@@ -0,0 +1,126 @@
+# A data explorer: `table3.view()`
+
+Status: accepted 2026-11-03; phase 1 released in table3 0.4.0.
+
+A printed frame shows as a paged table (design.md). R has a second way to
+look at data: `View(df)` opens RStudio's data viewer, a spreadsheet-like
+grid where you search, sort and filter without writing code. This document
+plans that viewer for table3: `table3.view(data)`, and a `view()` verb in
+tidy3.
+
+## 1. What R's `View()` does
+
+- One grid of every row, scrolled rather than paged, with row numbers and a
+  pinned header.
+- **Search** across every column in one box.
+- **Sort** by clicking a column header: ascending, descending, off.
+- **Filter** per column: a range for numbers and dates, text match for
+  strings, a pick-list for factors.
+- A status line: "Showing 1 to 120 of 344 entries, 8 total columns".
+- It reads only what it shows from the R session, so millions of rows work.
+
+## 2. Where filtering runs
+
+**Phase 1: in the browser.** `view()` writes the first *n* rows into the
+output once, as compact JSON, and a script draws the grid and runs search,
+sort and filters on them.
+
+- It works where the paged table works: SolveIt runs output scripts and runs
+  them again when a dialog is reloaded (probed 2026-11-02); VS Code and
+  trusted Jupyter notebooks run them too. A saved notebook reopens with the
+  explorer working.
+- No new dependency, no kernel connection.
+- It explores only the rows it was given: `n=10_000` by default, about 1 MB
+  for a dozen columns. The status line says when *n* cut the rows ("120 of
+  10,000 rows (first 10,000 of 52,341)").
+- Rows are JSON, not HTML: 10,000 rows of HTML table cells with inline
+  styles would be about 12 MB. The script draws only the rows in view
+  (virtual scrolling), so the grid stays fast at 10,000 rows.
+
+**Phase 3 (later, if needed): through the kernel.** A live widget (anywidget)
+sends each search, sort or filter to polars and gets one screen of rows
+back, so it explores any number of rows lazily. It needs a live kernel and
+shows nothing in a saved notebook, and SolveIt's and CRAFT's support for
+widgets is unknown. It would be an optional extra (`table3[explore]`), and a
+probe like the script probe decides whether to build it.
+
+## 3. Interface
+
+```python
+table3.view(data, *, n=10_000, height=500, digits=None, caption=None)  # shows, returns data
+```
+
+*data* is anything `html()` and `show()` take, `__table3__` objects
+included. It returns *data* unchanged, like `show()`; `;` hides the
+notebook's own print of it. Outside a notebook it prints the first rows as
+`show()` does.
+
+tidy3 adds `view()` as a verb and method, as `glimpse()`: `penguins >> view()`,
+`view(penguins)`, `penguins.view()`, passing the frame through. It is the
+only bare `view` in the family; tidy3a and stats3 document `table3.view(x)`.
+
+## 4. The grid
+
+- **Header**, pinned: name, type (`i64`, `str`), and a sort arrow; clicking
+  cycles ascending, descending, off. One sort column at a time, as R.
+- **Filter row** under the header, one control per column by type:
+  - numbers and dates: two boxes, from and to, either blank;
+  - strings: contains, case-insensitive;
+  - strings with at most 50 distinct values, booleans and categoricals: a
+    pick-list of their values, with `null` as one choice.
+- **Search box** above: rows where any cell's text contains it.
+- **Row numbers** on the left: the row's place in *data*, kept through sorts
+  and filters, as R shows them.
+- **Status line**: "120 of 344 rows | 8 columns", plus the *n* note.
+- **Cells** as the table formats them: `null`, floats by `digits=`, long
+  values cut with the full value on hover. Sorting and filters use the raw
+  values, so numbers sort as numbers and nulls go last.
+- **Wide frames** scroll sideways with the row numbers pinned at the left.
+- **Theme**: table3's colours and translucent greys, every style inline (set
+  by the script), no `<style>` block.
+
+**Without scripts** (an untrusted Jupyter notebook, perhaps CRAFT's
+republish) the output is `show()`'s table of the first 100 rows, with a line
+saying the explorer needs output scripts.
+
+## 5. Data in the output
+
+```json
+{"columns": [{"name": "species", "type": "str", "kind": "text", "choices": ["Adelie", "Chinstrap", "Gentoo"]},
+             {"name": "body_mass_g", "type": "i64", "kind": "number"}],
+ "rows": [["Adelie", 3750], ["Adelie", null]],
+ "shown": [null, ["3750"]],
+ "total": 344, "n": 10000}
+```
+
+- `rows` holds raw values for sorting and filtering: numbers as numbers,
+  dates and times as ISO text (which sorts in order), everything else as
+  text, `null` for missing.
+- `shown` holds a column's display text only where it differs from the raw
+  value: floats (`digits=`) and values cut at 40 characters. Other columns
+  show their raw text.
+- `kind` picks the filter: `number`, `date`, `text`, `choice`, `bool`.
+- The JSON goes in a `<script type="application/json">` element beside the
+  grid, escaped so a value holding `</script>` can't end it.
+
+## 6. Tests
+
+- **pytest**: the JSON (kinds, choices, raw and shown values, escaping, the
+  *n* cut, `__table3__` objects, pandas), `view()` returning its input, the
+  no-script fallback.
+- **pytest with Playwright** (headless Chromium): load the output in a page
+  and drive it: sort cycles, each filter kind, search, row numbers kept,
+  status line counts, virtual scrolling at 10,000 rows, a value holding
+  `</script>`. Its own CI job (`pip install pytest-playwright`, `playwright
+  install chromium`) and a `scripts/check.sh` step, as neither the Mac nor
+  gpudev has a headless browser installed.
+- **By eye**: `docs/check.ipynb` cells for the explorer, in SolveIt (dark
+  theme) and VS Code.
+
+## 7. Phases
+
+1. table3 0.4.0: `table3.view()` in the browser (§2, §4–§6).
+2. tidy3: the `view()` verb and method, reference docs, release.
+3. Probe SolveIt and CRAFT for widgets; if they work and in-browser limits
+   bite, a kernel-backed mode as `table3[explore]`.
+4. tidy3a and stats3: document `table3.view(x)`.

{table3-0.3.0 → table3-0.4.0}/pyproject.toml

@@ -27,6 +27,9 @@ dependencies = [
 [project.optional-dependencies]
 # pandas and pyarrow: the pandas input tests.
 dev = ["pytest>=7.0", "ipython>=8.0", "pandas>=2.1.4", "pyarrow>=15.0"]
+# The explorer's script in headless Chromium (tests/test_explorer_browser.py);
+# also run: python -m playwright install chromium
+browser = ["pytest-playwright>=0.5"]
 
 [project.urls]
 Homepage = "https://github.com/rleyvasal/table3"

{table3-0.3.0 → table3-0.4.0}/src/table3/__init__.py

@@ -5,6 +5,8 @@ Previous / page / Next buttons and, for wide data, as many columns as fit
 the cell plus arrows to the rest: what a package returns from its frames'
 ``_repr_html_`` so they print as R notebooks print data frames.
 ``table3.show(data)`` displays the same table and returns *data* unchanged.
+``table3.view(data)`` opens a data explorer instead, as R's ``View()``: a
+grid of up to 10,000 rows to search, sort and filter.
 
 *data* is a polars DataFrame, LazyFrame or Series, a pandas DataFrame or
 Series, or any object with a ``__table3__`` method::
@@ -25,7 +27,7 @@ import polars as pl
 from table3.__version__ import __version__
 from table3._html import table_html
 
-__all__ = ["__version__", "html", "show"]
+__all__ = ["__version__", "html", "show", "view"]
 
 
 def _from_pandas(df: Any) -> pl.DataFrame:
@@ -109,6 +111,19 @@ def html(
     )
 
 
+def _display(html_text: str) -> bool:
+    """Show *html_text* in a notebook; False outside one."""
+    try:
+        from IPython import get_ipython
+        from IPython.display import HTML, display
+    except ImportError:
+        return False
+    if get_ipython() is None:
+        return False
+    display(HTML(html_text))
+    return True
+
+
 def _text(data: Any, n: int, digits: int | str | None = None) -> str:
     df, total, caption = _parts(data, n)
     # Polars prints no significant digits; digits=k applies to the table only.
@@ -139,15 +154,42 @@ def show(
     the line with ``;`` to hide it.
     """
     _check(n, pages, page_size, height, digits)
-    try:
-        from IPython import get_ipython
-        from IPython.display import HTML, display
-    except ImportError:
-        get_ipython = None
-    if get_ipython is not None and get_ipython() is not None:
-        options = {"n": n, "pages": pages, "page_size": page_size, "height": height}
-        display(HTML(html(data, digits=digits, caption=caption, **options)))
-    else:
+    options = {"n": n, "pages": pages, "page_size": page_size, "height": height}
+    if not _display(html(data, digits=digits, caption=caption, **options)):
         print(_text(data, n, digits))
     return data
 
+
+def view(
+    data: Any,
+    *,
+    n: int = 10_000,
+    height: int = 500,
+    digits: int | str | None = None,
+    caption: str | None = None,
+) -> Any:
+    """Open a data explorer over the first *n* rows of *data*, and return *data*.
+
+    As R's ``View()``: one grid to scroll, a search box, headers that sort
+    on a click, and a filter under each column (from-to for numbers and
+    dates, "contains" for text, a pick-list for columns of few values).
+    The rows go into the notebook's output, so the explorer works in a saved
+    notebook, about 1 MB for 10,000 rows of a dozen columns. *height* is the
+    grid's height in pixels; *digits* and *caption* as in ``html()``. Where
+    output scripts don't run, it shows the first 100 rows as ``show()``.
+    Outside a notebook it prints the first rows.
+    """
+    _check(n, True, 10, height, digits)
+    if height is None:
+        raise ValueError("table3: view() height must be a positive integer")
+    from table3._explore import explorer_html
+
+    df, total, own_caption = _parts(data, n)
+    page = explorer_html(
+        df, total, own_caption if caption is None else caption,
+        n=n, height=height, digits=digits,
+    )
+    if not _display(page):
+        print(_text(data, min(n, 20), digits))
+    return data
+

table3-0.4.0/src/table3/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

table3-0.4.0/src/table3/_explore.py

@@ -0,0 +1,125 @@
+"""The explorer's output: its rows as JSON, a script that draws the grid, and a
+plain table for notebooks that don't run output scripts (docs/explorer.md)."""
+
+from __future__ import annotations
+
+import html as _html
+import json
+import math
+import uuid
+
+import polars as pl
+
+from table3._explorer_js import EXPLORER_JS
+from table3._format import dtype_short, float_text
+from table3._html import MONO, table_html
+
+CHOICES_MAX = 50  # a text column with at most this many values filters by pick-list
+FALLBACK_ROWS = 100
+_MAX_FLOAT = 1.7976931348623157e308  # inf's stand-in: JSON has no infinity
+_SAFE_INT = 2**53  # beyond this a JavaScript number loses digits
+
+
+def _kind(s: pl.Series) -> str:
+    t = s.dtype
+    if t == pl.Boolean:
+        return "bool"
+    if t.is_numeric():
+        return "number"
+    if t.is_temporal():
+        return "date"
+    if t in (pl.String, pl.Categorical) or isinstance(t, pl.Enum):
+        return "choice" if s.n_unique() <= CHOICES_MAX else "text"
+    return "text"
+
+
+def _float_raw(v: float | None) -> float | None:
+    if v is None or math.isnan(v):
+        return None
+    if math.isinf(v):
+        return _MAX_FLOAT if v > 0 else -_MAX_FLOAT
+    return v
+
+
+def _column(s: pl.Series, digits: int | str | None) -> tuple[dict, list, list | None]:
+    """The column's header entry, its raw values, and its display text where it differs."""
+    kind = _kind(s)
+    head = {"name": s.name, "type": dtype_short(s.dtype), "kind": kind}
+    values = s.to_list()
+    shown = None
+    if s.dtype.is_float():
+        raw = [_float_raw(v) for v in values]
+        shown = float_text(s, digits)
+    elif s.dtype.is_integer():
+        raw = values
+        if any(v is not None and abs(v) > _SAFE_INT for v in values):
+            raw = [None if v is None else float(v) for v in values]
+            shown = [None if v is None else str(v) for v in values]
+    elif s.dtype.is_decimal():
+        raw = [None if v is None else float(v) for v in values]
+        shown = [None if v is None else str(v) for v in values]
+    elif kind == "bool":
+        raw = values
+    else:
+        raw = [None if v is None else str(v) for v in values]
+    if kind == "choice":
+        head["choices"] = sorted({v for v in raw if v is not None})
+    return head, raw, shown
+
+
+def payload(df: pl.DataFrame, total: int | None, n: int, digits: int | str | None) -> dict:
+    """What the script needs: columns, rows of raw values, display text, counts."""
+    columns, raws, shown = [], [], []
+    for s in df.get_columns():
+        head, raw, text = _column(s, digits)
+        columns.append(head)
+        raws.append(raw)
+        shown.append(text)
+    return {
+        "columns": columns,
+        "rows": [list(r) for r in zip(*raws)] if raws else [],
+        "shown": shown,
+        "total": total,
+        "n": n,
+    }
+
+
+def _json_for_script(obj: dict) -> str:
+    # "<" never appears raw, so a value holding "</script>" or "<!--" can't end the block.
+    return json.dumps(obj, ensure_ascii=False, allow_nan=False).replace("<", "\\u003c")
+
+
+def explorer_html(
+    df: pl.DataFrame,
+    total: int | None,
+    caption: str | None,
+    *,
+    n: int,
+    height: int,
+    digits: int | str | None,
+) -> str:
+    uid = f"table3-explore-{uuid.uuid4().hex}"
+    fallback = table_html(
+        df.head(FALLBACK_ROWS), total, None, pages=False, page_size=10,
+        height=300, digits=digits,
+    )
+    note = (
+        f"<div style='font:{MONO};opacity:.65;margin:0 0 4px 0'>The explorer needs "
+        f"the notebook to run output scripts; the first {min(df.height, FALLBACK_ROWS):,} "
+        "rows show here instead.</div>"
+    )
+    cap = ""
+    if caption:
+        cap = (
+            f"<div style='font:{MONO};opacity:.85;margin:0 0 4px 0'>"
+            f"{_html.escape(caption)}</div>"
+        )
+    data = _json_for_script(payload(df, total, n, digits))
+    return (
+        f"<div id='{uid}' data-height='{height}' style='font:{MONO}'>"
+        + cap
+        + f"<div data-fallback>{note}{fallback}</div>"
+        + f"<script type='application/json'>{data}</script>"
+        + "</div>"
+        + f"<script>{EXPLORER_JS.replace('__ID__', uid)}</script>"
+    )

table3-0.4.0/src/table3/_explorer_js.py

@@ -0,0 +1,278 @@
+"""The script that turns a table3 explorer's JSON into a grid (docs/explorer.md §4).
+
+Every style is set inline by the script: CRAFT's republish drops <style>
+blocks. Only the rows in view are drawn, between two spacer rows, so 10,000
+rows scroll as fast as ten. Sorts and filters read the raw values; the grid
+shows the display text. __ID__ is the explorer's root element.
+"""
+
+EXPLORER_JS = r"""
+(function () {
+  var root = document.getElementById("__ID__");
+  if (!root || root.dataset.explorer) return;
+  root.dataset.explorer = "1";
+  var data = JSON.parse(root.querySelector("script[type='application/json']").textContent);
+  var fallback = root.querySelector("[data-fallback]");
+  if (fallback) fallback.style.display = "none";
+
+  var cols = data.columns, rows = data.rows, ncol = cols.length;
+  var ROW = 22, BUFFER = 10, CUT = 40;
+  var GREY = "rgba(127,127,127,.45)";
+  var SOLID = "background-color:var(--vscode-editor-background,var(--jp-layout-color0,Canvas));" +
+    "background-image:linear-gradient(hsl(var(--card)),hsl(var(--card)))";
+  var NUMERIC = { number: 1, date: 1 };
+
+  // Display text, and its lowercase for search, once per cell.
+  var text = [], lower = [];
+  rows.forEach(function (row, r) {
+    var t = [], l = [];
+    for (var c = 0; c < ncol; c++) {
+      var shown = data.shown[c] && data.shown[c][r];
+      var v = row[c];
+      var s = shown != null ? shown : v === null ? "null" : String(v);
+      t.push(s); l.push(s.toLowerCase());
+    }
+    text.push(t); lower.push(l);
+  });
+
+  function esc(s) {
+    return s.replace(/[&<>"']/g, function (ch) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[ch];
+    });
+  }
+
+  // Column widths in characters, from the widest text up to the cut.
+  var widths = cols.map(function (col, c) {
+    // Numbers and dates need room for their two filter boxes, from and to.
+    var w = Math.max(col.name.length + 2, col.type.length, NUMERIC[col.kind] ? 12 : 6);
+    for (var r = 0; r < rows.length && w < CUT; r++) w = Math.max(w, text[r][c].length);
+    return Math.min(w, CUT);
+  });
+  var numWidth = String(rows.length).length;
+
+  function cellStyle(c) {
+    return "box-sizing:border-box;width:calc(" + widths[c] + "ch + 20px);" +
+      "max-width:calc(" + widths[c] + "ch + 20px);padding:0 10px;height:" + ROW + "px;" +
+      "line-height:" + ROW + "px;white-space:pre;overflow:hidden;border:0;" +
+      "text-align:" + (NUMERIC[cols[c].kind] ? "right" : "left");
+  }
+  var NUM_STYLE = "box-sizing:border-box;width:calc(" + numWidth + "ch + 20px);padding:0 10px;" +
+    "height:" + ROW + "px;line-height:" + ROW + "px;text-align:right;opacity:.55;border:0;" +
+    "position:sticky;left:0;z-index:1;" + SOLID;
+
+  // Toolbar: search and the status line.
+  var bar = document.createElement("div");
+  bar.style.cssText = "display:flex;gap:12px;align-items:center;margin:0 0 4px 0;flex-wrap:wrap";
+  var search = document.createElement("input");
+  search.type = "search"; search.placeholder = "Search";
+  var INPUT = "font:inherit;color:inherit;background:transparent;border:1px solid " + GREY +
+    ";border-radius:4px;padding:1px 6px;box-sizing:border-box";
+  search.style.cssText = INPUT + ";width:16em";
+  var status = document.createElement("span");
+  status.dataset.status = "";
+  status.style.cssText = "opacity:.65";
+  bar.appendChild(search); bar.appendChild(status);
+  root.appendChild(bar);
+
+  var box = document.createElement("div");
+  box.dataset.grid = "";
+  box.style.cssText = "max-height:" + root.dataset.height + "px;overflow:auto;" +
+    "scrollbar-color:rgba(127,127,127,.5) transparent;border-top:1px solid " + GREY;
+  var table = document.createElement("table");
+  table.style.cssText = "border-collapse:separate;border-spacing:0;table-layout:fixed;font:inherit";
+  var thead = document.createElement("thead");
+  thead.style.cssText = "position:sticky;top:0;z-index:2;" + SOLID;
+  var tbody = document.createElement("tbody");
+  table.appendChild(thead); table.appendChild(tbody);
+  box.appendChild(table); root.appendChild(box);
+
+  // State: one sort column, a filter per column, the search text.
+  var sortCol = -1, sortDir = 0, filters = cols.map(function () { return null; });
+  var order = [], query = "";
+
+  // Header: names with sort arrows, types, filters.
+  var nameRow = document.createElement("tr"), typeRow = document.createElement("tr"),
+    filterRow = document.createElement("tr");
+  function corner(tr, html) {
+    var td = document.createElement("td");
+    td.style.cssText = NUM_STYLE + ";z-index:3";
+    td.innerHTML = html;
+    tr.appendChild(td);
+  }
+  corner(nameRow, ""); corner(typeRow, ""); corner(filterRow, "");
+  var arrows = [];
+  cols.forEach(function (col, c) {
+    var td = document.createElement("td");
+    td.style.cssText = cellStyle(c) + ";cursor:pointer;user-select:none";
+    td.title = "Sort by " + col.name;
+    var arrow = document.createElement("span");
+    arrow.style.cssText = "opacity:.55";
+    var name = document.createElement("b");
+    name.textContent = col.name;
+    if (NUMERIC[col.kind]) { td.appendChild(arrow); td.appendChild(name); }
+    else { td.appendChild(name); td.appendChild(arrow); }
+    td.onclick = function () {
+      if (sortCol !== c) { sortCol = c; sortDir = 1; }
+      else if (sortDir === 1) sortDir = -1;
+      else { sortCol = -1; sortDir = 0; }
+      apply();
+    };
+    arrows.push(arrow);
+    nameRow.appendChild(td);
+
+    var ttd = document.createElement("td");
+    ttd.style.cssText = cellStyle(c) + ";opacity:.55";
+    ttd.textContent = col.type;
+    typeRow.appendChild(ttd);
+
+    var ftd = document.createElement("td");
+    ftd.style.cssText = cellStyle(c) + ";height:auto;padding:2px 4px 4px 4px;border-bottom:1px solid " + GREY;
+    ftd.appendChild(filterControl(col, c));
+    filterRow.appendChild(ftd);
+  });
+  thead.appendChild(nameRow); thead.appendChild(typeRow); thead.appendChild(filterRow);
+
+  function filterControl(col, c) {
+    var timer = null;
+    function later(fn) { clearTimeout(timer); timer = setTimeout(fn, 150); }
+    if (col.kind === "choice" || col.kind === "bool") {
+      var sel = document.createElement("select");
+      sel.style.cssText = INPUT + ";width:100%;" + SOLID;
+      var values = col.kind === "bool" ? [true, false] : col.choices;
+      var opts = [["", "All"]].concat(values.map(function (v, i) { return ["v" + i, String(v)]; }))
+        .concat([["null", "null"]]);
+      opts.forEach(function (o) {
+        var op = document.createElement("option");
+        op.value = o[0]; op.textContent = o[1];
+        sel.appendChild(op);
+      });
+      sel.onchange = function () {
+        var v = sel.value;
+        filters[c] = v === "" ? null : v === "null" ? { is: null } : { is: values[+v.slice(1)] };
+        apply();
+      };
+      return sel;
+    }
+    if (NUMERIC[col.kind]) {
+      var wrap = document.createElement("div");
+      wrap.style.cssText = "display:flex;gap:2px";
+      var lo = document.createElement("input"), hi = document.createElement("input");
+      [lo, hi].forEach(function (inp, i) {
+        inp.placeholder = i ? "to" : "from";
+        inp.style.cssText = INPUT + ";width:50%;min-width:0";
+        inp.oninput = function () {
+          later(function () {
+            var a = lo.value.trim(), b = hi.value.trim();
+            if (col.kind === "number") {
+              a = a === "" ? null : parseFloat(a); b = b === "" ? null : parseFloat(b);
+              if (a !== null && isNaN(a)) a = null;
+              if (b !== null && isNaN(b)) b = null;
+            } else { a = a || null; b = b || null; }
+            filters[c] = a === null && b === null ? null : { from: a, to: b };
+            apply();
+          });
+        };
+        wrap.appendChild(inp);
+      });
+      return wrap;
+    }
+    var inp = document.createElement("input");
+    inp.placeholder = "contains";
+    inp.style.cssText = INPUT + ";width:100%";
+    inp.oninput = function () {
+      later(function () {
+        var q = inp.value.trim().toLowerCase();
+        filters[c] = q ? { has: q } : null;
+        apply();
+      });
+    };
+    return inp;
+  }
+
+  function passes(r) {
+    var row = rows[r];
+    for (var c = 0; c < ncol; c++) {
+      var f = filters[c];
+      if (!f) continue;
+      var v = row[c];
+      if ("is" in f) { if (v !== f.is) return false; continue; }
+      if ("has" in f) { if (lower[r][c].indexOf(f.has) < 0) return false; continue; }
+      if (v === null) return false;
+      // A date bound like "2008" or "2008-05" compares by its prefix.
+      var key = cols[c].kind === "date" ? String(v) : v;
+      if (f.from !== null && (cols[c].kind === "date" ? key.slice(0, f.from.length) < f.from : key < f.from)) return false;
+      if (f.to !== null && (cols[c].kind === "date" ? key.slice(0, f.to.length) > f.to : key > f.to)) return false;
+    }
+    if (query) {
+      var l = lower[r], hit = false;
+      for (var k = 0; k < ncol && !hit; k++) hit = l[k].indexOf(query) >= 0;
+      if (!hit) return false;
+    }
+    return true;
+  }
+
+  function compare(a, b) {
+    var x = rows[a][sortCol], y = rows[b][sortCol];
+    if (x === y) return a - b;
+    if (x === null) return 1;  // nulls last, whichever way
+    if (y === null) return -1;
+    var d = x < y ? -1 : x > y ? 1 : 0;
+    return d ? d * sortDir : a - b;
+  }
+
+  function apply() {
+    query = search.value.trim().toLowerCase();
+    order = [];
+    for (var r = 0; r < rows.length; r++) if (passes(r)) order.push(r);
+    if (sortCol >= 0) order.sort(compare);
+    arrows.forEach(function (a, c) {
+      a.textContent = c !== sortCol ? "" : sortDir > 0 ? " ▲ " : " ▼ ";
+    });
+    var label = order.length.toLocaleString("en-US") + " of " +
+      rows.length.toLocaleString("en-US") + " rows | " + ncol + " columns";
+    if (data.total === null || data.total > rows.length)
+      label += " (first " + rows.length.toLocaleString("en-US") + " of " +
+        (data.total === null ? "more" : data.total.toLocaleString("en-US")) + ")";
+    status.textContent = label;
+    box.scrollTop = 0;
+    render(true);
+  }
+
+  var drawn = "";
+  function render(force) {
+    var first = Math.max(0, Math.floor(box.scrollTop / ROW) - BUFFER);
+    var count = Math.ceil((box.clientHeight || +root.dataset.height) / ROW) + 2 * BUFFER;
+    var last = Math.min(order.length, first + count);
+    var key = first + ":" + last;
+    if (key === drawn && !force) return;
+    drawn = key;
+    var html = "<tr style='height:" + first * ROW + "px'></tr>";
+    for (var i = first; i < last; i++) {
+      var r = order[i], t = text[r];
+      html += "<tr data-row='" + (r + 1) + "' style='" + ((i % 2) ? "background:rgba(127,127,127,.08)" : "") + "'>";
+      html += "<td style='" + NUM_STYLE + "'>" + (r + 1) + "</td>";
+      for (var c = 0; c < ncol; c++) {
+        var s = t[c], cut = s.length > CUT;
+        html += "<td style='" + cellStyle(c) + "'" + (cut ? " title='" + esc(s) + "'" : "") + ">" +
+          esc(cut ? s.slice(0, CUT - 1) + "…" : s) + "</td>";
+      }
+      html += "</tr>";
+    }
+    html += "<tr style='height:" + (order.length - last) * ROW + "px'></tr>";
+    tbody.innerHTML = html;
+  }
+
+  var pending = false;
+  box.addEventListener("scroll", function () {
+    if (pending) return;
+    pending = true;
+    requestAnimationFrame(function () { pending = false; render(); });
+  });
+  var searchTimer = null;
+  search.oninput = function () {
+    clearTimeout(searchTimer);
+    searchTimer = setTimeout(apply, 150);
+  };
+  apply();
+})();
+"""

{table3-0.3.0 → table3-0.4.0/src/table3.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: table3
-Version: 0.3.0
+Version: 0.4.0
 Summary: Paged, theme-aware tables in notebook output: shared by tidy3, tidy3a and stats3
 Author: Rigoberto Leyva Salmeron
 License-Expression: MIT
@@ -19,6 +19,8 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ipython>=8.0; extra == "dev"
 Requires-Dist: pandas>=2.1.4; extra == "dev"
 Requires-Dist: pyarrow>=15.0; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: pytest-playwright>=0.5; extra == "browser"
 Dynamic: license-file
 
 # table3
@@ -51,7 +53,20 @@ full value on hover. Wide tables show as many columns as fit, with
 arrows to the rest. The table follows the notebook's light or dark theme in
 VS Code, JupyterLab and SolveIt.
 
-`show()` returns what it was given, so it can sit in the middle of a pipe.
+## Explore
+
+`table3.view(penguins)` opens a data explorer, as R's `View()` does: one
+grid of up to 10,000 rows with a search box, headers that sort on a click,
+and a filter under each column (from–to for numbers and dates, "contains"
+for text, a pick-list for columns of few values).
+
+```python
+table3.view(penguins);
+table3.view(penguins, n=50_000, height=600);  # more rows, a taller grid
+```
+
+`show()` and `view()` return what they were given, so they can sit in the
+middle of a pipe.
 As a cell's last line the notebook also prints that value; end the line with
 `;` to hide it.
 
@@ -72,6 +87,6 @@ def _repr_html_(self):
 ## More
 
 [docs/design.md](docs/design.md) records the design and what each package
-adds. table3 was first released as view3 0.1 and 0.2, where `show()` was
-`view()`, and its versions continue from them. The name `view` is kept for a
-data explorer, as R's `View()` opens one.
+adds, and [docs/explorer.md](docs/explorer.md) the explorer's. table3 was
+first released as view3 0.1 and 0.2, where `show()` was `view()`; its
+versions continue from them, and `view()` is now the explorer.

{table3-0.3.0 → table3-0.4.0}/src/table3.egg-info/SOURCES.txt

@@ -4,8 +4,11 @@ MANIFEST.in
 README.md
 pyproject.toml
 docs/design.md
+docs/explorer.md
 src/table3/__init__.py
 src/table3/__version__.py
+src/table3/_explore.py
+src/table3/_explorer_js.py
 src/table3/_format.py
 src/table3/_html.py
 src/table3/_pager.py
@@ -15,4 +18,6 @@ src/table3.egg-info/SOURCES.txt
 src/table3.egg-info/dependency_links.txt
 src/table3.egg-info/requires.txt
 src/table3.egg-info/top_level.txt
+tests/test_explore.py
+tests/test_explorer_browser.py
 tests/test_table3.py

{table3-0.3.0 → table3-0.4.0}/src/table3.egg-info/requires.txt

@@ -1,5 +1,8 @@
 polars>=1.39
 
+[browser]
+pytest-playwright>=0.5
+
 [dev]
 pytest>=7.0
 ipython>=8.0

table3-0.4.0/tests/test_explore.py

@@ -0,0 +1,123 @@
+import datetime as dt
+import json
+import re
+
+import polars as pl
+import pytest
+
+import table3
+from table3._explore import explorer_html, payload
+
+
+def _data(html: str) -> dict:
+    block = re.search(r"<script type='application/json'>(.*?)</script>", html, re.S).group(1)
+    return json.loads(block)
+
+
+@pytest.fixture
+def notebook(monkeypatch):
+    """Pretend to run in a notebook; collect what view() displays."""
+    import IPython
+    import IPython.display
+
+    shown = []
+    monkeypatch.setattr(IPython, "get_ipython", lambda: object())
+    monkeypatch.setattr(IPython.display, "display", lambda obj: shown.append(obj.data))
+    return shown
+
+
+MIXED = pl.DataFrame({
+    "species": ["Adelie", "Gentoo", None],
+    "mass": [3750, None, 4100],
+    "ratio": [0.000123456789, float("nan"), float("inf")],
+    "ok": [True, False, None],
+    "day": [dt.date(2008, 5, 1), None, dt.date(2009, 1, 2)],
+    "note": [f"note {i}" for i in range(3)],
+})
+
+
+def test_kinds_and_choices():
+    cols = payload(MIXED, 3, 10, None)["columns"]
+    assert [c["kind"] for c in cols] == ["choice", "number", "number", "bool", "date", "choice"]
+    assert cols[0]["choices"] == ["Adelie", "Gentoo"]
+    assert [c["type"] for c in cols[:3]] == ["str", "i64", "f64"]
+    many = pl.DataFrame({"s": [f"v{i}" for i in range(51)]})
+    assert payload(many, 51, 100, None)["columns"][0]["kind"] == "text"
+
+
+def test_raw_values_sort_and_shown_values_display():
+    data = payload(MIXED, 3, 10, None)
+    rows = data["rows"]
+    assert rows[0] == ["Adelie", 3750, 0.000123456789, True, "2008-05-01", "note 0"]
+    assert rows[1][1] is None and rows[1][2] is None  # null, and NaN as null
+    assert rows[2][2] == 1.7976931348623157e308  # inf sorts last
+    assert data["shown"][2] == ["0.000123", "NaN", "inf"]
+    assert data["shown"][0] is None and data["shown"][1] is None
+    assert payload(MIXED, 3, 10, 6)["shown"][2][0] == "0.000123457"
+
+
+def test_big_integers_keep_their_digits():
+    data = payload(pl.DataFrame({"id": [2**60 + 1, 5]}), 2, 10, None)
+    assert data["shown"][0] == [str(2**60 + 1), "5"]
+
+
+def test_script_end_in_a_value_is_escaped():
+    html = explorer_html(
+        pl.DataFrame({"s": ["</script><b>x"]}), 1, None, n=10, height=500, digits=None
+    )
+    assert "</script><b>x" not in html
+    assert _data(html)["rows"] == [["</script><b>x"]]
+
+
+def test_n_cut_and_counts():
+    df = pl.DataFrame({"x": range(2500)})
+    data = _data(explorer_html(df.head(1000), 2500, None, n=1000, height=500, digits=None))
+    assert len(data["rows"]) == 1000 and data["total"] == 2500 and data["n"] == 1000
+
+
+def test_fallback_without_scripts():
+    df = pl.DataFrame({"x": range(250)})
+    html = explorer_html(df, 250, "Frame", n=10_000, height=400, digits=None)
+    fallback = html.split("<div data-fallback>")[1].split("<script type='application/json'>")[0]
+    assert "the first 100 rows show here instead" in fallback
+    assert fallback.split("<tbody>")[1].count("<tr") == 100
+    assert "<script" not in fallback  # the fallback table needs no script
+    assert "data-height='400'" in html and ">Frame<" in html
+
+
+def test_view_shows_the_explorer_and_returns_data(notebook):
+    df = pl.DataFrame({"x": range(30)})
+    assert table3.view(df, n=20, height=300) is df
+    (html,) = notebook
+    assert "table3-explore-" in html and "data-height='300'" in html
+    data = _data(html)
+    assert len(data["rows"]) == 20 and data["total"] == 30
+
+
+def test_view_takes_lazy_pandas_and_hooks(notebook):
+    class Frame:
+        def __table3__(self, n):
+            return pl.DataFrame({"x": [1, 2]}), 2, "Frame (view)"
+
+    table3.view(pl.LazyFrame({"x": [1, 2]}))
+    table3.view(Frame())
+    pd = pytest.importorskip("pandas")
+    table3.view(pd.DataFrame({"x": [1.5, None]}))
+    lazy, hooked, pandas = notebook
+    assert _data(lazy)["total"] == 2
+    assert ">Frame (view)<" in hooked
+    assert _data(pandas)["shown"][0] == ["1.5", None]
+
+
+def test_view_outside_a_notebook_prints(capsys):
+    df = pl.DataFrame({"x": range(50)})
+    assert table3.view(df) is df
+    out = capsys.readouterr().out
+    assert out.startswith("shape: (50, 1)") and "… first 20 rows" in out
+
+
+def test_view_arguments_checked():
+    df = pl.DataFrame({"x": [1]})
+    for bad in ({"n": -1}, {"height": 0}, {"height": None}, {"digits": 0}):
+        with pytest.raises(ValueError):
+            table3.view(df, **bad)

table3-0.4.0/tests/test_explorer_browser.py

@@ -0,0 +1,169 @@
+"""The explorer's script, driven in headless Chromium (docs/explorer.md §6).
+
+Needs Playwright and its Chromium: pip install pytest-playwright, then
+python -m playwright install chromium. Skipped without them.
+"""
+
+import datetime as dt
+import random
+
+import polars as pl
+import pytest
+
+from table3._explore import explorer_html
+
+sync_api = pytest.importorskip("playwright.sync_api")
+
+
+@pytest.fixture(scope="module")
+def browser():
+    with sync_api.sync_playwright() as p:
+        try:
+            b = p.chromium.launch()
+        except Exception as e:  # no Chromium installed for Playwright
+            pytest.skip(f"no headless Chromium: {e}")
+        yield b
+        b.close()
+
+
+@pytest.fixture
+def explore(browser):
+    pages = []
+
+    def _open(df, total=None, **options):
+        page = browser.new_page()
+        pages.append(page)
+        html = explorer_html(
+            df, df.height if total is None else total, None,
+            n=options.get("n", 10_000), height=options.get("height", 400),
+            digits=options.get("digits"),
+        )
+        page.set_content(f"<!doctype html><html><body>{html}</body></html>")
+        return page
+
+    yield _open
+    for page in pages:
+        page.close()
+
+
+def _rows(page) -> list[int]:
+    return [int(r) for r in page.eval_on_selector_all(
+        "[data-grid] tbody tr[data-row]", "trs => trs.map(t => t.dataset.row)")]
+
+
+def _cells(page, row: int) -> list[str]:
+    return page.eval_on_selector_all(
+        f"tbody tr[data-row='{row}'] td", "tds => tds.map(t => t.textContent)")
+
+
+def _status(page) -> str:
+    return page.eval_on_selector("[data-status]", "s => s.textContent")
+
+
+def _wait_status(page, start: str) -> None:
+    page.wait_for_function(
+        "start => document.querySelector('[data-status]').textContent.startsWith(start)",
+        arg=start)
+
+
+def _header(page, name: str):
+    return page.locator(f"[data-grid] td[title='Sort by {name}']")
+
+
+random.seed(1)
+FRAME = pl.DataFrame({
+    "x": random.sample(range(300), 300),
+    "species": [["Adelie", "Gentoo", "Chinstrap", None][i % 4] for i in range(300)],
+    "note": [f"item {i}" for i in range(300)],
+    "day": [dt.date(2007 + i % 3, 1 + i % 12, 1) for i in range(300)],
+    "mass": [None if i % 10 == 0 else 3000.0 + i for i in range(300)],
+})
+
+
+def test_grid_replaces_the_fallback(explore):
+    page = explore(FRAME)
+    assert page.eval_on_selector("[data-fallback]", "f => f.style.display") == "none"
+    assert _status(page) == "300 of 300 rows | 5 columns"
+    assert _rows(page)[:3] == [1, 2, 3]
+    assert _cells(page, 1)[:3] == ["1", str(FRAME["x"][0]), "Adelie"]
+    assert _cells(page, 1)[5] == "null"  # mass of row 1
+
+
+def test_sort_cycles_and_keeps_row_numbers(explore):
+    page = explore(FRAME)
+    first = FRAME["x"].arg_min() + 1
+    _header(page, "x").click()
+    assert _rows(page)[0] == first
+    assert _cells(page, first)[1] == "0"
+    _header(page, "x").click()
+    assert _cells(page, _rows(page)[0])[1] == "299"
+    _header(page, "x").click()
+    assert _rows(page)[:3] == [1, 2, 3]
+
+
+def test_nulls_sort_last_both_ways(explore):
+    page = explore(FRAME)
+    for _ in range(2):
+        _header(page, "mass").click()
+        page.eval_on_selector("[data-grid]", "b => { b.scrollTop = b.scrollHeight }")
+        page.wait_for_timeout(100)
+        assert _cells(page, _rows(page)[-1])[5] == "null"
+
+
+def test_number_filter(explore):
+    page = explore(FRAME)
+    page.locator("input[placeholder='from']").first.fill("10")
+    page.locator("input[placeholder='to']").first.fill("19")
+    _wait_status(page, "10 of 300")
+    assert sorted(int(_cells(page, r)[1]) for r in _rows(page)) == list(range(10, 20))
+
+
+def test_choice_filter_and_null_choice(explore):
+    page = explore(FRAME)
+    select = page.locator("select").first
+    select.select_option(label="Gentoo")
+    _wait_status(page, "75 of 300")
+    select.select_option(label="null")
+    _wait_status(page, "75 of 300")
+    assert _cells(page, _rows(page)[0])[2] == "null"
+    select.select_option(label="All")
+    _wait_status(page, "300 of 300")
+
+
+def test_text_filter_search_and_date_prefix(explore):
+    page = explore(FRAME)
+    page.locator("[data-grid] input[placeholder='contains']").fill("item 2")  # 2, 20-29, 200-299
+    _wait_status(page, "111 of 300")
+    page.locator("input[type='search']").fill("adelie")
+    _wait_status(page, "28 of 300")
+    page.locator("[data-grid] input[placeholder='contains']").fill("")
+    _wait_status(page, "75 of 300")
+    page.locator("input[type='search']").fill("")
+    page.locator("input[placeholder='from']").nth(1).fill("2008")
+    page.locator("input[placeholder='to']").nth(1).fill("2008")
+    _wait_status(page, "100 of 300")
+
+
+def test_ten_thousand_rows_scroll_virtually(explore):
+    page = explore(pl.DataFrame({"x": range(10_000)}), total=52_341)
+    assert _status(page) == "10,000 of 10,000 rows | 1 columns (first 10,000 of 52,341)"
+    assert len(_rows(page)) < 60  # only the rows in view, plus a buffer
+    page.eval_on_selector("[data-grid]", "b => { b.scrollTop = b.scrollHeight }")
+    page.wait_for_timeout(100)
+    assert _rows(page)[-1] == 10_000
+    assert _cells(page, 10_000)[1] == "9999"
+
+
+def test_values_show_as_text_never_markup(explore):
+    page = explore(pl.DataFrame({"s": ["</script><b>bold</b>", "y" * 100]}))
+    assert _cells(page, 1)[1] == "</script><b>bold</b>"
+    assert page.locator("[data-grid] tbody b").count() == 0
+    cut = page.locator("[data-grid] tbody tr[data-row='2'] td").nth(1)
+    assert cut.text_content() == "y" * 39 + "…"
+    assert cut.get_attribute("title") == "y" * 100
+
+
+def test_digits_in_the_grid(explore):
+    df = pl.DataFrame({"r": [0.000123456789, 1.9015544041450778]})
+    assert _cells(explore(df), 1)[1] == "0.000123"
+    assert _cells(explore(df, digits=6), 1)[1] == "0.000123457"

table3-0.3.0/src/table3/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"