sanitizepy 0.1.0__tar.gz

sanitizepy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syed Muhammad Taha Hassan
+
+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.

sanitizepy-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: sanitizepy
+Version: 0.1.0
+Summary: An open-source Python engine for automated tabular data quality inspection, explainable cleaning, and preprocessing.
+Author: Syed Muhammad Taha Hassan
+License-Expression: MIT
+Keywords: machine-learning,data-quality,data-cleaning,eda,feature-engineering,preprocessing,pandas,python,data-analysis
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.3.0,>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: pandas-stubs>=2.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+
+# sanitizepy
+
+An open-source Python engine for automated tabular data quality inspection, explainable cleaning, and preprocessing.
+
+---
+
+## Overview
+
+`sanitizepy` provides modular, high-performance data engineering components built on top of `pandas`, `numpy`, `scipy`, `rich`, and `pydantic`. The library is designed around a transparent **Detect → Explain → Recommend → Preview → Apply → Validate → Audit** workflow.
+
+`sanitizepy` separates responsibilities into dedicated subsystems:
+- **Core Engine & High-Level API**: Centralized `Cleaner` entry point supporting `.inspect()`, `.plan()`, and `.clean(..., dry_run=True)`.
+- **Dataset Health & Inspection**: Read-only dataset analysis covering completeness, uniqueness, consistency, validity, datatypes, memory consumption, and statistical distributions with a composite **Dataset Health Score (0–100)**.
+- **Explainable Recommendations & Planning**: Rule-based issue detection with human-readable explanations (`WHAT`, `WHY`, `SEVERITY`, `EVIDENCE`, `RECOMMENDATION`) and previewable `CleaningPlan` instances.
+- **Cleaning Engine**: Safe, deterministic dataset transformations with dry-run support, before/after impact metrics, and detailed audit trails.
+- **Preprocessing & Feature Engineering**: Stateful fit/transform operations for interactions, ratio features, polynomial terms, logarithmic transformations, and datetime extraction.
+- **Rule Engine**: Quality validation framework with built-in rules, severity levels, and category classifications.
+- **Report Engine**: Structured report generation, rendering (Text, JSON), and exporting (String, File).
+- **Pipeline Engine**: Execution workflow orchestration with step timing and metadata tracking.
+
+---
+
+## Capabilities
+
+| Area | Component | Key Functionality |
+| :--- | :--- | :--- |
+| **Core & High-Level API** | `Cleaner`, `CleanerConfig` | Unified entry point for `.inspect()`, `.plan()`, and `.clean(..., dry_run=True)` |
+| **Dataset Health & Inspection** | `Cleaner.inspect()`, `MissingValueInspector`, `DuplicateInspector`, `DatatypeInspector`, `MemoryInspector`, `StatisticsInspector` | Dataset Health Score (0-100), severity scoring, memory estimation, distribution stats |
+| **Recommendations & Planning** | `CleaningPlan`, `IssueDetector` | Human-readable recommendations, issue severity classification (`critical`, `warning`, `info`), previewable execution plan |
+| **Cleaning Engine** | `CleaningEngine`, `DropMissingRows`, `DropMissingColumns`, `FillMissing`, `DropDuplicates`, `DropColumns` | Deterministic cleaning operations with `dry_run` support, `OperationResult`, and immutable audit log |
+| **Preprocessing** | `FeatureEngineeringEngine`, `ColumnInteraction`, `RatioFeature`, `PolynomialFeature`, `LogFeature`, `DatetimeFeatures` | Stateful fit/transform feature generation preserving dataset indices |
+| **Rules** | `RuleEngine`, `RuleRegistry`, `Rule`, `register_builtin_rules` | Data quality rules, severity levels (`info`, `warning`, `error`, `critical`), custom rules |
+| **Reporting** | `ReportEngine`, `TextRenderer`, `JSONRenderer`, `StringExporter`, `FileExporter` | Structured immutable reports with multi-format rendering and exporting |
+| **Pipeline** | `PipelineEngine`, `CallableStep`, `TransformStep` | Sequenced workflow execution with step duration and row/column metrics |
+
+---
+
+## Requirements
+
+- **Python**: `>=3.11`
+- **Core Dependencies**:
+  - `numpy >= 1.24.0`
+  - `pandas >= 2.0.0`
+  - `scipy >= 1.10.0`
+  - `rich >= 13.0.0`
+  - `pydantic >= 2.0.0`
+
+---
+
+## Installation
+
+### Standard User Installation
+
+Install `sanitizepy` using `pip`:
+
+```bash
+pip install sanitizepy
+```
+
+Or via `python -m pip`:
+
+```bash
+python -m pip install sanitizepy
+```
+
+### Developer / Contributor Installation
+
+For local development or contributing to the codebase, clone the repository and perform an editable installation with development dependencies:
+
+```bash
+git clone https://github.com/tahahssn/sanitizepy.git
+cd sanitizepy
+pip install -e .[dev]
+```
+
+---
+
+## Quick Start — High-Level API
+
+The recommended entry point is the `Cleaner` class or the module-level convenience functions `inspect()`, `plan()`, and `clean()`.
+
+```python
+import pandas as pd
+from sanitizepy import Cleaner
+
+# Load your dataset
+df = pd.read_csv("your_data.csv")
+
+# 1. Inspect — Understand what's wrong
+c = Cleaner()
+report = c.inspect(df)
+report.show()                     # Rich terminal health report
+
+print(f"Health Score: {report.health_score}/100")
+print(f"Critical Issues: {len(report.critical_issues)}")
+print(f"Recommendations: {len(report.recommendations)}")
+
+# 2. Plan — Generate a previewable cleaning plan
+plan = c.plan(report)
+plan.show()                       # Tabular plan preview
+
+# Optional: disable or enable specific steps
+plan.disable(2)                   # Disable step #2
+plan.enable(2)                    # Re-enable step #2
+
+# 3. Clean — Execute with dry-run or for real
+# Dry run: see what WOULD happen without changing data
+dry_result = c.clean(df, plan=plan, dry_run=True)
+print(dry_result.summary())
+
+# Apply for real
+result = c.clean(df, plan=plan, dry_run=False)
+cleaned_df = result.data
+
+print(result.summary())           # Human-readable summary
+print(result.audit_log)           # JSON-serializable audit trail
+```
+
+### Convenience Functions
+
+```python
+from sanitizepy import inspect, plan, clean
+
+report = inspect(df)
+cleaning_plan = plan(report)
+result = clean(df, cleaning_plan=cleaning_plan, dry_run=True)
+```
+
+---
+
+## Advanced Usage — Direct Engine Access
+
+For granular control, use the individual engines directly:
+
+```python
+from sanitizepy.cleaning import CleaningEngine, DropDuplicates, FillMissing
+from sanitizepy.inspection import MissingValueInspector
+
+# Read-only inspection
+inspector = MissingValueInspector()
+inspection_result = inspector.inspect(df)
+
+# Manual cleaning engine
+engine = CleaningEngine([
+    FillMissing(value=0.0, subset=["numeric_column"]),
+    DropDuplicates(keep="first"),
+])
+
+# Run with full result tracking
+result = engine.run_with_result(df, dry_run=False)
+print(result.summary())
+print(result.audit_log)
+```
+
+---
+
+## Architecture & Design
+
+`sanitizepy` adopts the following transparent workflow:
+**Detect → Explain → Recommend → Preview → Apply → Validate → Audit**
+
+```text
+               ┌───────────────────────┐
+               │      Dataset          │
+               └───────────┬───────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │    Dataset Profiler /     │
+             │    Issue Detector         │ (Read-Only)
+             └─────────────┬─────────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │   Recommendation Engine   │ (Explainable)
+             └─────────────┬─────────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │     Cleaning Plan         │ (Previewable)
+             └─────────────┬─────────────┘
+                           │
+                    user approves
+                           │
+             ┌─────────────┴─────────────┐
+             │  Transformation Engine    │ (Deterministic)
+             └─────────────┬─────────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │    Validation / Audit     │ (Auditable)
+             └───────────────────────────┘
+```
+
+---
+
+## Documentation
+
+Detailed documentation is available in the `docs/` directory:
+
+- [Installation Guide](docs/installation.md): Requirements, virtual environments, installation commands, verification, and upgrade procedures.
+- [Quick Start Guide](docs/quickstart.md): Step-by-step examples for inspection, cleaning, feature engineering, rules, reporting, and pipelines.
+- [API Reference](docs/api.md): Complete technical API documentation for classes, functions, dataclasses, models, and exceptions.
+
+---
+
+## Development & Testing
+
+To run the project test suite or linting tools:
+
+### Run Tests
+
+```bash
+pytest
+```
+
+### Code Formatting & Linting
+
+```bash
+black --check src tests
+ruff check src tests
+mypy src
+```
+
+---
+
+## License
+
+`sanitizepy` is distributed under the terms of the [MIT License](LICENSE).
+

sanitizepy-0.1.0/README.md

@@ -0,0 +1,227 @@
+
+# sanitizepy
+
+An open-source Python engine for automated tabular data quality inspection, explainable cleaning, and preprocessing.
+
+---
+
+## Overview
+
+`sanitizepy` provides modular, high-performance data engineering components built on top of `pandas`, `numpy`, `scipy`, `rich`, and `pydantic`. The library is designed around a transparent **Detect → Explain → Recommend → Preview → Apply → Validate → Audit** workflow.
+
+`sanitizepy` separates responsibilities into dedicated subsystems:
+- **Core Engine & High-Level API**: Centralized `Cleaner` entry point supporting `.inspect()`, `.plan()`, and `.clean(..., dry_run=True)`.
+- **Dataset Health & Inspection**: Read-only dataset analysis covering completeness, uniqueness, consistency, validity, datatypes, memory consumption, and statistical distributions with a composite **Dataset Health Score (0–100)**.
+- **Explainable Recommendations & Planning**: Rule-based issue detection with human-readable explanations (`WHAT`, `WHY`, `SEVERITY`, `EVIDENCE`, `RECOMMENDATION`) and previewable `CleaningPlan` instances.
+- **Cleaning Engine**: Safe, deterministic dataset transformations with dry-run support, before/after impact metrics, and detailed audit trails.
+- **Preprocessing & Feature Engineering**: Stateful fit/transform operations for interactions, ratio features, polynomial terms, logarithmic transformations, and datetime extraction.
+- **Rule Engine**: Quality validation framework with built-in rules, severity levels, and category classifications.
+- **Report Engine**: Structured report generation, rendering (Text, JSON), and exporting (String, File).
+- **Pipeline Engine**: Execution workflow orchestration with step timing and metadata tracking.
+
+---
+
+## Capabilities
+
+| Area | Component | Key Functionality |
+| :--- | :--- | :--- |
+| **Core & High-Level API** | `Cleaner`, `CleanerConfig` | Unified entry point for `.inspect()`, `.plan()`, and `.clean(..., dry_run=True)` |
+| **Dataset Health & Inspection** | `Cleaner.inspect()`, `MissingValueInspector`, `DuplicateInspector`, `DatatypeInspector`, `MemoryInspector`, `StatisticsInspector` | Dataset Health Score (0-100), severity scoring, memory estimation, distribution stats |
+| **Recommendations & Planning** | `CleaningPlan`, `IssueDetector` | Human-readable recommendations, issue severity classification (`critical`, `warning`, `info`), previewable execution plan |
+| **Cleaning Engine** | `CleaningEngine`, `DropMissingRows`, `DropMissingColumns`, `FillMissing`, `DropDuplicates`, `DropColumns` | Deterministic cleaning operations with `dry_run` support, `OperationResult`, and immutable audit log |
+| **Preprocessing** | `FeatureEngineeringEngine`, `ColumnInteraction`, `RatioFeature`, `PolynomialFeature`, `LogFeature`, `DatetimeFeatures` | Stateful fit/transform feature generation preserving dataset indices |
+| **Rules** | `RuleEngine`, `RuleRegistry`, `Rule`, `register_builtin_rules` | Data quality rules, severity levels (`info`, `warning`, `error`, `critical`), custom rules |
+| **Reporting** | `ReportEngine`, `TextRenderer`, `JSONRenderer`, `StringExporter`, `FileExporter` | Structured immutable reports with multi-format rendering and exporting |
+| **Pipeline** | `PipelineEngine`, `CallableStep`, `TransformStep` | Sequenced workflow execution with step duration and row/column metrics |
+
+---
+
+## Requirements
+
+- **Python**: `>=3.11`
+- **Core Dependencies**:
+  - `numpy >= 1.24.0`
+  - `pandas >= 2.0.0`
+  - `scipy >= 1.10.0`
+  - `rich >= 13.0.0`
+  - `pydantic >= 2.0.0`
+
+---
+
+## Installation
+
+### Standard User Installation
+
+Install `sanitizepy` using `pip`:
+
+```bash
+pip install sanitizepy
+```
+
+Or via `python -m pip`:
+
+```bash
+python -m pip install sanitizepy
+```
+
+### Developer / Contributor Installation
+
+For local development or contributing to the codebase, clone the repository and perform an editable installation with development dependencies:
+
+```bash
+git clone https://github.com/tahahssn/sanitizepy.git
+cd sanitizepy
+pip install -e .[dev]
+```
+
+---
+
+## Quick Start — High-Level API
+
+The recommended entry point is the `Cleaner` class or the module-level convenience functions `inspect()`, `plan()`, and `clean()`.
+
+```python
+import pandas as pd
+from sanitizepy import Cleaner
+
+# Load your dataset
+df = pd.read_csv("your_data.csv")
+
+# 1. Inspect — Understand what's wrong
+c = Cleaner()
+report = c.inspect(df)
+report.show()                     # Rich terminal health report
+
+print(f"Health Score: {report.health_score}/100")
+print(f"Critical Issues: {len(report.critical_issues)}")
+print(f"Recommendations: {len(report.recommendations)}")
+
+# 2. Plan — Generate a previewable cleaning plan
+plan = c.plan(report)
+plan.show()                       # Tabular plan preview
+
+# Optional: disable or enable specific steps
+plan.disable(2)                   # Disable step #2
+plan.enable(2)                    # Re-enable step #2
+
+# 3. Clean — Execute with dry-run or for real
+# Dry run: see what WOULD happen without changing data
+dry_result = c.clean(df, plan=plan, dry_run=True)
+print(dry_result.summary())
+
+# Apply for real
+result = c.clean(df, plan=plan, dry_run=False)
+cleaned_df = result.data
+
+print(result.summary())           # Human-readable summary
+print(result.audit_log)           # JSON-serializable audit trail
+```
+
+### Convenience Functions
+
+```python
+from sanitizepy import inspect, plan, clean
+
+report = inspect(df)
+cleaning_plan = plan(report)
+result = clean(df, cleaning_plan=cleaning_plan, dry_run=True)
+```
+
+---
+
+## Advanced Usage — Direct Engine Access
+
+For granular control, use the individual engines directly:
+
+```python
+from sanitizepy.cleaning import CleaningEngine, DropDuplicates, FillMissing
+from sanitizepy.inspection import MissingValueInspector
+
+# Read-only inspection
+inspector = MissingValueInspector()
+inspection_result = inspector.inspect(df)
+
+# Manual cleaning engine
+engine = CleaningEngine([
+    FillMissing(value=0.0, subset=["numeric_column"]),
+    DropDuplicates(keep="first"),
+])
+
+# Run with full result tracking
+result = engine.run_with_result(df, dry_run=False)
+print(result.summary())
+print(result.audit_log)
+```
+
+---
+
+## Architecture & Design
+
+`sanitizepy` adopts the following transparent workflow:
+**Detect → Explain → Recommend → Preview → Apply → Validate → Audit**
+
+```text
+               ┌───────────────────────┐
+               │      Dataset          │
+               └───────────┬───────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │    Dataset Profiler /     │
+             │    Issue Detector         │ (Read-Only)
+             └─────────────┬─────────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │   Recommendation Engine   │ (Explainable)
+             └─────────────┬─────────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │     Cleaning Plan         │ (Previewable)
+             └─────────────┬─────────────┘
+                           │
+                    user approves
+                           │
+             ┌─────────────┴─────────────┐
+             │  Transformation Engine    │ (Deterministic)
+             └─────────────┬─────────────┘
+                           │
+             ┌─────────────┴─────────────┐
+             │    Validation / Audit     │ (Auditable)
+             └───────────────────────────┘
+```
+
+---
+
+## Documentation
+
+Detailed documentation is available in the `docs/` directory:
+
+- [Installation Guide](docs/installation.md): Requirements, virtual environments, installation commands, verification, and upgrade procedures.
+- [Quick Start Guide](docs/quickstart.md): Step-by-step examples for inspection, cleaning, feature engineering, rules, reporting, and pipelines.
+- [API Reference](docs/api.md): Complete technical API documentation for classes, functions, dataclasses, models, and exceptions.
+
+---
+
+## Development & Testing
+
+To run the project test suite or linting tools:
+
+### Run Tests
+
+```bash
+pytest
+```
+
+### Code Formatting & Linting
+
+```bash
+black --check src tests
+ruff check src tests
+mypy src
+```
+
+---
+
+## License
+
+`sanitizepy` is distributed under the terms of the [MIT License](LICENSE).
+

sanitizepy-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sanitizepy"
+version = "0.1.0"
+description = "An open-source Python engine for automated tabular data quality inspection, explainable cleaning, and preprocessing."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+
+authors = [
+    { name = "Syed Muhammad Taha Hassan" }
+]
+
+keywords = [
+    "machine-learning",
+    "data-quality",
+    "data-cleaning",
+    "eda",
+    "feature-engineering",
+    "preprocessing",
+    "pandas",
+    "python",
+    "data-analysis"
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries"
+]
+
+dependencies = [
+    "numpy>=1.24.0,<2.3.0",
+    "pandas>=2.0.0",
+    "scipy>=1.10.0",
+    "rich>=13.0.0",
+    "pydantic>=2.0.0"
+]
+
+[project.optional-dependencies]
+
+dev = [
+    "black>=24.0.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "pandas-stubs>=2.0.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0"
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "SIM",
+    "C4"
+]
+
+ignore = []
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src"
+]
+testpaths = [
+    "tests"
+]
+addopts = "-ra"

sanitizepy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sanitizepy-0.1.0/src/sanitizepy/__init__.py

@@ -0,0 +1,54 @@
+"""
+sanitizepy
+
+An open-source Python engine for automated tabular data quality inspection,
+explainable cleaning, and preprocessing.
+"""
+
+from __future__ import annotations
+
+from .api import (
+    DEFAULT_CONFIG,
+    VERSION,
+    VERSION_INFO,
+    Cleaner,
+    CleanerConfig,
+    CleanerError,
+    CleaningEngine,
+    CleaningPlan,
+    CleaningResult,
+    ConfigurationError,
+    DatasetHealthReport,
+    DatasetIssue,
+    DataValidationError,
+    EngineError,
+    OperationResult,
+    clean,
+    get_version,
+    inspect,
+    plan,
+)
+
+__all__ = [
+    "Cleaner",
+    "inspect",
+    "plan",
+    "clean",
+    "DatasetHealthReport",
+    "DatasetIssue",
+    "CleaningPlan",
+    "CleaningResult",
+    "OperationResult",
+    "CleaningEngine",
+    "CleanerConfig",
+    "DEFAULT_CONFIG",
+    "CleanerError",
+    "ConfigurationError",
+    "DataValidationError",
+    "EngineError",
+    "VERSION",
+    "VERSION_INFO",
+    "get_version",
+]
+
+__version__ = VERSION