tabalyst 0.1.1__tar.gz → 0.2.1__tar.gz

tabalyst-0.2.1/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: tabalyst
+Version: 0.2.1
+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 tabalyst
+```
+
+## 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.
+
+## 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",
+)
+```
+
+`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/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.
+
+The complete CSV is currently loaded into memory. File and phase progress is
+available now; 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/architecture.md)
+- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/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.2.1/README.md

@@ -0,0 +1,231 @@
+# 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 tabalyst
+```
+
+## 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.
+
+## 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",
+)
+```
+
+`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/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.
+
+The complete CSV is currently loaded into memory. File and phase progress is
+available now; 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/architecture.md)
+- [Configuration](https://github.com/loribel-labs/tabalyst/blob/main/docs/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.1 → tabalyst-0.2.1}/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.1 → tabalyst-0.2.1}/pyproject.toml

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

{tabalyst-0.1.1 → tabalyst-0.2.1}/src/tabalyst/__init__.py

@@ -4,6 +4,7 @@ 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.service import analyze
 from tabalyst.service import analyze_csv as analyze_csv
@@ -15,6 +16,7 @@ __all__ = [
     "TabalystError",
     "__version__",
     "analyze",
+    "generate_reports",
 ]
 
 # Alpha compatibility imports remain available, but are not part of the 0.1.0 API.