DataCrease 🧺⚡ (Das Daten-Bügeleisen)

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

---

🎯 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):

=================================================================
--- 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:

pip install datacrease

Oder direkt aus dem Repository:

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

---

🚀 Quickstart: Python API

1. Grundlegende Pipeline-Schleuse

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

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

# 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

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

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

Dry-Run / Inspect

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

Unix Pipes & Streaming

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

Legacy ASCII-Modus

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

---

🛠️ Entwicklung & Testen

# 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 (Haftungsausschluss gemäß "AS IS").