tabcaddy 0.1.3

Dataset-centric CLI toolkit for exploring, compiling, transforming, and diffing tabular data

TabCaddy

TabCaddy is a command-line tool for exploring, compiling, transforming, and comparing tabular datasets.

It works with single files, whole folders, and previously compiled datasets, so you can move from quick inspection to repeatable data workflows without switching tools.

Install

TabCaddy currently requires Python 3.13 or newer.

Install with pip:

pip install tabcaddy

Install with uv as a standalone CLI:

uv tool install tabcaddy

If you prefer to add it to a project environment, you can also use:

uv add tabcaddy

Supported Inputs

• .csv
• .feather
• .arrow
• folders containing supported files
• compiled TabCaddy datasets created by tabcaddy compile

Quick Start

Inspect a single dataset:

tabcaddy summary trades.feather

Inspect a folder of files:

tabcaddy summary data/

Look at schema drift across a folder:

tabcaddy schema data/

Compile a folder into a reusable parquet dataset:

tabcaddy compile data/

Compare two datasets:

tabcaddy diff old_data/ new_data/

What summary Shows

tabcaddy summary is the main entry point for understanding a dataset. Depending on the selected profile, it can show:

• file, row, column, and schema counts
• schema overview and schema distribution
• per-column statistics such as null rate, min, max, and mean
• date ranges for temporal columns
• warnings such as schema drift
• deep-profile histograms, uniqueness estimates, and column hashes

Profiles

Use --profile with summary or schema to control how much work TabCaddy does.

• quick: counts only, for fast inspection
• standard: metadata, schema overview, lightweight statistics, and warnings
• deep: adds uniqueness estimates, histograms, and column hashes

Example:

tabcaddy summary data/ --profile deep

Commands

summary

tabcaddy summary <source> [--profile quick|standard|deep]

Use this for everyday inspection of a file, folder, or compiled dataset.

schema

tabcaddy schema <source> [--profile quick|standard|deep]

Use this when you care specifically about schema groups, type changes, and files that violate the dominant schema.

compile

tabcaddy compile <folder> [--output compiled_dataset] [--schema N] [--interactive]

Compile a folder of compatible files into a parquet-backed TabCaddy dataset. If multiple schemas are present, you can either pick one explicitly with --schema or let TabCaddy ask you in --interactive mode.

transform

tabcaddy transform <input> <transform.py> [output_folder] [--workers N]

Apply a Python transform to a single file or a folder of files. If you omit the output folder, TabCaddy creates one automatically by appending _transformed.

When the input is a compiled dataset, output is written as a compiled dataset as well (data/*.parquet plus refreshed metadata.json).

Supported transform signatures:

def transform(df):
    return df

def transform(df, context):
    return df

The optional context includes:

• file_name
• file_path
• schema
• metadata.row_count
• metadata.schema_hash

scaffold-transform

tabcaddy scaffold-transform <source> [--output transform_template.py]

Generate a starter transform file with observed schemas and example snippets.

diff

tabcaddy diff <left> <right> [--level metadata|statistics|full]

Compare two files, two folders, or two compiled datasets.

• metadata: high-level changes only
• statistics: metadata plus statistics changes
• full: metadata, schema, and statistics changes

Typical Workflows

Inspect a folder before deciding whether to compile it:

tabcaddy summary raw_exports/
tabcaddy schema raw_exports/

Compile the dominant schema into a reusable dataset:

tabcaddy compile raw_exports/ --interactive

Generate a transform scaffold, edit it, then apply it:

tabcaddy scaffold-transform raw_exports/
tabcaddy transform raw_exports/ transform_template.py cleaned_exports/

Compare two compiled snapshots:

tabcaddy diff compiled_dataset_2025_12 compiled_dataset_2026_01 --level full

Help

See all commands:

tabcaddy --help

See help for a specific command:

tabcaddy summary --help
tabcaddy compile --help
tabcaddy transform --help