Tabalyst
ENFR
Get started
ENFR

Tabalyst for developers

Profile and inspect data from your CLI or Python workflows.

Tabalyst is an open-source, local-first toolkit. Install it with pip, point it at a CSV, Excel, JSON or JSONL file, and get an HTML report for you and a JSON profile for your code. No service to call, no telemetry.

Get startedCLI referencePython API reference
Nothing overwrittenAn existing report stops the batch
tabalyst report basic.csv -d reports/
Error: Report output already exists. Use --force to replace it:
  reports/basic.html
  reports/basic.json
A choice to makeAmbiguous input, no guess
tabalyst report shop.json
2 collections of shop.json are equally plausible.
Nothing was analyzed.
Candidates:
  $.customers[] (2 elements)
  $.products[] (2 elements)

Real output of tabalyst 0.6.0, paths shortened.

Your angle

Built to be scripted

  • 01 / ONE LINE

    Install, run, done

    pip install tabalyst gives you the tabalyst command and the Python package. One command per file or per folder, and one report with its profile for each file.

  • 02 / MACHINE OUTPUT

    A JSON profile for your code

    Every run writes a JSON profile beside the HTML report: the same analysis, structured. The format is versioned with format_version and format_revision, and still experimental: check both before you rely on a field.

  • 03 / EXPLICIT

    Failures you can script

    Exit codes tell an invalid command or a choice to make (2) from a failed analysis (1) and an unreadable input (4). A failed file does not stop the others, and nothing is replaced without --force.

Workflow

From pip install to a batch in your pipeline

Tabalyst Report runs on your machine and needs Python 3.11 or later. The command line and the Python API do the same work.

  1. 1 · Install
    pip install tabalyst

    # Also updates it: Tabalyst changes often

  2. 2 · One file
    tabalyst report data.csv

    # data.html, data.json and executions.json, beside the source

  3. 3 · A batch
    tabalyst report *.csv -d reports/

    # One report and one profile per file. A failed file does not stop the others

Expected failures raise tabalyst.TabalystError. Pass force=True to replace existing outputs on purpose. Settings go in a strict JSON file given with --config, or with config_path in Python; explicit arguments override it.

The toolkit chains. tabalyst inspect orders.json writes the choice of collection to a file you can edit. tabalyst scan writes the complete description of every field. tabalyst report --scan file.scan.json builds a report from a scan document without reading the source again.

Proof

See what your code receives

The profile of the example report, shortened. The report that people read is rendered from it.

report.jsonOne analysis, structured
{
  "format_version": "0.1.0a",
  "format_revision": 11,
  "source": {
    "filename": "insurance-customers.csv",
    "format": "csv",
    "size_bytes": 827600,
    "delimiter": ","
  },
  "datasets": [{
    "id": "rows",
    "summary": {
      "row_count": 3000,
      "column_count": 34,
      "missing_count": 12532,
      "duplicate_row_count": 8
    },
    "columns": [ ... ],
    "issues": [ ... ]
  }]
}

Synthetic insurance customers, analyzed as they are. Shortened: some fields are left out.

report.json report.html JSON profile reference

Scope, not hype

What to know before you depend on it

  • The JSON profile format is experimental and can change incompatibly between releases. Pin the Tabalyst version your code reads, and check format_version and format_revision.
  • tabalyst.analyze() reads CSV files. For Excel, JSON and JSONL, use generate_reports(), the command line or scan().
  • Wildcards such as *.csv match the files of one folder, not its subfolders.
  • Tabalyst is in beta. It profiles a file: it does not clean it or check your domain rules.

The known limitations ↗ list the rest.

Next step

Where to go next

Tabalyst is open source under MPL-2.0. Read the source, report a problem or ask for a feature on GitHub.

SOURCE

GitHub

Source code, issues and releases.

PACKAGE

PyPI

The published package.

HUB

Developers

Resources and integration notes in one place.

Your next pipeline

See your data in one command.

Install Tabalyst, run it on a file or a folder, and read the profile from your own code.

Get started with Tabalyst ReportRead the CLI reference