tabalyst 0.1.0__tar.gz

tabalyst-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chergreg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tabalyst-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include examples/README.md
+include examples/config.json
+recursive-include examples/input *.csv

tabalyst-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: tabalyst
+Version: 0.1.0
+Summary: Open-source data profiling engine for structured JSON and customizable HTML reports.
+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
+
+Tabalyst is a local-first CSV profiling library and command-line tool. It reads a
+CSV file once, produces a structured JSON profile, and renders the same result as
+an interactive HTML report.
+
+Version `0.1.0` is the first packaged public API. The analysis format is still
+young, so larger schema changes are reserved for future minor releases.
+
+## Requirements and installation
+
+Tabalyst supports Python 3.11, 3.12, 3.13, and 3.14.
+
+```console
+pip install tabalyst
+```
+
+For local development from a clone:
+
+```console
+python -m venv .venv
+python -m pip install -e ".[dev]"
+```
+
+## Command line
+
+Pass the CSV source and the complete HTML report path as positional arguments:
+
+```console
+tabalyst data.csv reports/client-a.html
+```
+
+The report path must end in `.html`. Parent directories are created
+automatically, and existing artifacts are replaced. A successful run creates:
+
+```text
+reports/
+|-- client-a.html
+|-- client-a.json
+`-- executions.json
+```
+
+The JSON profile always shares the HTML filename stem. `executions.json` keeps a
+cumulative history for successful analyses in the same report directory, so
+several named reports can coexist there.
+
+Common options are:
+
+```console
+tabalyst data.csv reports/client-a.html --separator ";" --encoding cp1252
+tabalyst data.csv reports/client-a.html --config tabalyst.json
+tabalyst --help
+tabalyst --version
+```
+
+`python -m tabalyst` accepts the same arguments.
+
+## Python API
+
+```python
+import tabalyst
+
+result = tabalyst.analyze(
+    "data.csv",
+    "reports/client-a.html",
+    separator=";",
+    encoding="cp1252",
+    config_path="tabalyst.json",
+)
+
+print(tabalyst.__version__)
+print(result["summary"]["row_count"])
+```
+
+`analyze()` returns a JSON-serializable dictionary whose logical content matches
+the adjacent JSON file. The HTML is rendered from that canonical JSON profile.
+Expected failures derive from `tabalyst.TabalystError`; callers may distinguish
+`InputError`, `ConfigurationError`, and `ReportError`.
+
+## Configuration
+
+Configuration files are strict JSON. Unknown names and invalid values are errors.
+The existing analysis settings remain available; the smallest useful file is:
+
+```json
+{
+  "csv": {
+    "delimiter": ";",
+    "encoding": "cp1252"
+  }
+}
+```
+
+Resolution order is:
+
+1. an explicit `separator` or `encoding` argument;
+2. the file passed with `config_path` or `--config`;
+3. Tabalyst defaults: comma and `utf-8-sig`.
+
+`utf-8-sig` accepts ordinary UTF-8 and UTF-8 with a byte-order mark. See the
+[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/configuration.md)
+for analysis, normalization,
+date, type-inference, sampling, and enum settings.
+
+## Public examples
+
+The repository contains two reproducible examples:
+
+- `basic`: five rows covering common CSV values and one duplicate row.
+- `insurance-customers`: 3,000 synthetic customer and contract records across
+  34 columns. Names and contact details are fictional, and email addresses use
+  reserved `.example` domains.
+
+Each dataset under `examples/input/` has a matching generated report under
+`examples/output/`. Regenerate both 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
+```
+
+See the complete layout and maintenance notes in the
+[examples README](https://github.com/loribel-labs/tabalyst/blob/main/examples/README.md).
+
+## What the report contains
+
+- Dataset dimensions, missing cells, duplicate rows, and quality observations.
+- Physical and semantic type inference with explicit confidence and error rates.
+- Numeric, date, string-length, normalization, and value-distribution profiles.
+- A bounded raw-data preview while all records are analyzed.
+- Sortable and filterable HTML tables.
+
+Raw strings are preserved. The complete CSV is currently loaded into memory.
+Report data remains local and Tabalyst adds no telemetry or remote analysis.
+Bootstrap, DataTables, and Google Fonts are loaded from pinned CDNs for the full
+interactive presentation; the Tabalyst template, theme, and report JavaScript are
+included in the Python package.
+
+## Compatibility with alpha commands
+
+The earlier commands remain available during the `0.1.x` transition:
+
+```console
+tabalyst analyze data.csv -o reports/client-a.html
+tabalyst render reports/client-a.json -o reports/regenerated.html
+```
+
+The alpha `analyze` form also retains automatic `tabalyst.json` discovery,
+multiple `--config` overrides, and `--preview-rows`. New integrations should use
+the direct command or `tabalyst.analyze()`.
+
+## Development and packaging
+
+```console
+python -m pytest
+python -m ruff check .
+python -m build
+```
+
+The build creates a wheel and source distribution under `dist/`. Release steps,
+including the clean-wheel smoke test and PyPI Trusted Publishing setup, are in
+[RELEASING.md](https://github.com/loribel-labs/tabalyst/blob/main/RELEASING.md).
+
+Report format details and internal boundaries are documented in
+[docs/architecture.md](https://github.com/loribel-labs/tabalyst/blob/main/docs/architecture.md).
+Please report defects through the
+[GitHub issue tracker](https://github.com/loribel-labs/tabalyst/issues).
+
+## License
+
+Tabalyst is released under the
+[MIT License](https://github.com/loribel-labs/tabalyst/blob/main/LICENSE).
+
+Created by Gregory Borelli - Catalyseur Numérique.

tabalyst-0.1.0/README.md

@@ -0,0 +1,174 @@
+# Tabalyst
+
+Tabalyst is a local-first CSV profiling library and command-line tool. It reads a
+CSV file once, produces a structured JSON profile, and renders the same result as
+an interactive HTML report.
+
+Version `0.1.0` is the first packaged public API. The analysis format is still
+young, so larger schema changes are reserved for future minor releases.
+
+## Requirements and installation
+
+Tabalyst supports Python 3.11, 3.12, 3.13, and 3.14.
+
+```console
+pip install tabalyst
+```
+
+For local development from a clone:
+
+```console
+python -m venv .venv
+python -m pip install -e ".[dev]"
+```
+
+## Command line
+
+Pass the CSV source and the complete HTML report path as positional arguments:
+
+```console
+tabalyst data.csv reports/client-a.html
+```
+
+The report path must end in `.html`. Parent directories are created
+automatically, and existing artifacts are replaced. A successful run creates:
+
+```text
+reports/
+|-- client-a.html
+|-- client-a.json
+`-- executions.json
+```
+
+The JSON profile always shares the HTML filename stem. `executions.json` keeps a
+cumulative history for successful analyses in the same report directory, so
+several named reports can coexist there.
+
+Common options are:
+
+```console
+tabalyst data.csv reports/client-a.html --separator ";" --encoding cp1252
+tabalyst data.csv reports/client-a.html --config tabalyst.json
+tabalyst --help
+tabalyst --version
+```
+
+`python -m tabalyst` accepts the same arguments.
+
+## Python API
+
+```python
+import tabalyst
+
+result = tabalyst.analyze(
+    "data.csv",
+    "reports/client-a.html",
+    separator=";",
+    encoding="cp1252",
+    config_path="tabalyst.json",
+)
+
+print(tabalyst.__version__)
+print(result["summary"]["row_count"])
+```
+
+`analyze()` returns a JSON-serializable dictionary whose logical content matches
+the adjacent JSON file. The HTML is rendered from that canonical JSON profile.
+Expected failures derive from `tabalyst.TabalystError`; callers may distinguish
+`InputError`, `ConfigurationError`, and `ReportError`.
+
+## Configuration
+
+Configuration files are strict JSON. Unknown names and invalid values are errors.
+The existing analysis settings remain available; the smallest useful file is:
+
+```json
+{
+  "csv": {
+    "delimiter": ";",
+    "encoding": "cp1252"
+  }
+}
+```
+
+Resolution order is:
+
+1. an explicit `separator` or `encoding` argument;
+2. the file passed with `config_path` or `--config`;
+3. Tabalyst defaults: comma and `utf-8-sig`.
+
+`utf-8-sig` accepts ordinary UTF-8 and UTF-8 with a byte-order mark. See the
+[configuration reference](https://github.com/loribel-labs/tabalyst/blob/main/docs/configuration.md)
+for analysis, normalization,
+date, type-inference, sampling, and enum settings.
+
+## Public examples
+
+The repository contains two reproducible examples:
+
+- `basic`: five rows covering common CSV values and one duplicate row.
+- `insurance-customers`: 3,000 synthetic customer and contract records across
+  34 columns. Names and contact details are fictional, and email addresses use
+  reserved `.example` domains.
+
+Each dataset under `examples/input/` has a matching generated report under
+`examples/output/`. Regenerate both 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
+```
+
+See the complete layout and maintenance notes in the
+[examples README](https://github.com/loribel-labs/tabalyst/blob/main/examples/README.md).
+
+## What the report contains
+
+- Dataset dimensions, missing cells, duplicate rows, and quality observations.
+- Physical and semantic type inference with explicit confidence and error rates.
+- Numeric, date, string-length, normalization, and value-distribution profiles.
+- A bounded raw-data preview while all records are analyzed.
+- Sortable and filterable HTML tables.
+
+Raw strings are preserved. The complete CSV is currently loaded into memory.
+Report data remains local and Tabalyst adds no telemetry or remote analysis.
+Bootstrap, DataTables, and Google Fonts are loaded from pinned CDNs for the full
+interactive presentation; the Tabalyst template, theme, and report JavaScript are
+included in the Python package.
+
+## Compatibility with alpha commands
+
+The earlier commands remain available during the `0.1.x` transition:
+
+```console
+tabalyst analyze data.csv -o reports/client-a.html
+tabalyst render reports/client-a.json -o reports/regenerated.html
+```
+
+The alpha `analyze` form also retains automatic `tabalyst.json` discovery,
+multiple `--config` overrides, and `--preview-rows`. New integrations should use
+the direct command or `tabalyst.analyze()`.
+
+## Development and packaging
+
+```console
+python -m pytest
+python -m ruff check .
+python -m build
+```
+
+The build creates a wheel and source distribution under `dist/`. Release steps,
+including the clean-wheel smoke test and PyPI Trusted Publishing setup, are in
+[RELEASING.md](https://github.com/loribel-labs/tabalyst/blob/main/RELEASING.md).
+
+Report format details and internal boundaries are documented in
+[docs/architecture.md](https://github.com/loribel-labs/tabalyst/blob/main/docs/architecture.md).
+Please report defects through the
+[GitHub issue tracker](https://github.com/loribel-labs/tabalyst/issues).
+
+## License
+
+Tabalyst is released under the
+[MIT License](https://github.com/loribel-labs/tabalyst/blob/main/LICENSE).
+
+Created by Gregory Borelli - Catalyseur Numérique.

tabalyst-0.1.0/examples/README.md

@@ -0,0 +1,41 @@
+# Tabalyst examples
+
+The examples are organized by input name so additional public datasets can be
+added without mixing source data and generated artifacts.
+
+```text
+examples/
+|-- config.json
+|-- input/
+|   |-- basic.csv
+|   `-- insurance-customers.csv
+`-- output/
+    |-- basic/
+    |   |-- report.html
+    |   |-- report.json
+    |   `-- executions.json
+    `-- insurance-customers/
+        |-- report.html
+        |-- report.json
+        `-- executions.json
+```
+
+`basic.csv` is a five-row smoke example. `insurance-customers.csv` contains 3,000
+synthetic customer and contract records across 34 columns. Its people, contact
+details, and contracts are fictional; email addresses use reserved `.example`
+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
+```
+
+Every output folder is independent and contains its own HTML report, canonical
+JSON profile, and cumulative `executions.json` history. Delete an output folder
+before regenerating when a fresh one-entry execution history is required.
+
+The input datasets and generated output are public repository examples. The wheel
+contains only the runtime package and report resources; examples are not installed
+as package data.

tabalyst-0.1.0/examples/config.json

@@ -0,0 +1,48 @@
+{
+  "csv": {
+    "encoding": "utf-8-sig",
+    "delimiter": ","
+  },
+  "missing_values": ["", "N/A", "NULL"],
+  "preview_rows": 20,
+  "normalization": {
+    "trim": true,
+    "collapse_internal_whitespace": true
+  },
+  "date_detection": {
+    "enabled": true,
+    "orders": ["YMD", "MDY", "DMY"],
+    "separators": ["-", "/", "."],
+    "ambiguous_order": null
+  },
+  "type_inference": {
+    "minimum_confidence": 0.95
+  },
+  "string_analysis": {
+    "very_short_max_length": 5,
+    "short_max_length": 20,
+    "medium_max_length": 50,
+    "long_max_length": 255,
+    "length_distribution_max_length": 50,
+    "examples_per_length": 10
+  },
+  "value_examples": {
+    "full_distribution_max_distinct": 50,
+    "candidate_sample_size": 100,
+    "short_text_max_length": 20,
+    "short_text_percentile": 0.95,
+    "short_text_result_size": 20,
+    "long_text_result_size": 20,
+    "long_text_truncate_at": 30,
+    "truncation_suffix": "...",
+    "inline_display_size": 3,
+    "random_seed": 42
+  },
+  "enum_detection": {
+    "enabled": true,
+    "minimum_row_count": 500,
+    "maximum_distinct_values": 49,
+    "eligible_types": ["text"],
+    "case_sensitive": true
+  }
+}

tabalyst-0.1.0/examples/input/basic.csv

@@ -0,0 +1,6 @@
+id,name,amount,joined,active,notes
+001,Alice,12.50,2026-01-01,true,First order
+002,Bob,,2026-02-01,false,
+003,Charlie,25.00,2026-03-01,true,"Two items, one order"
+003,Charlie,25.00,2026-03-01,true,"Two items, one order"
+004,Dana,not available,2026-04-01,true,Pending review