datacrease 1.0.0__py3-none-any.whl

datacrease/__init__.py

@@ -0,0 +1,58 @@
+"""DataCrease: Das deterministische Daten-Bügeleisen.
+
+Sanitization, Pufferung, Hash-Guard und Audit-Trails an Daten-Kupplungen.
+"""
+
+from datacrease.audit import AuditLogger
+from datacrease.buffer import OverflowPolicy, RingBuffer
+from datacrease.config import IronConfig
+from datacrease.exceptions import (
+    BufferOverflowError,
+    ConfigError,
+    DataCreaseCorruptPayloadError,
+    DataCreaseError,
+    RegexConfigError,
+)
+from datacrease.hash_guard import HashGuard
+from datacrease.iron import Iron
+from datacrease.models import (
+    CheckerResult,
+    CreaseErrorCode,
+    FieldChangeType,
+    FieldModification,
+    IronResult,
+    ProcessingResult,
+    Receipt,
+    Status,
+)
+from datacrease.pipeline import DataCrease
+from datacrease.stream import StreamProcessor, StreamStats
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "DataCrease",
+    "Iron",
+    "IronConfig",
+    "Checker",
+    "HashGuard",
+    "RingBuffer",
+    "OverflowPolicy",
+    "DataCreaseError",
+    "DataCreaseCorruptPayloadError",
+    "BufferOverflowError",
+    "AuditLogger",
+    "StreamProcessor",
+    "StreamStats",
+    "ConfigError",
+    "RegexConfigError",
+    "Status",
+    "CreaseErrorCode",
+    "FieldChangeType",
+    "FieldModification",
+    "IronResult",
+    "CheckerResult",
+    "ProcessingResult",
+    "Receipt",
+]

datacrease/audit.py

@@ -0,0 +1,145 @@
+"""Audit-Logger: Strukturierter Append-Only JSONL-Writer und Metrik-Sammler für DataCrease.
+
+Protokolliert jeden Datensatz mit seinem manipulationssicheren Receipt und aggregiert Latenzen.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional, Union
+
+from datacrease.models import Receipt, Status
+
+
+class AuditLogger:
+    """
+    Append-Only JSONL Audit-Logger:
+    - Schreibt lückenlose Audit-Trails direkt ins JSON-Lines-Format (.jsonl).
+    - Thread-sicher durch internes Datei-Locking.
+    - Führt Echtzeit-Metriken (Total, Passed, Cleaned, Dropped, Ø Latenz in µs).
+    """
+
+    def __init__(
+        self,
+        file_path: Optional[Union[str, Path]] = None,
+        auto_flush: bool = True,
+    ):
+        """
+        :param file_path: Zieldatei für den JSONL-Audit-Trail. Falls None, wird nur im Speicher mitgezählt.
+        :param auto_flush: Sofortiges Flushen auf die Festplatte bei jedem Schreibvorgang
+        """
+        self.file_path: Optional[Path] = Path(file_path) if file_path else None
+        self.auto_flush = auto_flush
+        self._lock = threading.Lock()
+
+        # Metrik-Zähler
+        self._total_processed = 0
+        self._total_passed = 0
+        self._total_cleaned = 0
+        self._total_dropped = 0
+        self._total_latency_us = 0
+        self._counters: Dict[str, int] = {"DROPPED_JUNK_LINE": 0}
+
+        # Datei initialisieren / Verzeichnis erstellen, falls Pfad angegeben
+        if self.file_path:
+            self.file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(
+        self,
+        receipt: Receipt,
+        record_preview: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Protokolliert ein Receipt inklusive optionaler Metadaten atomar.
+
+        :param receipt: Ausgestelltes Receipt-Objekt des Hash-Guards
+        :param record_preview: Optionale Vorschau auf die Daten (falls Audit Rohdaten beinhalten soll)
+        :param metadata: Zusätzliche Kontext-Informationen (z. B. Source-System, Batch-ID)
+        :return: Das geschriebene Audit-Eintrag-Dictionary
+        """
+        entry: Dict[str, Any] = {
+            "record_id": receipt.record_id,
+            "status": receipt.status.value,
+            "sha256_raw": receipt.sha256_raw,
+            "sha256_clean": receipt.sha256_clean,
+            "modifications_count": receipt.modifications_count,
+            "timestamp_utc": receipt.timestamp_utc,
+            "latency_us": receipt.latency_us,
+            "errors": list(receipt.errors),
+        }
+
+        if record_preview is not None:
+            entry["record_preview"] = record_preview
+
+        if metadata:
+            entry["metadata"] = metadata
+
+        with self._lock:
+            # Metriken aktualisieren
+            self._total_processed += 1
+            if receipt.status == Status.PASSED:
+                self._total_passed += 1
+            elif receipt.status == Status.CLEANED:
+                self._total_cleaned += 1
+            elif receipt.status == Status.DROPPED:
+                self._total_dropped += 1
+
+            self._total_latency_us += max(0, receipt.latency_us)
+
+            # Dateiausgabe (Append-Only JSONL)
+            if self.file_path:
+                json_line = json.dumps(entry, ensure_ascii=False) + "\n"
+                with open(self.file_path, "a", encoding="utf-8") as f:
+                    f.write(json_line)
+                    if self.auto_flush:
+                        f.flush()
+
+        return entry
+
+    def increment_counter(self, name: str, count: int = 1) -> int:
+        """Erhöht einen benannten Zähler (z. B. DROPPED_JUNK_LINE) thread-sicher."""
+        with self._lock:
+            self._counters[name] = self._counters.get(name, 0) + count
+            return self._counters[name]
+
+    def record_dropped_junk_line(self, count: int = 1) -> int:
+        """Protokolliert übersprungene Strukturmüll-/Trennlinien."""
+        return self.increment_counter("DROPPED_JUNK_LINE", count)
+
+    def get_metrics(self) -> Dict[str, Any]:
+        """Liefert die aktuellen Aggregats-Metriken."""
+        with self._lock:
+            avg_latency = (
+                self._total_latency_us / self._total_processed
+                if self._total_processed > 0
+                else 0.0
+            )
+            return {
+                "total_processed": self._total_processed,
+                "total_passed": self._total_passed,
+                "total_cleaned": self._total_cleaned,
+                "total_dropped": self._total_dropped,
+                "total_latency_us": self._total_latency_us,
+                "avg_latency_us": round(avg_latency, 2),
+                "dropped_junk_lines": self._counters.get("DROPPED_JUNK_LINE", 0),
+                "counters": dict(self._counters),
+            }
+
+    @classmethod
+    def read_entries(cls, file_path: Union[str, Path]) -> Iterator[Dict[str, Any]]:
+        """
+        Generator zum streaming-effizienten Einlesen einer JSONL-Audit-Datei.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            return
+
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line_str = line.strip()
+                if line_str:
+                    yield json.loads(line_str)

datacrease/buffer.py

@@ -0,0 +1,148 @@
+"""Ring-Buffer: Thread-sicherer In-Memory FIFO-Puffer für DataCrease.
+
+Fängt Lastspitzen ab, wenn Erzeuger schneller senden als Folgesysteme konsumieren können.
+"""
+
+from __future__ import annotations
+
+import collections
+import threading
+from enum import Enum
+from typing import Any, Generic, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class OverflowPolicy(str, Enum):
+    """Verhalten bei vollem Puffer."""
+    DROP_OLDEST = "DROP_OLDEST"      # Ältestes Element stillschweigend verwerfen (Standard für Echtzeit-Streaming)
+    REJECT_NEWEST = "REJECT_NEWEST"  # Neues Element ablehnen (Rückgabe False)
+    RAISE_ERROR = "RAISE_ERROR"      # Löst BufferOverflowError aus
+
+
+from datacrease.exceptions import BufferOverflowError
+
+
+class RingBuffer(Generic[T]):
+    """
+    Thread-sicherer FIFO Ring-Puffer mit konfigurierbarer Kapazität und Überlaufstrategie.
+    """
+
+    def __init__(
+        self,
+        capacity: int = 1000,
+        overflow_policy: OverflowPolicy = OverflowPolicy.DROP_OLDEST,
+    ):
+        """
+        :param capacity: Maximale Anzahl an Elementen im Puffer (> 0)
+        :param overflow_policy: Verhalten bei Erreichen der Maximalkapazität
+        """
+        if capacity <= 0:
+            raise ValueError(f"Kapazität muss positiv sein, erhalten: {capacity}")
+
+        self.capacity = capacity
+        self.overflow_policy = overflow_policy
+        self._deque: collections.deque[T] = collections.deque(maxlen=capacity if overflow_policy == OverflowPolicy.DROP_OLDEST else None)
+        self._lock = threading.RLock()
+
+        # Metriken
+        self._total_pushed = 0
+        self._total_popped = 0
+        self._total_dropped = 0
+
+    def push(self, item: T) -> bool:
+        """
+        Fügt ein Element in den Puffer ein.
+
+        :param item: Einzupflegendes Element
+        :return: True, wenn das Element aufgenommen wurde, False wenn abgewiesen (bei REJECT_NEWEST)
+        :raises BufferOverflowError: Wenn der Puffer voll ist und RAISE_ERROR konfiguriert ist
+        """
+        with self._lock:
+            current_size = len(self._deque)
+
+            if current_size >= self.capacity:
+                if self.overflow_policy == OverflowPolicy.REJECT_NEWEST:
+                    self._total_dropped += 1
+                    return False
+                elif self.overflow_policy == OverflowPolicy.RAISE_ERROR:
+                    self._total_dropped += 1
+                    raise BufferOverflowError(
+                        f"Ring-Buffer Kapazität von {self.capacity} Elementen erschöpft."
+                    )
+                elif self.overflow_policy == OverflowPolicy.DROP_OLDEST:
+                    # Wenn maxlen gesetzt ist, verwirft deque das älteste Element automatisch,
+                    # wir zählen den Drop für die Auditierung mit.
+                    self._total_dropped += 1
+
+            self._deque.append(item)
+            self._total_pushed += 1
+            return True
+
+    def pop(self, default: Optional[T] = None) -> Optional[T]:
+        """
+        Entnimmt das älteste Element nach dem FIFO-Prinzip.
+
+        :param default: Rückgabewert, falls der Puffer leer ist
+        :return: Ältestes Element oder default
+        """
+        with self._lock:
+            if not self._deque:
+                return default
+            item = self._deque.popleft()
+            self._total_popped += 1
+            return item
+
+    def pop_batch(self, max_items: int) -> List[T]:
+        """
+        Entnimmt bis zu `max_items` Elemente in einem atomaren Durchlauf.
+        """
+        with self._lock:
+            batch: List[T] = []
+            count = min(max_items, len(self._deque))
+            for _ in range(count):
+                batch.append(self._deque.popleft())
+                self._total_popped += 1
+            return batch
+
+    def peek(self, default: Optional[T] = None) -> Optional[T]:
+        """
+        Gibt das älteste Element zurück, ohne es zu entfernen.
+        """
+        with self._lock:
+            if not self._deque:
+                return default
+            return self._deque[0]
+
+    def size(self) -> int:
+        """Gibt die aktuelle Anzahl der Elemente im Puffer zurück."""
+        with self._lock:
+            return len(self._deque)
+
+    def is_full(self) -> bool:
+        """Prüft, ob der Puffer seine maximale Kapazität erreicht hat."""
+        with self._lock:
+            return len(self._deque) >= self.capacity
+
+    def is_empty(self) -> bool:
+        """Prüft, ob der Puffer leer ist."""
+        with self._lock:
+            return len(self._deque) == 0
+
+    def clear(self) -> None:
+        """Leert den gesamten Puffer."""
+        with self._lock:
+            self._deque.clear()
+
+    @property
+    def metrics(self) -> dict:
+        """Gibt Zählerstände für Monitoring und Auditierung zurück."""
+        with self._lock:
+            return {
+                "capacity": self.capacity,
+                "current_size": len(self._deque),
+                "total_pushed": self._total_pushed,
+                "total_popped": self._total_popped,
+                "total_dropped": self._total_dropped,
+                "overflow_policy": self.overflow_policy.value,
+            }

datacrease/checker.py

@@ -0,0 +1,156 @@
+"""Data-Checker: Plausibilitäts-, Pflichtfeld- und Schwellenwert-Validierung.
+
+Deterministische Validierung vor und nach dem Glätten mit strikter Regex-Governance.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Dict, Iterable, List, Optional, Pattern, Set, Tuple, Union
+
+from datacrease.models import CheckerResult, CreaseErrorCode, Status
+
+
+from datacrease.exceptions import ConfigError, RegexConfigError
+
+
+class Checker:
+    """
+    Data-Checker: Prüft Pflichtfelder, Schwellenwerte, Whitelists und reguläre Ausdrücke.
+
+    Hält sich strikt an die DataCrease-Regex-Governance:
+    - Verwendet Python Standard-NFA (`re`, PCRE-Standard).
+    - Kompiliert und validiert alle Regex-Muster strikt bei der Initialisierung.
+    - Fängt fehlerhafte Syntax vor dem Live-Stream als RegexConfigError ab.
+    """
+
+    def __init__(
+        self,
+        required_fields: Optional[Iterable[str]] = None,
+        numeric_ranges: Optional[Dict[str, Tuple[Optional[float], Optional[float]]]] = None,
+        allowed_values: Optional[Dict[str, Set[Any]]] = None,
+        regex_rules: Optional[Dict[str, Union[str, Pattern[str]]]] = None,
+        custom_rules: Optional[Dict[str, Callable[[Any], bool]]] = None,
+    ):
+        """
+        Initialisiert den Checker mit Validierungsregeln.
+
+        :param required_fields: Felder, die zwingend im Record vorhanden und nicht None sein müssen
+        :param numeric_ranges: Schwellenwerte pro Feld als (min_wert, max_wert)
+        :param allowed_values: Erlaubte Werte pro Feld (Whitelist/Enums)
+        :param regex_rules: Reguläre Ausdrücke pro Feld (werden sofort pre-kompiliert)
+        :param custom_rules: Benutzerdefinierte Prädikat-Funktionen (Key -> Bool)
+        :raises RegexConfigError: Falls ein übergebenes Regex-Muster syntaktisch ungültig ist
+        """
+        self.required_fields: Set[str] = set(required_fields) if required_fields else set()
+        self.numeric_ranges: Dict[str, Tuple[Optional[float], Optional[float]]] = numeric_ranges or {}
+        self.allowed_values: Dict[str, Set[Any]] = allowed_values or {}
+        self.custom_rules: Dict[str, Callable[[Any], bool]] = custom_rules or {}
+
+        # Pre-Compilation und Syntax-Validierung der Regex-Regeln
+        self.compiled_regex_rules: Dict[str, Pattern[str]] = {}
+        if regex_rules:
+            for field_name, pattern in regex_rules.items():
+                if isinstance(pattern, re.Pattern):
+                    self.compiled_regex_rules[field_name] = pattern
+                elif isinstance(pattern, str):
+                    try:
+                        self.compiled_regex_rules[field_name] = re.compile(pattern)
+                    except re.error as err:
+                        raise RegexConfigError(
+                            f"CONFIG_ERROR: Ungültiges Regex-Muster für Feld '{field_name}': {pattern!r}. "
+                            f"Fehler: {err}"
+                        ) from err
+                else:
+                    raise ConfigError(
+                        f"CONFIG_ERROR: Regex für Feld '{field_name}' muss ein String oder re.Pattern sein, "
+                        f"erhalten: {type(pattern).__name__}"
+                    )
+
+    def check(self, record: Dict[str, Any]) -> CheckerResult:
+        """
+        Validiert einen Datensatz gegen alle definierten Regeln.
+
+        :param record: Zu prüfendes Datensatz-Dictionary
+        :return: CheckerResult mit Validitätsstatus und detaillierter Fehlerliste
+        """
+        violations: List[str] = []
+        missing_fields: List[str] = []
+        error_codes: List[CreaseErrorCode] = []
+
+        # 1. Pflichtfeld-Prüfung
+        for field in self.required_fields:
+            if field not in record:
+                missing_fields.append(field)
+                violations.append(f"Pflichtfeld '{field}' fehlt.")
+                error_codes.append(CreaseErrorCode.MISSING_REQUIRED_FIELD)
+            elif record[field] is None:
+                missing_fields.append(field)
+                violations.append(f"Pflichtfeld '{field}' ist null.")
+                error_codes.append(CreaseErrorCode.NULL_VALUE_REJECTED)
+
+        # 2. Schwellenwert-Prüfung (Numerische Bereiche)
+        for field, (min_val, max_val) in self.numeric_ranges.items():
+            if field in record and record[field] is not None:
+                val = record[field]
+                try:
+                    num_val = float(val) if not isinstance(val, (int, float)) else float(val)
+                    if min_val is not None and num_val < min_val:
+                        violations.append(
+                            f"Feld '{field}' unterschreitet Schwellenwert: {num_val} < {min_val}"
+                        )
+                        error_codes.append(CreaseErrorCode.NUMERIC_BELOW_MIN)
+                    if max_val is not None and num_val > max_val:
+                        violations.append(
+                            f"Feld '{field}' überschreitet Schwellenwert: {num_val} > {max_val}"
+                        )
+                        error_codes.append(CreaseErrorCode.NUMERIC_ABOVE_MAX)
+                except (ValueError, TypeError):
+                    violations.append(
+                        f"Feld '{field}' ist kein gültiger numerischer Wert für Schwellenwertprüfung: {val!r}"
+                    )
+                    error_codes.append(CreaseErrorCode.UNPARSEABLE_NUMBER)
+
+        # 3. Whitelist / Erlaubte Werte
+        for field, allowed_set in self.allowed_values.items():
+            if field in record and record[field] is not None:
+                val = record[field]
+                if val not in allowed_set:
+                    violations.append(
+                        f"Wert {val!r} in Feld '{field}' ist nicht in erlaubter Wertemenge enthalten."
+                    )
+                    error_codes.append(CreaseErrorCode.DISALLOWED_VALUE)
+
+        # 4. Regex-Muster-Validierung
+        for field, pattern in self.compiled_regex_rules.items():
+            if field in record and record[field] is not None:
+                val_str = str(record[field])
+                if not pattern.search(val_str):
+                    violations.append(
+                        f"Feld '{field}' ({val_str!r}) entspricht nicht dem geforderten Muster {pattern.pattern!r}."
+                    )
+                    error_codes.append(CreaseErrorCode.REGEX_PATTERN_MISMATCH)
+
+        # 5. Benutzerdefinierte Prädikat-Regeln
+        for field, rule_fn in self.custom_rules.items():
+            if field in record and record[field] is not None:
+                try:
+                    if not rule_fn(record[field]):
+                        violations.append(
+                            f"Feld '{field}' verletzt benutzerdefinierte Regel: Wert {record[field]!r}"
+                        )
+                except Exception as ex:
+                    violations.append(
+                        f"Fehler bei Ausführung benutzerdefinierter Regel für Feld '{field}': {ex}"
+                    )
+
+        is_valid = len(violations) == 0
+        status = Status.PASSED if is_valid else Status.DROPPED
+
+        return CheckerResult(
+            is_valid=is_valid,
+            status=status,
+            violations=violations,
+            missing_fields=missing_fields,
+            error_codes=error_codes,
+        )