table3 0.3.0__py3-none-any.whl

table3/__init__.py

@@ -0,0 +1,153 @@
+"""Paged, theme-aware tables in notebook output.
+
+``table3.html(data)`` is a table of up to *n* rows shown ten at a time, with
+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.
+
+*data* is a polars DataFrame, LazyFrame or Series, a pandas DataFrame or
+Series, or any object with a ``__table3__`` method::
+
+    def __table3__(self, n: int) -> tuple[polars.DataFrame, int | None, str | None]:
+        # the first n rows, the whole row count (None if not counted),
+        # and a caption shown above the table (None for none)
+
+so a package's own frames show without table3 importing that package.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import polars as pl
+
+from table3.__version__ import __version__
+from table3._html import table_html
+
+__all__ = ["__version__", "html", "show"]
+
+
+def _from_pandas(df: Any) -> pl.DataFrame:
+    try:
+        return pl.from_pandas(df)
+    except Exception:  # no pyarrow, or a dtype polars can't take: show the text
+        return pl.DataFrame({str(c): df[c].astype(str).tolist() for c in df.columns})
+
+
+def _parts(data: Any, n: int) -> tuple[pl.DataFrame, int | None, str | None]:
+    if hasattr(type(data), "__table3__"):
+        return data.__table3__(n)
+    if isinstance(data, pl.Series):
+        data = data.to_frame()
+    if isinstance(data, pl.LazyFrame):
+        head, count = pl.collect_all([data.head(n), data.select(pl.len())])
+        return head, int(count.item()), None
+    if isinstance(data, pl.DataFrame):
+        return data.head(n), data.height, None
+    # pandas, duck-typed so table3 never imports it
+    if hasattr(data, "to_frame") and hasattr(data, "iloc") and not hasattr(data, "columns"):
+        data = data.to_frame()
+    if hasattr(data, "columns") and hasattr(data, "iloc"):
+        return _from_pandas(data.head(n)), len(data), None
+    raise TypeError(
+        f"table3 can't show a {type(data).__name__}: pass a polars or pandas "
+        "DataFrame or Series, or an object with a __table3__ method"
+    )
+
+
+def _positive_int(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
+def _check(n: Any, pages: Any, page_size: Any, height: Any, digits: Any) -> None:
+    if not isinstance(n, int) or isinstance(n, bool) or n < 0:
+        raise ValueError("table3: n must be a non-negative integer")
+    if not isinstance(pages, bool):
+        raise TypeError("table3: pages must be True or False")
+    if not _positive_int(page_size):
+        raise ValueError("table3: page_size must be a positive integer")
+    if height is not None and not _positive_int(height):
+        raise ValueError("table3: height must be a positive integer or None")
+    if digits is not None and digits != "full" and not _positive_int(digits):
+        raise ValueError('table3: digits must be a positive integer, "full", or None')
+
+
+def html(
+    data: Any,
+    *,
+    n: int = 1000,
+    pages: bool = True,
+    page_size: int = 10,
+    height: int | None = 300,
+    digits: int | str | None = None,
+    caption: str | None = None,
+) -> str:
+    """The table's HTML for the first *n* rows of *data*.
+
+    *page_size* rows show per page. ``pages=False``, or a notebook that
+    doesn't run output scripts, shows every row instead in a box *height*
+    pixels tall that scrolls; ``height=None`` grows it to fit.
+
+    Floats print as polars' text preview prints them (up to six decimals,
+    following ``pl.Config(float_precision=)``) unless *digits* says
+    otherwise: ``digits=6`` keeps six significant digits, as R's
+    ``signif()`` does, so small numbers keep their precision (0.000123457);
+    ``digits="full"`` shows every stored digit. *caption* replaces the one
+    ``__table3__`` gives.
+    """
+    _check(n, pages, page_size, height, digits)
+    df, total, own_caption = _parts(data, n)
+    return table_html(
+        df,
+        total,
+        own_caption if caption is None else caption,
+        pages=pages,
+        page_size=page_size,
+        height=height,
+        digits=digits,
+    )
+
+
+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.
+    full = {"fmt_float": "full"} if digits == "full" else {}
+    with pl.Config(tbl_rows=max(df.height, 1), tbl_hide_dataframe_shape=True, **full):
+        lines = [f"shape: ({'?' if total is None else total}, {df.width})", repr(df)]
+    if caption:
+        lines.insert(0, caption)
+    if total is None or total > df.height:
+        lines.append(f"… first {df.height:,} rows")
+    return "\n".join(lines)
+
+
+def show(
+    data: Any,
+    *,
+    n: int = 1000,
+    pages: bool = True,
+    page_size: int = 10,
+    height: int | None = 300,
+    digits: int | str | None = None,
+    caption: str | None = None,
+) -> Any:
+    """Show up to *n* rows of *data* in a paged table and return *data*.
+
+    Arguments as in ``html()``. Outside a notebook it prints the rows as
+    text. As a cell's last line the notebook also prints *data* itself; end
+    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:
+        print(_text(data, n, digits))
+    return data
+

table3/__version__.py

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

table3/_format.py

@@ -0,0 +1,81 @@
+"""Cell text: values, types and floats as polars' text preview prints them."""
+
+from __future__ import annotations
+
+import html as _html
+
+import polars as pl
+
+MAX_CHARS = 40  # longer values are cut, with the full value on hover
+
+
+def escape(v: object) -> str:
+    if v is None:
+        return "null"
+    return _html.escape(str(v))
+
+
+def cell(v: object) -> str:
+    text = "null" if v is None else str(v)
+    if len(text) <= MAX_CHARS:
+        return escape(v)
+    short = _html.escape(text[: MAX_CHARS - 1]) + "…"
+    return f"<span title='{_html.escape(text)}'>{short}</span>"
+
+
+def dtype_short(t: pl.DataType) -> str:
+    """Polars-style short dtype name ("i64"); falls back to str(t)."""
+    try:
+        from polars._plr import dtype_str_repr
+
+        return dtype_str_repr(t)
+    except Exception:
+        return str(t)
+
+
+def significant(v: float, digits: int) -> str:
+    """*v* to *digits* significant digits, as R's ``signif()`` keeps them.
+
+    Written as polars writes floats: "2.0" not "2", "1.5e-7" not "1.5e-07".
+    """
+    if v != v:
+        return "NaN"
+    if v in (float("inf"), float("-inf")):
+        return "inf" if v > 0 else "-inf"
+    text = format(v, f".{digits}g")
+    if "e" in text:
+        mantissa, exponent = text.split("e")
+        return f"{mantissa}e{int(exponent)}"
+    return text if "." in text else text + ".0"
+
+
+def float_text(s: pl.Series, digits: int | str | None = None) -> list[object]:
+    """Floats as polars' text preview prints them ("3.3", "1.2346e8").
+
+    Read off polars' own printer, so ``pl.Config(float_precision=)`` applies.
+    *digits* = k keeps k significant digits instead; "full" every stored digit.
+    """
+    if isinstance(digits, int):
+        return [None if v is None else significant(v, digits) for v in s.to_list()]
+    full = {"fmt_float": "full"} if digits == "full" else {}
+    with pl.Config(
+        tbl_formatting="NOTHING",
+        tbl_hide_column_names=True,
+        tbl_hide_column_data_types=True,
+        tbl_hide_dataframe_shape=True,
+        tbl_rows=-1,
+        tbl_width_chars=10_000,
+        **full,
+    ):
+        lines = [line.strip() for line in repr(s.to_frame()).splitlines()]
+    if len(lines) != len(s):
+        return s.to_list()
+    return [None if v is None else t for v, t in zip(s.to_list(), lines)]
+
+
+def display_rows(df: pl.DataFrame, digits: int | str | None = None) -> list[tuple]:
+    cols = [
+        float_text(s, digits) if s.dtype.is_float() else s.to_list()
+        for s in df.get_columns()
+    ]
+    return list(zip(*cols))

table3/_html.py

@@ -0,0 +1,125 @@
+"""The table's HTML: inline styles only.
+
+CRAFT republishes remote output through ``display_pub.publish``, which drops
+``<style>`` blocks, so every element carries its own style (as in tidy3's
+``display.py``). The pinned header needs a solid background: SolveIt's card
+colour (``--card``, an HSL triplet) is drawn as a gradient over a plain colour
+taken from VS Code, then JupyterLab, then the browser. Where ``--card`` is
+undefined the gradient drops out alone.
+
+Paging is a script over this table. Where output scripts don't run, the
+table stays a box of fixed height that scrolls down and sideways, with the
+column names and types pinned at the top.
+"""
+
+from __future__ import annotations
+
+import html as _html
+import uuid
+
+import polars as pl
+
+from table3._format import cell, display_rows, dtype_short, escape
+from table3._pager import PAGER_JS
+
+MONO = "12px ui-monospace,SFMono-Regular,Menlo,Consolas,monospace"
+RULE = "border-bottom:1px solid rgba(127,127,127,.45)"
+# The font is set once on the table: a cell's style repeats on up to
+# n x columns cells, and the font list is half its length.
+CELL = "font:inherit;padding:3px 10px;text-align:right;white-space:pre;border:0"
+HEAD_BG = (
+    "background-color:var(--vscode-editor-background,"
+    "var(--jp-layout-color0,Canvas));"
+    "background-image:linear-gradient(hsl(var(--card)),hsl(var(--card)))"
+)
+ZEBRA = "background:rgba(127,127,127,.08)"
+SCROLLBAR = "scrollbar-color:rgba(127,127,127,.5) transparent"
+
+
+def _plural(k: int) -> str:
+    return f"{k:,} row" + ("s" if k != 1 else "")
+
+
+def rows_label(shown: int, total: int | None) -> str:
+    """Footer for the scroll box: "35 rows", or how many of how many show."""
+    if total is not None and total <= shown:
+        return _plural(total)
+    of = "more" if total is None else f"{total:,}"
+    return f"showing first {shown:,} of {of} rows"
+
+
+def pages_label(shown: int, total: int | None) -> str:
+    """What the pager counts rows of: "344 rows", or the first 100 of more."""
+    if total is not None and total <= shown:
+        return _plural(shown)
+    of = "more" if total is None else f"{total:,}"
+    return f"{_plural(shown)} (first {shown:,} of {of})"
+
+
+def table_html(
+    df: pl.DataFrame,
+    total: int | None,
+    caption: str | None,
+    *,
+    pages: bool,
+    page_size: int,
+    height: int | None,
+    digits: int | str | None = None,
+) -> str:
+    """*df* is the first rows; *total* the whole row count, None if not counted."""
+
+    def _tr(cells: list[str], style: str, row_style: str = "") -> str:
+        tds = "".join(f"<td style='{style}'>{c}</td>" for c in cells)
+        return f"<tr style='{row_style}'>{tds}</tr>"
+
+    head = _tr([f"<b>{escape(c)}</b>" for c in df.columns], f"{CELL};{RULE}")
+    types = _tr(
+        [escape(dtype_short(t)) for t in df.dtypes], f"{CELL};opacity:.55;{RULE}"
+    )
+    body = [
+        _tr([cell(v) for v in row], CELL, ZEBRA if i % 2 else "")
+        for i, row in enumerate(display_rows(df, digits))
+    ]
+
+    shape = f"shape: ({'?' if total is None else total}, {df.width})"
+    box = f"overflow:auto;{SCROLLBAR}"
+    if height is not None:
+        box = f"max-height:{height}px;{box}"
+    small = f"font:{MONO};opacity:.65"
+    cap = ""
+    if caption:
+        cap = (
+            f"<div style='font:{MONO};opacity:.85;margin:0 0 2px 0'>"
+            f"{_html.escape(caption)}</div>"
+        )
+
+    root = "<div>"
+    pager = script = ""
+    if pages:
+        uid = f"table3-{uuid.uuid4().hex}"
+        label = _html.escape(pages_label(df.height, total))
+        root = f"<div id='{uid}' data-page-size='{page_size}' data-label='{label}'>"
+        pager = (
+            f"<div data-pager style='font:{MONO};margin:4px 0 0 0;display:none'>"
+            "</div>"
+        )
+        script = f"<script>{PAGER_JS.replace('__ID__', uid)}</script>"
+    return (
+        root
+        + cap
+        + f"<small style='{small}'>{shape}</small>"
+        f"<div data-box style='{box}'>"
+        "<table style='border-collapse:separate;border-spacing:0;margin:2px 0;"
+        f"font:{MONO}'>"
+        f"<thead style='position:sticky;top:0;z-index:1;{HEAD_BG}'>"
+        + head
+        + types
+        + "</thead><tbody>"
+        + "".join(body)
+        + "</tbody></table></div>"
+        f"<small data-foot style='{small}'>"
+        f"{rows_label(df.height, total)}</small>"
+        + pager
+        + "</div>"
+        + script
+    )

table3/_pager.py

@@ -0,0 +1,106 @@
+"""The script that pages a table3 table in place."""
+
+# Column widths are measured once over all rows, so a column page keeps its
+# columns whichever row page is shown. __ID__ is the table's root element.
+PAGER_JS = """
+(function () {
+  var root = document.getElementById("__ID__");
+  if (!root || root.dataset.paged) return;
+  root.dataset.paged = "1";
+  var box = root.querySelector("[data-box]");
+  var table = box.querySelector("table");
+  var head = [].slice.call(table.tHead.rows);
+  var body = [].slice.call(table.tBodies[0].rows);
+  var foot = root.querySelector("[data-foot]");
+  var pager = root.querySelector("[data-pager]");
+  var size = +root.dataset.pageSize, label = root.dataset.label;
+  var widths = [].map.call(head[0].cells, function (c) { return c.offsetWidth; });
+  var page = 0, cpage = 0, groups = [], seenWidth = -1;
+  var BTN = "font:inherit;color:inherit;background:none;cursor:pointer;" +
+    "border:1px solid transparent;border-radius:4px;padding:1px 7px;margin:0 1px";
+
+  function group() {
+    var avail = box.clientWidth || Infinity, cur = [], w = 0;
+    seenWidth = box.clientWidth;
+    groups = [];
+    widths.forEach(function (x, j) {
+      if (cur.length && w + x > avail) { groups.push(cur); cur = []; w = 0; }
+      cur.push(j); w += x;
+    });
+    groups.push(cur);
+    cpage = Math.min(cpage, groups.length - 1);
+  }
+
+  function button(text, on, go, current) {
+    var b = document.createElement("button");
+    b.type = "button"; b.textContent = text; b.style.cssText = BTN;
+    if (current) b.style.borderColor = "rgba(127,127,127,.6)";
+    if (!on) { b.disabled = true; b.style.opacity = ".35"; b.style.cursor = "default"; }
+    else b.onclick = go;
+    pager.appendChild(b);
+  }
+
+  function gap(text) {
+    var s = document.createElement("span");
+    s.textContent = text || "…"; s.style.cssText = "opacity:.55;padding:0 4px";
+    pager.appendChild(s);
+  }
+
+  function pageList(n, cur) {
+    if (n <= 7) return Array.from({ length: n }, function (_, i) { return i; });
+    var keep = [0, n - 1, cur - 1, cur, cur + 1].filter(function (i) {
+      return i >= 0 && i < n;
+    });
+    return keep.filter(function (v, i) { return keep.indexOf(v) === i; })
+      .sort(function (a, b) { return a - b; });
+  }
+
+  function render() {
+    var npages = Math.max(1, Math.ceil(body.length / size));
+    page = Math.min(page, npages - 1);
+    var lo = page * size, hi = Math.min(lo + size, body.length);
+    var cols = groups[cpage], keep = {};
+    cols.forEach(function (j) { keep[j] = 1; });
+    body.forEach(function (tr, i) {
+      var on = i >= lo && i < hi;
+      tr.style.display = on ? "" : "none";
+      if (on) tr.style.background = (i - lo) % 2 ? "rgba(127,127,127,.08)" : "";
+    });
+    head.concat(body.slice(lo, hi)).forEach(function (tr) {
+      [].forEach.call(tr.cells, function (td, j) { td.style.display = keep[j] ? "" : "none"; });
+    });
+
+    var text = body.length > size ? (lo + 1) + "–" + hi + " of " + label : label;
+    if (groups.length > 1)
+      text += " | " + (cols[0] + 1) + "–" + (cols[cols.length - 1] + 1) +
+        " of " + widths.length + " columns";
+    foot.textContent = text;
+
+    pager.textContent = "";
+    if (groups.length > 1) {
+      button("◂ columns", cpage > 0, function () { cpage--; render(); });
+      button("columns ▸", cpage < groups.length - 1, function () { cpage++; render(); });
+      if (npages > 1) gap("|");
+    }
+    if (npages > 1) {
+      button("Previous", page > 0, function () { page--; render(); });
+      var last = -1;
+      pageList(npages, page).forEach(function (p) {
+        if (p > last + 1) gap();
+        button(String(p + 1), p !== page, function () { page = p; render(); }, p === page);
+        last = p;
+      });
+      button("Next", page < npages - 1, function () { page++; render(); });
+    }
+    pager.style.display = pager.childNodes.length ? "" : "none";
+  }
+
+  group();
+  box.style.maxHeight = "none";
+  render();
+  if (window.ResizeObserver)
+    new ResizeObserver(function () {
+      if (box.clientWidth !== seenWidth) { group(); render(); }
+    }).observe(box);
+})();
+"""

table3-0.3.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: table3
+Version: 0.3.0
+Summary: Paged, theme-aware tables in notebook output: shared by tidy3, tidy3a and stats3
+Author: Rigoberto Leyva Salmeron
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rleyvasal/table3
+Keywords: notebooks,jupyter,polars,tables,viewer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: polars>=1.39
+Provides-Extra: dev
+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"
+Dynamic: license-file
+
+# table3
+
+Paged, theme-aware tables in notebook output, the way R notebooks print a
+data frame. It is the shared table display of
+[tidy3](https://github.com/rleyvasal/tidy3),
+[tidy3a](https://github.com/rleyvasal/tidy3a) and
+[stats3](https://github.com/rleyvasal/stats3), released on its own so each
+can show tables without depending on the others. It needs only polars.
+
+```python
+import polars as pl
+import table3
+
+penguins = pl.read_csv(
+    "https://raw.githubusercontent.com/allisonhorst/palmerpenguins/main/inst/extdata/penguins.csv",
+    null_values="NA",
+)
+table3.show(penguins);                           # ten rows a page, every row up to n=1000
+table3.show(penguins, page_size=25);             # bigger pages
+table3.show(penguins, pages=False, height=300);  # one box that scrolls
+table3.show(penguins, digits=4);                 # four significant digits
+```
+
+Column names and types sit in the header, missing values show as `null`,
+floats print as polars' text preview prints them (or to `digits=`
+significant digits, or `digits="full"`), and long values are cut with the
+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.
+As a cell's last line the notebook also prints that value; end the line with
+`;` to hide it.
+
+## Your own frames
+
+A package makes its frames print this way by returning `table3.html(self)`
+from `_repr_html_`. An object with a `__table3__` method shows without table3
+importing its package:
+
+```python
+def __table3__(self, n):
+    return first_n_rows_as_polars, total_rows_or_None, "caption or None"
+
+def _repr_html_(self):
+    return table3.html(self, n=100)
+```
+
+## 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.

table3-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+table3/__init__.py,sha256=HuQnXQ5FKPEFe_JpbeCs0II-4FpqRdutcolaGZZMxAo,5814
+table3/__version__.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,22
+table3/_format.py,sha256=vQ8w6FZHZyS-Z3cuKT10OPnws7Xlf54yv9rIgOHSTFw,2536
+table3/_html.py,sha256=aCDUmSGAu85rfG6BbTbmrhqwgaI2KuWlVp3QfdKnr3s,4406
+table3/_pager.py,sha256=P2FGXTxgclpFBySTqgKeBUFZSbGK99BnosTsgMlKPLc,4107
+table3/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+table3-0.3.0.dist-info/licenses/LICENSE,sha256=sjpfmtLhkcM74AL9VMpifL0CRdeiMoLyUO9OKZ_hg9I,1082
+table3-0.3.0.dist-info/METADATA,sha256=s8TqvQ_jfpaNBpttexj3HOyWGqKO6MRU72p7eNOUYRs,2873
+table3-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+table3-0.3.0.dist-info/top_level.txt,sha256=UrtGfSKMg2UGL__F7_pu_MAGsOEj1KtBbmUs2NSgIjY,7
+table3-0.3.0.dist-info/RECORD,,

table3-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

table3-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rigoberto Leyva Salmeron 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

table3-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+table3