Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Use datui from Python

datui.view() opens the terminal UI on a Polars frame, a file or a URL, and can hand the final view back as a LazyFrame.

pip install datui

The package on PyPI installs the datui command and the datui module. It needs Python 3.10 or later. Python API lists every option, the return value and the errors.

View a frame

import polars as pl
import datui

url = "https://vincentarelbundock.github.io/Rdatasets/csv/palmerpenguins/penguins.csv"
penguins = pl.scan_csv(url)
datui.view(penguins)
datui.view(penguins.collect())

A LazyFrame passes its plan, not its data, and stays lazy: datui reads the rows it needs to show. Sorting, aggregation and other operations may still scan the whole input. A DataFrame works too. q closes datui and returns to Python.

View a path

view also takes a path, a URL or a list of paths, with the command line’s options as keywords:

import polars as pl
import datui

pl.DataFrame({"month": [1], "sales": [10.5]}).write_parquet("jan.parquet")
pl.DataFrame({"month": [2], "sales": [12.0]}).write_parquet("feb.parquet")
datui.view(["jan.parquet", "feb.parquet"])

with open("data.csv", "w") as f:
    f.write("1;north\n2;south\n")
datui.view("data.csv", delimiter=";", no_header=True)

Remote paths read as they do on the command line:

import datui

datui.view("s3://noaa-ghcn-pds/parquet/by_year/YEAR=2024/ELEMENT=TMAX/")
datui.view("https://vincentarelbundock.github.io/Rdatasets/csv/palmerpenguins/penguins.csv")

The keywords are named after the flags and config keys: delimiter for --delimiter, row_numbers for display.row_numbers, and config for any key, the way -c sets it. Pass them as keywords or as a datui.DatuiOptions. datui.OPTION_NAMES lists them, and Python API gives each one’s type and flag. For a frame, only display options apply.

Return the current view

import polars as pl
import datui

url = "https://vincentarelbundock.github.io/Rdatasets/csv/palmerpenguins/penguins.csv"
result = datui.view(pl.scan_csv(url), capture=True)
if result is not None:
    print(result.collect())

Run the species summary from the quick start and press q. result collects to the three rows, with Gentoo first at 5076.01626 and 124 penguins. Collecting reads the CSV from the web again.

With capture=True, a normal quit returns the final view as a LazyFrame, even for DataFrame input: the applied query, filters, sort, drill-down, reshape and column order, over all matching rows. It returns None if no dataset was open at quit.

Collecting runs the returned plan again, with Python’s own Polars; the rows datui showed are not cached. If your polars cannot read the plan, you get rows instead; see Compatibility.

SourceWhat collecting the result does
Scanned files (pl.scan_*, paths)Executes the plan again and rereads the files, which must still exist
In-memory frame (df.lazy())The plan can embed the DataFrame, so it may be copied on the way in and again on the way out, even when the result is a few rows
Materialized intermediatesA LazyFrame built from an already computed intermediate may carry that intermediate’s data too
Downloaded or decompressed filesRefused with RuntimeError: the temp file is removed when datui exits. Export with e instead

Without capture, exporting with e is the way to get data out.

Compatibility

A DataFrame crosses into datui as Arrow data, which works with any polars the wheel accepts. A LazyFrame crosses as a serialized Polars plan, read by the wheel’s embedded Polars (0.55), and a captured view comes back as a plan the same way. Both sides must agree on the plan format:

Python polarsLazyFramesCaptured views
2.0Most plans read; some, such as joins and rank, are refusedRows, with a warning
1.44Most plans read; some, such as joins, are refusedPlans
1.43The release Polars pairs with Rust 0.55; fully testedPlans
1.38 to 1.42Read in testing (scan, filter, group by, join, cast, sort, unique)Plans

The wheel declares polars>=1.38 and never downgrades the polars you have. A plan the wheel cannot read raises ValueError before the TUI opens, naming the Polars release the wheel is built for. Pass lf.collect() or a path instead. Paths do not go through a plan and work with any polars version. A DataFrame column of Python objects (pl.Object) or Float16 raises ValueError naming the column. Cast a Float16 column to Float32 first.

When your polars cannot read the captured plan, or the view has no plan form (a SQLite table, a text or log file), view() returns the view’s rows instead, with a UserWarning saying why. datui collects the rows at quit and holds them all in memory, so collecting the result reads nothing again.

Build from source

See Build Python bindings.