tabalyst 0.1.2__tar.gz → 0.3.0__tar.gz

tabalyst-0.3.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: tabalyst
+Version: 0.3.0
+Summary: Open-source toolkit for understanding and working with unfamiliar data.
+Author: Gregory Borelli
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/loribel-labs/tabalyst
+Project-URL: Repository, https://github.com/loribel-labs/tabalyst.git
+Project-URL: Issues, https://github.com/loribel-labs/tabalyst/issues
+Keywords: csv,data-analysis,data-profiling,data-quality,eda,html-report,json
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pandas>=2.2
+Requires-Dist: pydantic>=2.10
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Dynamic: license-file
+
+# Tabalyst
+
+**Tools for unfamiliar data.**
+
+Tabalyst is an open-source, local-first toolkit for understanding and working
+with structured data.
+
+Its first tool is **Tabalyst Report**. The current CSV implementation,
+**Tabalyst CSV Report**, analyzes a CSV file and produces both a structured JSON
+profile and a self-contained interactive HTML report.
+
+Tabalyst is in active alpha development. Its interfaces may still change while
+the shared toolkit architecture is being established.
+
+## Install
+
+Tabalyst supports Python 3.11, 3.12, 3.13, and 3.14.
+
+```console
+pip install --upgrade tabalyst
+```
+
+The same command installs Tabalyst or updates it. Tabalyst is in alpha and
+changes often: update it before each new test.
+
+## Tabalyst Report
+
+| Use case | Command | Destination |
+| --- | --- | --- |
+| One file, automatic name | `tabalyst report data.csv` | `data.html` beside the source |
+| One file, custom name | `tabalyst report data.csv -o report.html` | The file `report.html` |
+| Several files, automatic names | `tabalyst report *.csv` | Beside each source |
+| Several files, one directory | `tabalyst report *.csv -d reports/` | The directory `reports/` |
+
+The simplest command keeps the source filename:
+
+```console
+tabalyst report customers.csv
+```
+
+It creates these files beside the source:
+
+```text
+customers.csv
+customers.html
+customers.json
+executions.json
+```
+
+Use `-o` to choose a different HTML filename for one source:
+
+```console
+tabalyst report customers.csv -o customer-analysis.html
+```
+
+### Multiple files
+
+Report several CSV files at once:
+
+```console
+tabalyst report *.csv
+```
+
+Each report is created beside its source and keeps the source stem:
+
+```text
+customers.csv → customers.html
+orders.csv    → orders.html
+products.csv  → products.html
+```
+
+Use `-d` to place all reports in one directory:
+
+```console
+tabalyst report *.csv -d reports/
+```
+
+This produces:
+
+```text
+reports/
+├── customers.html
+├── customers.json
+├── orders.html
+├── orders.json
+├── products.html
+├── products.json
+└── executions.json
+```
+
+Both `-d reports/` and `-d reports` are accepted. Quotes are only needed when a
+path contains spaces.
+
+`-o` always names one output file and therefore accepts only one input. `-d`
+always names an output directory and accepts one or many inputs.
+
+This is invalid because several inputs cannot share one output file:
+
+```console
+tabalyst report *.csv -o report.html
+```
+
+Tabalyst rejects the command before processing any file. Use `-d reports/`
+instead.
+
+### Safe batch behavior
+
+Before processing begins, Tabalyst resolves every input and planned output. It
+stops the entire batch if output names collide or if an output already exists.
+Use `--force` only when replacing all matching report artifacts is intentional:
+
+```console
+tabalyst report *.csv -d reports/ --force
+```
+
+If one CSV is malformed during analysis, Tabalyst reports that error, continues
+with the remaining files, and returns a non-zero exit code at the end.
+
+Interactive terminals show accurate file and phase progress:
+
+```text
+[2/8] orders.csv - Analyzing
+```
+
+Progress and diagnostics use standard error. Progress is disabled automatically
+outside a terminal and can be disabled explicitly with `--no-progress` or
+`--quiet`.
+
+### Useful options
+
+```console
+tabalyst report data.csv --delimiter ";"
+tabalyst report data.csv --encoding cp1252
+tabalyst report data.csv --config tabalyst.json
+tabalyst report data.csv --verbose
+tabalyst report --help
+tabalyst --version
+```
+
+`python -m tabalyst` accepts the same commands.
+
+## Tabalyst Sample
+
+Create a smaller CSV without modifying the source:
+
+```console
+tabalyst sample customers.csv --sample-method random --rows 1000 --seed 42
+```
+
+The default output is `customers.sample.csv` beside the source. Use `-o` to
+name the output for one input, or `-d` to sample several files into one
+directory:
+
+```console
+tabalyst sample customers.csv --sample-method first --rows 100 -o test.csv
+tabalyst sample *.csv --sample-method random --percent 5 -d samples/
+```
+
+Available methods are `first`, `last`, `random` and `stratified`. Stratified
+sampling approximately preserves the distribution of a selected field:
+
+```console
+tabalyst sample customers.csv --sample-method stratified --field province --rows 1000 --seed 42
+```
+
+Sampling reads CSV records as a stream. Random and stratified sampling keep
+only the requested sample, plus stratum counts, in memory. Existing outputs
+require `--force`, and an input file is never overwritten.
+
+## What the report analyzes
+
+- Dataset dimensions, missing cells, duplicates, and quality observations.
+- Physical and semantic types with confidence and error rates.
+- Numeric, date, string-length, normalization, and value distributions.
+- Distinct values, representative examples, enum candidates, and date formats.
+- CSV record widths, quoting, encoding, and delimiter configuration.
+- A bounded raw-data preview while every record is analyzed.
+
+The HTML report is self-contained and works without a CDN or network connection.
+The JSON profile contains the same canonical analysis result for scripts and
+future Tabalyst tools.
+
+## Python API
+
+The same operations are available without the CLI:
+
+```python
+import tabalyst
+
+result = tabalyst.analyze(
+    "customers.csv",
+    "customers.html",
+    separator=";",
+)
+
+batch = tabalyst.generate_reports(
+    ["*.csv"],
+    output_dir="reports",
+)
+
+sample = tabalyst.sample_csv(
+    "customers.csv",
+    method="random",
+    rows=1000,
+    seed=42,
+)
+```
+
+`analyze()` returns the JSON-serializable profile for one report.
+`generate_reports()` returns the complete batch plan, successes, and failures.
+Expected failures derive from `tabalyst.TabalystError`.
+
+Existing artifacts are never replaced silently. Pass `force=True` when
+replacement is intentional.
+
+## Configuration
+
+Configuration files are strict JSON. A minimal file is:
+
+```json
+{
+  "csv": {
+    "delimiter": ";",
+    "encoding": "cp1252"
+  }
+}
+```
+
+Explicit CLI or Python arguments override the configuration file, which overrides
+Tabalyst defaults. See the
+[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
+for all analysis settings.
+
+## Local-first behavior and current limits
+
+Tabalyst performs analysis locally and adds no telemetry or remote processing.
+Generated JSON and HTML may contain source values and should be shared
+accordingly.
+
+Report analysis currently loads the complete CSV into memory. Sampling uses a
+streaming reader with bounded row storage. File and phase progress is available
+for reports; row percentages, throughput estimates, recursive directory input,
+and parallel batch execution will require later ingestion work.
+
+## Examples and development
+
+The repository includes small and synthetic public examples under `examples/`.
+See the [examples README](https://github.com/loribel-labs/tabalyst/blob/main/examples/README.md)
+for regeneration commands.
+
+```console
+python -m pytest
+python -m ruff check .
+python -m build
+```
+
+Additional documentation:
+
+- [Architecture](https://github.com/loribel-labs/tabalyst/blob/main/docs/dev/architecture.md)
+- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
+- [Release procedure](https://github.com/loribel-labs/tabalyst/blob/main/RELEASING.md)
+
+Please report defects and feature requests through the
+[GitHub issue tracker](https://github.com/loribel-labs/tabalyst/issues).
+
+## License
+
+Tabalyst is released under the [MIT License](LICENSE).
+
+Created by Gregory Borelli — Catalyseur Numérique.

tabalyst-0.3.0/README.md

@@ -0,0 +1,270 @@
+# Tabalyst
+
+**Tools for unfamiliar data.**
+
+Tabalyst is an open-source, local-first toolkit for understanding and working
+with structured data.
+
+Its first tool is **Tabalyst Report**. The current CSV implementation,
+**Tabalyst CSV Report**, analyzes a CSV file and produces both a structured JSON
+profile and a self-contained interactive HTML report.
+
+Tabalyst is in active alpha development. Its interfaces may still change while
+the shared toolkit architecture is being established.
+
+## Install
+
+Tabalyst supports Python 3.11, 3.12, 3.13, and 3.14.
+
+```console
+pip install --upgrade tabalyst
+```
+
+The same command installs Tabalyst or updates it. Tabalyst is in alpha and
+changes often: update it before each new test.
+
+## Tabalyst Report
+
+| Use case | Command | Destination |
+| --- | --- | --- |
+| One file, automatic name | `tabalyst report data.csv` | `data.html` beside the source |
+| One file, custom name | `tabalyst report data.csv -o report.html` | The file `report.html` |
+| Several files, automatic names | `tabalyst report *.csv` | Beside each source |
+| Several files, one directory | `tabalyst report *.csv -d reports/` | The directory `reports/` |
+
+The simplest command keeps the source filename:
+
+```console
+tabalyst report customers.csv
+```
+
+It creates these files beside the source:
+
+```text
+customers.csv
+customers.html
+customers.json
+executions.json
+```
+
+Use `-o` to choose a different HTML filename for one source:
+
+```console
+tabalyst report customers.csv -o customer-analysis.html
+```
+
+### Multiple files
+
+Report several CSV files at once:
+
+```console
+tabalyst report *.csv
+```
+
+Each report is created beside its source and keeps the source stem:
+
+```text
+customers.csv → customers.html
+orders.csv    → orders.html
+products.csv  → products.html
+```
+
+Use `-d` to place all reports in one directory:
+
+```console
+tabalyst report *.csv -d reports/
+```
+
+This produces:
+
+```text
+reports/
+├── customers.html
+├── customers.json
+├── orders.html
+├── orders.json
+├── products.html
+├── products.json
+└── executions.json
+```
+
+Both `-d reports/` and `-d reports` are accepted. Quotes are only needed when a
+path contains spaces.
+
+`-o` always names one output file and therefore accepts only one input. `-d`
+always names an output directory and accepts one or many inputs.
+
+This is invalid because several inputs cannot share one output file:
+
+```console
+tabalyst report *.csv -o report.html
+```
+
+Tabalyst rejects the command before processing any file. Use `-d reports/`
+instead.
+
+### Safe batch behavior
+
+Before processing begins, Tabalyst resolves every input and planned output. It
+stops the entire batch if output names collide or if an output already exists.
+Use `--force` only when replacing all matching report artifacts is intentional:
+
+```console
+tabalyst report *.csv -d reports/ --force
+```
+
+If one CSV is malformed during analysis, Tabalyst reports that error, continues
+with the remaining files, and returns a non-zero exit code at the end.
+
+Interactive terminals show accurate file and phase progress:
+
+```text
+[2/8] orders.csv - Analyzing
+```
+
+Progress and diagnostics use standard error. Progress is disabled automatically
+outside a terminal and can be disabled explicitly with `--no-progress` or
+`--quiet`.
+
+### Useful options
+
+```console
+tabalyst report data.csv --delimiter ";"
+tabalyst report data.csv --encoding cp1252
+tabalyst report data.csv --config tabalyst.json
+tabalyst report data.csv --verbose
+tabalyst report --help
+tabalyst --version
+```
+
+`python -m tabalyst` accepts the same commands.
+
+## Tabalyst Sample
+
+Create a smaller CSV without modifying the source:
+
+```console
+tabalyst sample customers.csv --sample-method random --rows 1000 --seed 42
+```
+
+The default output is `customers.sample.csv` beside the source. Use `-o` to
+name the output for one input, or `-d` to sample several files into one
+directory:
+
+```console
+tabalyst sample customers.csv --sample-method first --rows 100 -o test.csv
+tabalyst sample *.csv --sample-method random --percent 5 -d samples/
+```
+
+Available methods are `first`, `last`, `random` and `stratified`. Stratified
+sampling approximately preserves the distribution of a selected field:
+
+```console
+tabalyst sample customers.csv --sample-method stratified --field province --rows 1000 --seed 42
+```
+
+Sampling reads CSV records as a stream. Random and stratified sampling keep
+only the requested sample, plus stratum counts, in memory. Existing outputs
+require `--force`, and an input file is never overwritten.
+
+## What the report analyzes
+
+- Dataset dimensions, missing cells, duplicates, and quality observations.
+- Physical and semantic types with confidence and error rates.
+- Numeric, date, string-length, normalization, and value distributions.
+- Distinct values, representative examples, enum candidates, and date formats.
+- CSV record widths, quoting, encoding, and delimiter configuration.
+- A bounded raw-data preview while every record is analyzed.
+
+The HTML report is self-contained and works without a CDN or network connection.
+The JSON profile contains the same canonical analysis result for scripts and
+future Tabalyst tools.
+
+## Python API
+
+The same operations are available without the CLI:
+
+```python
+import tabalyst
+
+result = tabalyst.analyze(
+    "customers.csv",
+    "customers.html",
+    separator=";",
+)
+
+batch = tabalyst.generate_reports(
+    ["*.csv"],
+    output_dir="reports",
+)
+
+sample = tabalyst.sample_csv(
+    "customers.csv",
+    method="random",
+    rows=1000,
+    seed=42,
+)
+```
+
+`analyze()` returns the JSON-serializable profile for one report.
+`generate_reports()` returns the complete batch plan, successes, and failures.
+Expected failures derive from `tabalyst.TabalystError`.
+
+Existing artifacts are never replaced silently. Pass `force=True` when
+replacement is intentional.
+
+## Configuration
+
+Configuration files are strict JSON. A minimal file is:
+
+```json
+{
+  "csv": {
+    "delimiter": ";",
+    "encoding": "cp1252"
+  }
+}
+```
+
+Explicit CLI or Python arguments override the configuration file, which overrides
+Tabalyst defaults. See the
+[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
+for all analysis settings.
+
+## Local-first behavior and current limits
+
+Tabalyst performs analysis locally and adds no telemetry or remote processing.
+Generated JSON and HTML may contain source values and should be shared
+accordingly.
+
+Report analysis currently loads the complete CSV into memory. Sampling uses a
+streaming reader with bounded row storage. File and phase progress is available
+for reports; row percentages, throughput estimates, recursive directory input,
+and parallel batch execution will require later ingestion work.
+
+## Examples and development
+
+The repository includes small and synthetic public examples under `examples/`.
+See the [examples README](https://github.com/loribel-labs/tabalyst/blob/main/examples/README.md)
+for regeneration commands.
+
+```console
+python -m pytest
+python -m ruff check .
+python -m build
+```
+
+Additional documentation:
+
+- [Architecture](https://github.com/loribel-labs/tabalyst/blob/main/docs/dev/architecture.md)
+- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/en/reference/configuration.md)
+- [Release procedure](https://github.com/loribel-labs/tabalyst/blob/main/RELEASING.md)
+
+Please report defects and feature requests through the
+[GitHub issue tracker](https://github.com/loribel-labs/tabalyst/issues).
+
+## License
+
+Tabalyst is released under the [MIT License](LICENSE).
+
+Created by Gregory Borelli — Catalyseur Numérique.

{tabalyst-0.1.2 → tabalyst-0.3.0}/examples/README.md

@@ -28,8 +28,8 @@ domains.
 From the repository root, regenerate both outputs with:
 
 ```console
-tabalyst examples/input/basic.csv examples/output/basic/report.html --config examples/config.json
-tabalyst examples/input/insurance-customers.csv examples/output/insurance-customers/report.html --config examples/config.json
+tabalyst report examples/input/basic.csv -o examples/output/basic/report.html --config examples/config.json --force
+tabalyst report examples/input/insurance-customers.csv -o examples/output/insurance-customers/report.html --config examples/config.json --force
 ```
 
 Every output folder is independent and contains its own HTML report, canonical

{tabalyst-0.1.2 → tabalyst-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabalyst"
-version = "0.1.2"
-description = "Open-source data profiling engine for structured JSON and customizable HTML reports."
+version = "0.3.0"
+description = "Open-source toolkit for understanding and working with unfamiliar data."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"

{tabalyst-0.1.2 → tabalyst-0.3.0}/src/tabalyst/__init__.py

@@ -4,7 +4,12 @@ from tabalyst._version import __version__
 from tabalyst.analysis import analyze_column as analyze_column
 from tabalyst.config import AnalysisConfig as AnalysisConfig
 from tabalyst.errors import ConfigurationError, InputError, ReportError, TabalystError
+from tabalyst.report_service import generate_reports as generate_reports
 from tabalyst.reporting import render_report as render_report
+from tabalyst.sampling import SampleMethod as SampleMethod
+from tabalyst.sampling import SampleResult as SampleResult
+from tabalyst.sampling import sample_csv as sample_csv
+from tabalyst.sampling_service import generate_samples as generate_samples
 from tabalyst.service import analyze
 from tabalyst.service import analyze_csv as analyze_csv
 
@@ -15,6 +20,9 @@ __all__ = [
     "TabalystError",
     "__version__",
     "analyze",
+    "generate_reports",
+    "generate_samples",
+    "sample_csv",
 ]
 
 # Alpha compatibility imports remain available, but are not part of the 0.1.0 API.

tabalyst-0.3.0/src/tabalyst/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Public command-line application for Tabalyst."""
+
+from tabalyst.cli.app import app, main
+
+__all__ = ["app", "main"]

tabalyst-0.3.0/src/tabalyst/cli/app.py

@@ -0,0 +1,46 @@
+"""Tabalyst command-line application."""
+
+from typing import Annotated
+
+import typer
+
+from tabalyst import __version__
+from tabalyst.cli.report import report_command
+from tabalyst.cli.sample import sample_command
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Tools for unfamiliar data.",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show the installed Tabalyst version and exit.",
+            is_eager=True,
+            callback=_version_callback,
+        ),
+    ] = False,
+) -> None:
+    """Understand, explore, clean, and validate structured data."""
+
+
+app.command("report")(report_command)
+app.command("sample")(sample_command)
+
+
+def main() -> None:
+    """Run the Tabalyst command-line application."""
+    app()