Skip to content
TabalystDocs
Beta · version 0.6.1 · commands and the JSON format may still change.

Python API

Everything the command line does is available from Python. Import tabalyst and call the functions described in the pages below. Names not documented here are internal and may change without notice during beta.

import tabalyst


batch = tabalyst.generate_reports(["*.csv"], output_dir="reports")

Functions by task

Section titled “Functions by task”
To do thisUsePage
Write the report and profile of one CSV filetabalyst.analyze()Python API: reports
Write reports for CSV, JSON, JSONL or Excel filestabalyst.generate_reports()Python API: reports
Get a profile or its HTML without writing filestabalyst.analyze_csv(), tabalyst.analyze_scan(), tabalyst.render_report()Python API: reports
Scan one source in memorytabalyst.scan()Python API: scans
Write scan documentstabalyst.generate_scans()Python API: scans
Find how to read a JSON, JSONL or Excel filetabalyst.inspect(), tabalyst.generate_inspections()Python API: Inspect
Write a smaller CSV filetabalyst.sample_csv(), tabalyst.generate_samples()Python API: sampling

Conventions

Section titled “Conventions”

Batch functions

Section titled “Batch functions”

The generate_* functions take input_specs, a list of files and non-recursive glob patterns, as the command line does, and process the whole batch. They return a batch result with the same four members:

  • plan: the jobs that were planned, and plan.warnings, a tuple of (source, sentence) pairs about what planning left out, such as an option that a source cannot use.
  • successes: one entry per source that was processed, with its job and its result.
  • failures: one entry per source that failed, with its job and its error. A failed source does not stop the others.
  • succeeded: True when there is no failure.

The whole batch is rejected before any work when an output is unsafe, such as two sources that map to one file or an output that would replace a source.

batch = tabalyst.generate_reports(["data/*.csv"], output_dir="reports")
for failure in batch.failures:
    print(failure.job.source, failure.error)

Errors

Section titled “Errors”

Expected failures derive from tabalyst.TabalystError: ConfigurationError (invalid options or configuration, or a collection that must be chosen), InputError (a missing, unreadable or invalid source) and ReportError (a file that cannot be rendered or written). A source whose collection must be chosen raises a ConfigurationError, as exit code 2 does on the command line. Functions for one source raise the error; batch functions list it among the failures.

Existing files

Section titled “Existing files”

Existing outputs are never replaced silently. Pass force=True when replacement is intended. A source is never replaced.

Configuration files

Section titled “Configuration files”

config_path is one JSON configuration file or a sequence of files merged in order. Explicit arguments override the files, which override the defaults.

Progress

Section titled “Progress”

on_progress is a function that receives a progress event for each phase of each source. It is optional, and is what the command line uses to print its progress line.

Section titled “Related pages”