table3 0.3.0__tar.gz

table3-0.3.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.3.0 — 2026-11-02
+
+table3 is view3 renamed: the table is how a frame prints in a notebook, as
+R's `print()`, and `view` is kept for a data explorer, as R's `View()`. Its
+versions continue view3's, whose entries are below; this is table3's first
+release on PyPI.
+
+### Changed from view3 0.2.0
+
+- `view3.view()` is `table3.show()`, and there is no `view()`. Nothing used
+  `view()` yet.
+- The hook is `__table3__`, not `__view3__`.
+- The footer no longer names `n=`: "1–10 of 100 rows (first 100 of 344)".
+  A package showing the table as its frames' notebook display sets *n*
+  itself.
+
+## view3 0.2.0 — 2026-11-02
+
+### Added
+
+- `digits=` chooses how floats print. `digits=6` keeps six significant
+  digits, as R's `signif()` does, so small numbers keep their precision
+  (`0.000123457`, `1.5e-7`) where the default shows `0.000123`;
+  `digits="full"` shows every stored digit. The default, `None`, prints as
+  polars' text preview does, as before.
+
+## view3 0.1.0 — 2026-11-02
+
+Phase 1 of [the design](docs/design.md).
+
+### Added
+
+- `view3.view(data)` shows up to `n` rows in a paged table and returns
+  `data`; `view3.html(data)` returns the HTML. Ten rows a page
+  (`page_size=`), column pages for wide tables, and a scroll box with pinned
+  names and types where output scripts don't run or with `pages=False`.
+- polars DataFrames, LazyFrames and Series, pandas DataFrames and Series, and
+  any object with a `__view3__(n)` method.

table3-0.3.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+recursive-include docs *.md
+recursive-include tests *.py

table3-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/docs/design.md

@@ -0,0 +1,123 @@
+# A shared package for notebook tables
+
+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).
+
+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
+names, types and the table. R notebooks print every data frame as a paged
+table (R Markdown's `df_print: paged`, `rmarkdown::paged_table()`): ten rows
+a page, up to `max.print` rows to page through. table3 is that table, with
+tidy3's formatting, for any package's `_repr_html_`. It is its own package
+because tidy3, tidy3a and stats3 all produce tables to look at, and none of
+them should depend on another to do it.
+
+The name `view` is kept for a data explorer: in R, `View(df)` opens
+RStudio's viewer, where you search, sort and filter as in a spreadsheet.
+That is not this table, so the package is table3 (what it makes), its
+functions `html()` and `show()` (R's `print()`), and a later `table3.view()`
+can be the explorer. view3 0.1 and 0.2 called `show()` `view()`; nothing
+used it yet, so it is gone rather than deprecated.
+
+## 1. Precedents
+
+- R splits printing from the table packages: tibble prints through
+  [pillar](https://pillar.r-lib.org), which other packages share, and
+  RStudio's paged table lives in rmarkdown (`paged_table()`), not dplyr.
+- tidy3syntax already shares notebook syntax among tidy3, tidy3a, plot3 and
+  stats3 the same way: one small package, a version range in each.
+- tidy3a reaches tidy3 through `TidyArray.__tidy__` and never imports it.
+  table3 reaches its callers' objects through `__table3__` the same way.
+
+## 2. What it shows
+
+- A table of the first *n* rows (default 1,000), names and types in the
+  header, as tidy3's notebook table prints them; `null` for missing values;
+  floats as polars' text preview prints them (`3.3`, `1.2346e8`), following
+  `pl.Config(float_precision=)`, unless `digits=` asks for significant
+  digits (§2.1); values longer than 40 characters cut with
+  "…", the full value on hover.
+- Ten rows a page (`page_size=`), Previous / page numbers / Next, and as many
+  columns as fit the cell with `◂ columns` / `columns ▸` for the rest. Column
+  groups are measured once over all *n* rows, so they don't shift between
+  pages, and they are regrouped when the cell's width changes.
+- The footer counts rows and columns ("21–30 of 344 rows | 10–12 of 12
+  columns") and says when *n* cut the rows ("1–10 of 100 rows (first 100 of
+  52,341)").
+
+### 2.1 Float digits
+
+Polars' preview keeps up to six decimal places, so `0.000123456789` shows as
+`0.000123`, and its `float_precision` counts decimal places, which turns
+small numbers into `0.00`. `digits=k` instead keeps *k* significant digits,
+as R's `signif()` and tibble's `pillar.sigfig` count them: `0.000123457`,
+`1.5e-7`, `1.23457e8` for `digits=6`, written as polars writes floats (`2.0`,
+an exponent without `+` or a leading zero). `digits="full"` is polars'
+`fmt_float="full"`: every stored digit, float noise included. Text output
+outside a notebook takes `"full"` but not *k*, since polars prints no
+significant digits and converting the column would print its type as `str`.
+
+## 3. Where it runs
+
+- **Inline styles only.** CRAFT republishes remote output through
+  `display_pub.publish`, which drops `<style>` blocks; tidy3's `display.py`
+  is inline-only for the same reason.
+- **Theme.** Text inherits the notebook's colour; rules, stripes and
+  scrollbars are translucent grey, which reads on dark and light. The pinned
+  header needs a solid background: SolveIt's `--card` (an HSL triplet, so
+  `hsl(var(--card))`) drawn as a gradient over `var(--vscode-editor-background,
+  var(--jp-layout-color0, Canvas))`. An undefined `--card` makes only the
+  gradient invalid, so the colour under it shows. Checked in SolveIt's dark
+  theme on 2026-11-02 (card `rgb(23,23,23)`).
+- **Paging is a script over a plain table.** SolveIt runs output scripts and
+  inline handlers, and runs them again when a dialog is reloaded (probed
+  2026-11-02); VS Code and trusted Jupyter notebooks run them too. Where
+  scripts don't run, the table stays a box `height` pixels tall (default
+  300) that scrolls both ways under a pinned header. `pages=False` asks for
+  that box everywhere.
+- **Size.** Every cell carries its style, about 100 bytes a cell: 1,000 rows
+  of 12 columns add about 1.2 MB to a saved notebook. The font is set once
+  on the table to halve that.
+
+## 4. Interface
+
+```python
+table3.show(data, *, n=1000, pages=True, page_size=10, height=300, digits=None, caption=None)  # shows, returns data
+table3.html(data, *, n=1000, pages=True, page_size=10, height=300, digits=None, caption=None)  # the HTML
+```
+
+*data* is a polars DataFrame, LazyFrame or Series (a LazyFrame's first *n*
+rows and row count are collected together), a pandas DataFrame or Series
+(read without importing pandas), or any object with
+
+```python
+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."""
+```
+
+Outside a notebook `show()` prints the rows as text. As a cell's last line
+the notebook also prints what `show()` returns; `;` hides it. A package
+prints its frames as this table by returning `table3.html(self, n=…)` from
+`_repr_html_`.
+
+## 5. Each package's part
+
+| Package | Change | Dependency |
+|---|---|---|
+| tidy3 | `TidyFrame._repr_html_` returns `table3.html(self, n=preview_max, page_size=preview_rows, digits=preview_digits)` from `options()`; `TidyFrame.__table3__` from `_preview_parts` (respects `preview_count`), caption `TidyFrame (preview groups=[…])`. No verb: every frame in a cell prints this way | `table3>=0.3,<0.4` |
+| stats3 | Result tables are polars, so `table3.show(table)` works as is; its own result objects may return `table3.html` from `_repr_html_` | optional at first |
+| tidy3a | `TidyArray.__table3__` through `as_table` | extra `tidy3a[view]` (tidy3a has no polars) |
+| plot3, tidy3syntax | none | none |
+
+None of them exports `show` or `view` bare, so `from … import *` in any order
+leaves the names alone.
+
+## 6. Phases
+
+1. view3 0.1.0: the prototype's code without tidy3, tests, CI, release.
+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.

table3-0.3.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "table3"
+dynamic = ["version"]
+description = "Paged, theme-aware tables in notebook output: shared by tidy3, tidy3a and stats3"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Rigoberto Leyva Salmeron" }]
+keywords = ["notebooks", "jupyter", "polars", "tables", "viewer"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: IPython",
+  "Framework :: Jupyter",
+  "Programming Language :: Python :: 3",
+]
+# Polars formats the values; pandas frames are read without importing pandas.
+# IPython is optional and imported only to show a table in a notebook.
+dependencies = [
+  "polars>=1.39",
+]
+
+[project.optional-dependencies]
+# pandas and pyarrow: the pandas input tests.
+dev = ["pytest>=7.0", "ipython>=8.0", "pandas>=2.1.4", "pyarrow>=15.0"]
+
+[project.urls]
+Homepage = "https://github.com/rleyvasal/table3"
+
+[tool.setuptools.dynamic]
+version = { attr = "table3.__version__.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+table3 = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

table3-0.3.0/setup.cfg

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

table3-0.3.0/src/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-0.3.0/src/table3/__version__.py

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

table3-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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/src/table3.egg-info/PKG-INFO

@@ -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/src/table3.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+docs/design.md
+src/table3/__init__.py
+src/table3/__version__.py
+src/table3/_format.py
+src/table3/_html.py
+src/table3/_pager.py
+src/table3/py.typed
+src/table3.egg-info/PKG-INFO
+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_table3.py

table3-0.3.0/src/table3.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

table3-0.3.0/src/table3.egg-info/requires.txt

@@ -0,0 +1,7 @@
+polars>=1.39
+
+[dev]
+pytest>=7.0
+ipython>=8.0
+pandas>=2.1.4
+pyarrow>=15.0

table3-0.3.0/src/table3.egg-info/top_level.txt

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

table3-0.3.0/tests/test_table3.py

@@ -0,0 +1,206 @@
+import re
+
+import polars as pl
+import pytest
+
+import table3
+
+
+def _body_rows(html: str) -> int:
+    return html.split("<tbody>")[1].count("<tr")
+
+
+@pytest.fixture
+def islands():
+    # 29 distinct values, like a distinct() over one column
+    return pl.DataFrame({"island": [f"island {i:02d}" for i in range(29)]})
+
+
+class Frame:
+    """A package's own frame: shown through __table3__ without table3 knowing it."""
+
+    def __init__(self, df, counted=True):
+        self.df, self.counted, self.asked = df, counted, []
+
+    def __table3__(self, n):
+        self.asked.append(n)
+        return self.df.head(n), self.df.height if self.counted else None, "Frame (view)"
+
+
+def test_all_rows_shown(islands):
+    html = table3.html(islands)
+    assert _body_rows(html) == 29
+    assert "island 28" in html
+    assert "max-height:300px" in html
+    assert ">29 rows<" in html
+
+
+def test_header_and_types_pinned(islands):
+    thead = table3.html(islands).split("<thead")[1].split("</thead>")[0]
+    assert "position:sticky;top:0" in thead
+    assert "<b>island</b>" in thead and ">str<" in thead
+
+
+def test_row_limit_labelled():
+    html = table3.html(pl.DataFrame({"x": range(2500)}), n=1000)
+    assert _body_rows(html) == 1000
+    assert "showing first 1,000 of 2,500 rows<" in html
+    assert "data-label='1,000 rows (first 1,000 of 2,500)'" in html
+    assert "shape: (2500, 1)" in html
+
+
+def test_lazy_frame_counted():
+    html = table3.html(pl.LazyFrame({"x": range(50)}), n=10)
+    assert _body_rows(html) == 10 and "shape: (50, 1)" in html
+
+
+def test_table3_hook_gives_rows_count_and_caption():
+    frame = Frame(pl.DataFrame({"x": range(50)}), counted=False)
+    html = table3.html(frame, n=10)
+    assert frame.asked == [10]
+    assert ">Frame (view)<" in html
+    assert "shape: (?, 1)" in html
+    assert "showing first 10 of more rows" in html
+    assert "(first 10 of more)" in html
+    assert ">Mine<" in table3.html(frame, caption="Mine")
+
+
+def test_nulls_mixed_types_and_long_strings():
+    df = pl.DataFrame(
+        {"n": [1, None, 3], "s": ["short", None, "<b>" + "y" * 100], "d": [1.5, 2.0, None]}
+    )
+    html = table3.html(df)
+    assert html.split("<tbody>")[1].count(">null<") == 3
+    assert ">i64<" in html and ">f64<" in html
+    assert "<b>yyy" not in html  # escaped, never live markup
+    assert "title='&lt;b&gt;" + "y" * 100 + "'" in html
+    assert re.search(r"&lt;b&gt;y{36}…</span>", html)
+
+
+def test_floats_as_text_preview():
+    df = pl.DataFrame(
+        {"x": [3.3000000000000003, 1.9015544041450778, None, 123456789.123, 2.0],
+         "y": [1, 2, 3, 4, 5]}
+    )
+    body = table3.html(df).split("<tbody>")[1]
+    cells = re.findall(r"<td style='[^']*'>([^<]*)</td>", body)
+    assert cells[0::2] == ["3.3", "1.901554", "null", "1.2346e8", "2.0"]
+    assert cells[1::2] == ["1", "2", "3", "4", "5"]
+    with pl.Config(float_precision=2):
+        assert ">1.90<" in table3.html(df)
+
+
+def _float_cells(html: str) -> list[str]:
+    return re.findall(r"<td style='[^']*'>([^<]*)</td>", html.split("<tbody>")[1])
+
+
+SMALL = pl.DataFrame(
+    {"x": [0.000123456789, 1.5e-7, 2.5e-12, 1.9015544041450778, 123456789.123,
+           2.0, -0.5, float("nan"), float("inf"), None]}
+)
+
+
+def test_digits_significant_keeps_small_numbers():
+    assert _float_cells(table3.html(SMALL, digits=6)) == [
+        "0.000123457", "1.5e-7", "2.5e-12", "1.90155", "1.23457e8",
+        "2.0", "-0.5", "NaN", "inf", "null",
+    ]
+    assert _float_cells(table3.html(SMALL, digits=2))[:4] == [
+        "0.00012", "1.5e-7", "2.5e-12", "1.9",
+    ]
+
+
+def test_digits_default_and_full():
+    default = _float_cells(table3.html(SMALL))
+    assert default[:2] == ["0.000123", "1.5000e-7"]
+    full = _float_cells(table3.html(SMALL, digits="full"))
+    assert full[:5] == [
+        "0.000123456789", "0.00000015", "0.0000000000025", "1.9015544041450778",
+        "123456789.123",
+    ]
+
+
+def test_digits_leave_other_columns_and_float32():
+    df = pl.DataFrame({"i": [123456789], "s": ["0.123456789"],
+                       "f": pl.Series([0.1], dtype=pl.Float32)})
+    assert _float_cells(table3.html(df, digits=3)) == ["123456789", "0.123456789", "0.1"]
+
+
+def test_digits_in_text_output(capsys):
+    table3.show(SMALL.head(1), digits="full")
+    assert "0.000123456789" in capsys.readouterr().out
+    table3.show(SMALL.head(1), digits=3)  # polars prints its own floats
+    assert "f64" in capsys.readouterr().out
+
+
+def test_empty():
+    html = table3.html(pl.DataFrame({"x": []}, schema={"x": pl.Int64}))
+    assert _body_rows(html) == 0
+    assert "<b>x</b>" in html and ">0 rows<" in html
+
+
+def test_wide_table_keeps_every_column():
+    html = table3.html(pl.DataFrame({f"c{i}": [i] for i in range(45)}))
+    assert [i for i in range(45) if f"<b>c{i}</b>" not in html] == []
+    assert "…</td>" not in html
+
+
+def test_series_and_pandas():
+    assert "<b>x</b>" in table3.html(pl.Series("x", [1, 2]))
+    pd = pytest.importorskip("pandas")
+    df = pd.DataFrame({"a": [1.5, None], "b": ["p", "q"]})
+    html = table3.html(df)
+    assert "<b>a</b>" in html and ">1.5<" in html and ">null<" in html
+    assert "<b>a</b>" in table3.html(df["a"])
+
+
+def test_unknown_data_refused():
+    with pytest.raises(TypeError, match="can't show a list"):
+        table3.html([1, 2])
+
+
+def test_pages_script_targets_its_table(islands):
+    html = table3.html(islands, page_size=5)
+    uid = re.search(r"<div id='(table3-[0-9a-f]{32})'", html).group(1)
+    assert f'document.getElementById("{uid}")' in html
+    assert "data-page-size='5'" in html and "data-label='29 rows'" in html
+    assert html.count("<script>") == 1 and html.endswith("</script>")
+    assert uid not in table3.html(islands)  # each output pages its own table
+
+
+def test_pages_off_is_the_scroll_box(islands):
+    html = table3.html(islands, pages=False)
+    assert "<script" not in html and "data-pager" not in html
+    assert "max-height:300px" in html
+
+
+def test_show_returns_data_unchanged(capsys):
+    df = pl.DataFrame({"x": [3, 1, 2], "y": ["a", "b", None]})
+    before = df.clone()
+    assert table3.show(df) is df
+    assert df.equals(before)
+    out = capsys.readouterr().out  # text outside a notebook
+    assert "shape: (3, 2)" in out and "│ 3" in out
+
+
+def test_show_text_labels_the_limit(capsys):
+    frame = Frame(pl.DataFrame({"x": range(50)}))
+    assert table3.show(frame, n=5) is frame
+    out = capsys.readouterr().out
+    assert out.startswith("Frame (view)\nshape: (50, 1)")
+    assert "… first 5 rows" in out
+
+
+def test_arguments_checked():
+    with pytest.raises(ValueError):
+        table3.html(pl.DataFrame({"x": [1]}), n=-1)
+    with pytest.raises(ValueError):
+        table3.show(pl.DataFrame({"x": [1]}), page_size=0)
+    with pytest.raises(ValueError):
+        table3.show(pl.DataFrame({"x": [1]}), height=0)
+    with pytest.raises(TypeError):
+        table3.show(pl.DataFrame({"x": [1]}), pages="yes")
+    for bad in (0, True, 2.5, "all"):
+        with pytest.raises(ValueError, match="digits"):
+            table3.html(pl.DataFrame({"x": [1.0]}), digits=bad)
+