Metadata-Version: 2.4
Name: datacrease
Version: 1.0.0
Summary: Das deterministische Bügeleisen an Daten-Kupplungen: Sanitization, Hash-Guard, Pufferung und Audit-Trails.
Author: DataCrease Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/datacrease/datacrease
Project-URL: Repository, https://github.com/datacrease/datacrease
Project-URL: Issues, https://github.com/datacrease/datacrease/issues
Keywords: data-quality,sanitization,data-cleansing,hash-guard,audit-trail,zero-dependency,streaming,data-pipeline
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Dynamic: license-file

# DataCrease 🧺⚡ (Das Daten-Bügeleisen)

> **"Lieber 2 Millisekunden Glättung an der Schnittstelle investieren, als ein gecrashtes Folgesystem im Nachgang."**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)]()
[![Tests: 83/83 Green](https://img.shields.io/badge/Tests-83%2F83%20passed-success.svg)]()
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero%20External-orange.svg)]()
[![Latency: P99 340µs](https://img.shields.io/badge/Latency%20P99-340%C2%A0%C2%B5s-blueviolet.svg)]()
[![Throughput: 1.879 Rec/s](https://img.shields.io/badge/Throughput-1.879%C2%A0Records%2Fs-success.svg)]()

---

## 🎯 Elevator Pitch

**DataCrease** ist ein kompromisslos schnelles, deterministisches Python-Toolkit für **Data-Sanitization, Ingestion-Pufferung, kryptografische Unveränderlichkeit und lückenlose Audit-Trails** direkt an Daten-Kupplungen (APIs, Webhooks, Microservices, LLM-Tools, IoT-Streams).

Herkömmliche Validatoren wie Pydantic werfen beim kleinsten Whitespace-Fehler oder Formatbruch sofort harte Exceptions (*Fail-Fast*), während Datenanalyse-Tools wie Pandas für Echtzeit-Kupplungen viel zu schwergewichtig sind. 

**DataCrease wählt den dritten Weg:**
Anstatt Schnittstellen crashen zu lassen, bügelt DataCrease typischen Datenmüll (unsichtbare Steuerzeichen, chaotische Whitespaces, deutsche/US-Zahlenformate, unbereinigte Datumsangaben, Trennlinien) in **unter 0,2 Millisekunden** deterministisch glatt, prüft Schwellenwerte, versiegelt jeden Datensatz mit einem manipulationssicheren **SHA-256 Receipt** und absorbiert Lastspitzen über einen integrierten Ring-Puffer – **zu 100% in purem Python und ohne eine einzige externe Dependency**.

---

## ⚡ Kernfunktionen

- 🧺 **The Iron (Deterministischer Glätter):** Bereinigt Unicode-NFC, entfernt unsichtbare ASCII-Steuerzeichen (0–31, 127), normalisiert Zahlen (EU/US, Währungssymbole, Tausendertrenner), vereinheitlicht Datumsformate deterministisch auf ISO-8601 UTC und bügelt Trennmüll (`strip_decorations`).
- 🛡️ **The Checker & CreaseErrorCode:** Typisierte Integer-Fehlercodes (`CreaseErrorCode` 1xx–4xx) für intuitive IDE-Autovervollständigung (`if CreaseErrorCode.MISSING_REQUIRED_FIELD in result.error_codes`), Schwellenwerte, Whitelists und ReDoS-sichere Regex-Prüfungen.
- 🔒 **The Hash-Guard:** Kanonische deterministische JSON-Serialisierung und Ausstellung manipulationssicherer `Receipt`-Objekte mit SHA-256-Prüfsummen für Vorher/Nachher-Lineage und Latenz-Tracking.
- 🌊 **O(1) Memory Streaming:** Lazy Generator (`process_stream`, `process_file`) zur speicherschonenden Verarbeitung gigabytegroßer JSONL-Dateien inklusive automatischer Filterung von Strukturmüll (`DROPPED_JUNK_LINE`).
- 🔍 **Dry-Run & Inspect-Modus:** Risikofreie Datenprüfung via `iron.inspect()` oder `datacrease check --dry-run` ohne Mutation der Originaldaten.
- 🚨 **Präzise Diagnostik:** Typisierte `DataCreaseCorruptPayloadError`-Exceptions mit exakter Zeilennummer, Byte-Offset und Quellcode-Ausschnitt bei korruptem JSON.
- 🗄️ **Ring-Buffer & JSONL-Audit:** Thread-sicherer FIFO-Puffer mit konfigurierbaren Überlauf-Strategien (`DROP_OLDEST`, `REJECT_NEWEST`, `RAISE_ERROR`) und atomarer Append-Only JSONL-Audit-Logger.

---

## 📊 Differenzierungsmatrix

| Kriterium | Pydantic / Marshmallow | Pandas / Polars | Great Expectations | **DataCrease** |
| :--- | :--- | :--- | :--- | :--- |
| **Philosophie bei Schmutz** | Wirft Exceptions (`ValidationError`) | Erfordert manuelle Vorbereinigung | Meldet Fehler ex-post im Batch | **Bügelt Schmutz deterministisch glatt** |
| **Audit-Trail & Lineage** | ❌ Nein | ❌ Nein | ⚠️ Nur Testberichte | ✅ **Kryptografischer Hash-Guard (SHA-256)** |
| **Burst-Pufferung** | ❌ Nein | ❌ Nein | ❌ Nein | ✅ **In-Memory Ring-Buffer integriert** |
| **Fehler-Diagnostik** | Textmeldungen | Index-Fehler | Suite-Reports | ✅ **Typisierte `CreaseErrorCode` (1xx–4xx)** |
| **Latenz pro Record** | Mikrosekunden | Hoch (>500ms Import/Batch) | Schwergewicht (Sekunden) | ✅ **P50: 193 µs / P99: 340 µs** |
| **Memory Footprint** | Mittel | Hoch (RAM-Kopien) | Hoch | ✅ **$O(1)$ Memory Streaming** |
| **Dependencies & Ballast** | Rust/C-Bindings | Schwer (>100 MB) | Sehr schwer (>50 Pakete) | ✅ **Zero External Dependencies** |

---

## 📈 Benchmark-Ergebnisse (10.000 Records E2E)

Gemessen auf dem vollständigen Durchlauf (`Iron` $\to$ `Checker` $\to$ `HashGuard` $\to$ atomarer `AuditLogger`):

```text
=================================================================
--- DATACREASE BENCHMARK: 10.000 RECORDS DURCH DIE E2E-SCHLEUSE ---
=================================================================
Gesamtdauer:         5.323 Sekunden
Durchsatz:           1.879 Records / Sekunde
Ø Latenz:            201.3 µs (0.201 ms)
Median (P50):        193 µs   (0.193 ms)
90. Perzentil (P90): 247 µs   (0.247 ms)
99. Perzentil (P99): 340 µs   (0.340 ms)
Budget-Limit:        2.000 µs (2.000 ms)  --> 5,9x schneller als das Limit!
=================================================================
```

- **Fuzzing-Schredder:** 5.000 böswillig formatierte Datensätze (Zero-Width Spaces, unsichtbare ASCII-Steuerzeichen, extremes Whitespace-Chaos, ungültige Datumsangaben, NaN/Infinity-Strings) $\to$ **0 Crashes / 0 ungefangene Exceptions**.
- **Concurrency-Stresstest:** 3.000 Records über parallele Worker-Threads auf RingBuffer und Pipeline $\to$ **0 Deadlocks, 0 Race Conditions**.

---

## 📦 Installation

DataCrease benötigt Python 3.10 oder höher und hat **keine externen Abhängigkeiten**:

```bash
pip install datacrease
```

Oder direkt aus dem Repository:

```bash
git clone https://github.com/datacrease/datacrease.git
cd datacrease
pip install .
```

---

## 🚀 Quickstart: Python API

### 1. Grundlegende Pipeline-Schleuse

```python
from datacrease import DataCrease, Iron, Checker, Status, CreaseErrorCode

# 1. Pipeline konfigurieren
pipeline = DataCrease(
    iron=Iron(locale_hint="EU", collapse_whitespace=True),
    checker=Checker(
        required_fields=["id", "device_id"],
        numeric_ranges={"temperature": (-40.0, 85.0)},
        regex_rules={"device_id": r"^DEV-\d{3}$"}
    ),
    schema_hints={"temperature": "number", "timestamp": "date"}
)

# 2. Unsauberer Rohdaten-Eingang
raw_record = {
    "id": " 1001 ",
    "device_id": " DEV-042 \n",
    "temperature": " 21,50 °C ",
    "timestamp": " 15.09.2026 18:02:47 ",
    "notes": " N/A "
}

# 3. Durch die Schleuse schleusen
res = pipeline.process(raw_record)

print(res.status)               # Status.CLEANED
print(res.cleaned)
# {
#     "id": "1001",
#     "device_id": "DEV-042",
#     "temperature": 21.5,
#     "timestamp": "2026-09-15T18:02:47Z",
#     "notes": None
# }

# 4. Kryptografischen Beleg (Receipt) auswerten
print(res.receipt.sha256_raw)   # SHA-256 Prüfsumme des Eingangs
print(res.receipt.sha256_clean) # SHA-256 Prüfsumme des geglätteten Outputs
print(f"Dauer: {res.receipt.latency_us} µs")
```

### 2. Typisierte Fehlerbehandlung mit `CreaseErrorCode`

```python
from datacrease import CreaseErrorCode

result = pipeline.process({"temperature": "ungültig"})

if result.status == Status.DROPPED:
    if CreaseErrorCode.MISSING_REQUIRED_FIELD in result.error_codes:
        print("Pflichtfeld fehlt!")
    if CreaseErrorCode.UNPARSEABLE_NUMBER in result.error_codes:
        print("Temperaturwert konnte nicht als Zahl interpretiert werden.")
```

### 3. $O(1)$-Memory Streaming für große Dateien

```python
# Verarbeitet Dateien zeilenweise ohne Speicher-Explosion
for result in pipeline.process_file("huge_dataset.jsonl", stop_on_first_drop=False):
    if result.status != Status.DROPPED:
        save_to_database(result.cleaned)
```

### 4. Risikofreier Dry-Run / Inspect-Modus

```python
from datacrease import Iron

iron = Iron()
# Ermittelt Modifikationen und Hashes, ohne Daten zu mutieren
receipt = iron.inspect({"name": "  Max   Mustermann\r\n", "age": "42 "})
print(receipt.modifications_count) # 2
print(receipt.status)              # Status.CLEANED
```

---

## 💻 CLI-Nutzung

DataCrease bietet ein vollwertiges Command-Line-Interface (`datacrease`):

### Standard-Verarbeitung
```bash
# JSONL-Datei glätten und Audit-Trail mitschreiben
datacrease input.jsonl -o cleaned.jsonl -a audit.jsonl --summary
```

### Dry-Run / Inspect
```bash
# Vorprüfung ohne Dateien zu verändern (Report über Glättungen & Fehler)
datacrease check input.jsonl --dry-run
```

### Unix Pipes & Streaming
```bash
# Reines Stdin/Stdout-Streaming mit eingebetteten Receipts
cat raw_stream.jsonl | datacrease --with-receipts > output.jsonl
```

### Legacy ASCII-Modus
```bash
# Umlaute und Sonderzeichen für Legacy-Systeme transliterieren (ä -> ae, € -> EUR)
datacrease input.jsonl -o ascii_cleaned.jsonl --ascii-only
```

---

## 🛠️ Entwicklung & Testen

```bash
# Schnelle Dev-Testsuite ausführen (80 Tests in ~0.34s)
pytest

# Isolierte Performance-Benchmarks ausführen (10.000 Records & Fuzzing)
pytest -m benchmark

# Alle Tests inklusive Benchmarks ausführen
pytest -o addopts=""
```

---

## 📄 Lizenz

Lizenziert unter der [MIT-Lizenz](LICENSE) (Haftungsausschluss gemäß "AS IS").

