tablescope 0.2.2

A lazy table viewer with narwhals-backed query pushdown, for Marimo or Juptyer

tablescope

tablescope is a Marimo-oriented lazy table viewer. It accepts a dataframe-like object that Narwhals can normalize, keeps sort and aggregation work pushed down to the underlying engine, and renders a Solid + TanStack data grid via anywidget.

Install

pip install tablescope

Status

This is a first pass focused on:

• lazy row paging with backend pushdown
• arbitrary fraction jumps through the dataset
• per-column profile stats
• value counts for enum-like columns
• on-demand histograms for numeric and datetime columns
• derived columns from polars/narwhals expressions (e.g. col("a") + 1); on a polars source the full polars API is available, other backends get the narwhals subset
• keyboard navigation in the grid

Usage

import marimo as mo
import polars as pl
import tablescope

lf = pl.scan_parquet("data.parquet")
viewer = tablescope.view(lf, page_size=100)
viewer

CLI

To browse a file without writing any Python, run:

tablescope data.parquet

This starts a local server, prints its URL, and opens your browser. Supported file types: .parquet, .csv, .tsv, .arrow/.feather/.ipc, and .json/.ndjson/.jsonl. Files are read with polars, using lazy pushdown where the format allows it.

Over SSH, pass --no-open and use the printed URL (forward the port, e.g. ssh -L 6767:localhost:6767 host):

tablescope data.parquet --no-open
# tablescope: serving data.parquet at http://localhost:6767

Other flags: --port, --host, --page-size.

To stop the server, press Ctrl+C at the terminal, or click ⏻ Stop server in the page's top bar — the page then shows a "Server stopped" message.

Databricks

With the databricks extra installed (pip install tablescope[databricks]), point tablescope straight at a Unity Catalog table or a SQL query:

tablescope --source databricks:dev --table catalog.schema.table
tablescope --source databricks:dev --query "SELECT * FROM catalog.schema.t WHERE region = 'us'"

--source takes a <backend>:<profile> pair; only databricks is supported, and the profile is a Databricks CLI profile (databricks auth login -p dev). Use --source databricks alone for the default profile.

The table or query is opened with databricks-connect as a lazy Spark DataFrame, so tablescope's filters, sorts, and paging push down to Spark — the table is never fully materialized. Refine the view further from the UI.

Release

Use the justfile to build and validate the package artifacts before uploading them to PyPI.

just check-release
just publish

Frontend build

The frontend bundle is generated from frontend/src and inlined into src/tablescope/_frontend.py.

npm install
npm run build

Python workflow

just sync
just test