pycharter 0.0.22__py3-none-any.whl → 0.0.24__py3-none-any.whl

pycharter/quality/tracking/exporters.py

@@ -0,0 +1,238 @@
+"""
+Quality Tracking Exporters - Export metrics in various formats.
+
+Provides functions to export validation metrics in different
+formats for external consumption.
+"""
+
+import json
+from datetime import datetime
+from typing import List, Optional
+
+from pycharter.quality.tracking.models import MetricsSummary, ValidationMetric
+
+
+def export_json(
+    metrics: List[ValidationMetric],
+    pretty: bool = True,
+    include_metadata: bool = True,
+) -> str:
+    """
+    Export metrics as JSON.
+
+    Args:
+        metrics: List of ValidationMetrics to export
+        pretty: If True, format with indentation
+        include_metadata: If True, include metric metadata
+
+    Returns:
+        JSON string representation of metrics
+    """
+    data = []
+    for m in metrics:
+        metric_dict = m.to_dict()
+        if not include_metadata:
+            metric_dict.pop("metadata", None)
+        data.append(metric_dict)
+
+    if pretty:
+        return json.dumps(data, indent=2, default=str)
+    return json.dumps(data, default=str)
+
+
+def export_prometheus(
+    metrics: List[ValidationMetric],
+    summaries: Optional[List[MetricsSummary]] = None,
+    prefix: str = "pycharter",
+) -> str:
+    """
+    Export metrics in Prometheus text format.
+
+    Generates Prometheus-compatible metrics that can be scraped
+    by a Prometheus server or used with pushgateway.
+
+    Args:
+        metrics: List of ValidationMetrics to export
+        summaries: Optional list of MetricsSummaries to export
+        prefix: Metric name prefix
+
+    Returns:
+        Prometheus text format string
+
+    Example output:
+        # HELP pycharter_validation_total Total validation runs
+        # TYPE pycharter_validation_total counter
+        pycharter_validation_total{schema="users",version="1.0.0"} 100
+    """
+    lines = []
+    timestamp_ms = int(datetime.utcnow().timestamp() * 1000)
+
+    # Helper to format labels
+    def format_labels(labels: dict) -> str:
+        parts = [f'{k}="{v}"' for k, v in labels.items()]
+        return "{" + ",".join(parts) + "}"
+
+    # Aggregate metrics by schema for summary metrics
+    schema_metrics: dict = {}
+    for m in metrics:
+        key = (m.schema_name, m.version)
+        if key not in schema_metrics:
+            schema_metrics[key] = {
+                "record_count": 0,
+                "valid_count": 0,
+                "error_count": 0,
+                "validity_rates": [],
+                "completeness_values": [],
+                "durations": [],
+                "latest": m,
+            }
+        data = schema_metrics[key]
+        data["record_count"] += m.record_count
+        data["valid_count"] += m.valid_count
+        data["error_count"] += m.error_count
+        data["validity_rates"].append(m.validity_rate)
+        data["completeness_values"].append(m.completeness)
+        data["durations"].append(m.duration_ms)
+        if m.timestamp > data["latest"].timestamp:
+            data["latest"] = m
+
+    # Total validations counter
+    lines.append(f"# HELP {prefix}_validations_total Total number of validation runs")
+    lines.append(f"# TYPE {prefix}_validations_total counter")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        lines.append(f"{prefix}_validations_total{labels} {len(data['validity_rates'])}")
+
+    lines.append("")
+
+    # Total records processed
+    lines.append(f"# HELP {prefix}_records_total Total number of records processed")
+    lines.append(f"# TYPE {prefix}_records_total counter")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        lines.append(f"{prefix}_records_total{labels} {data['record_count']}")
+
+    lines.append("")
+
+    # Valid records counter
+    lines.append(f"# HELP {prefix}_valid_records_total Total number of valid records")
+    lines.append(f"# TYPE {prefix}_valid_records_total counter")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        lines.append(f"{prefix}_valid_records_total{labels} {data['valid_count']}")
+
+    lines.append("")
+
+    # Error records counter
+    lines.append(f"# HELP {prefix}_error_records_total Total number of records with errors")
+    lines.append(f"# TYPE {prefix}_error_records_total counter")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        lines.append(f"{prefix}_error_records_total{labels} {data['error_count']}")
+
+    lines.append("")
+
+    # Validity rate gauge (latest value)
+    lines.append(f"# HELP {prefix}_validity_rate Current validity rate")
+    lines.append(f"# TYPE {prefix}_validity_rate gauge")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        latest_rate = data["latest"].validity_rate
+        lines.append(f"{prefix}_validity_rate{labels} {latest_rate:.6f}")
+
+    lines.append("")
+
+    # Completeness gauge (latest value)
+    lines.append(f"# HELP {prefix}_completeness Current data completeness")
+    lines.append(f"# TYPE {prefix}_completeness gauge")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        latest_completeness = data["latest"].completeness
+        lines.append(f"{prefix}_completeness{labels} {latest_completeness:.6f}")
+
+    lines.append("")
+
+    # Validation duration (latest value)
+    lines.append(f"# HELP {prefix}_validation_duration_ms Validation duration in milliseconds")
+    lines.append(f"# TYPE {prefix}_validation_duration_ms gauge")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        latest_duration = data["latest"].duration_ms
+        lines.append(f"{prefix}_validation_duration_ms{labels} {latest_duration:.3f}")
+
+    lines.append("")
+
+    # Average validity rate
+    lines.append(f"# HELP {prefix}_validity_rate_avg Average validity rate")
+    lines.append(f"# TYPE {prefix}_validity_rate_avg gauge")
+    for (schema, version), data in schema_metrics.items():
+        labels = format_labels({"schema": schema, "version": version})
+        avg_rate = sum(data["validity_rates"]) / len(data["validity_rates"])
+        lines.append(f"{prefix}_validity_rate_avg{labels} {avg_rate:.6f}")
+
+    # Include summary metrics if provided
+    if summaries:
+        lines.append("")
+        lines.append(f"# HELP {prefix}_summary_total_validations Total validations in summary period")
+        lines.append(f"# TYPE {prefix}_summary_total_validations gauge")
+        for s in summaries:
+            labels = format_labels({"schema": s.schema_name})
+            lines.append(f"{prefix}_summary_total_validations{labels} {s.total_validations}")
+
+        lines.append("")
+        lines.append(f"# HELP {prefix}_summary_avg_validity_rate Average validity rate in summary period")
+        lines.append(f"# TYPE {prefix}_summary_avg_validity_rate gauge")
+        for s in summaries:
+            labels = format_labels({"schema": s.schema_name})
+            lines.append(f"{prefix}_summary_avg_validity_rate{labels} {s.avg_validity_rate:.6f}")
+
+    return "\n".join(lines) + "\n"
+
+
+def export_csv(
+    metrics: List[ValidationMetric],
+    include_header: bool = True,
+) -> str:
+    """
+    Export metrics as CSV.
+
+    Args:
+        metrics: List of ValidationMetrics to export
+        include_header: If True, include header row
+
+    Returns:
+        CSV string representation of metrics
+    """
+    columns = [
+        "id",
+        "schema_name",
+        "version",
+        "timestamp",
+        "record_count",
+        "valid_count",
+        "error_count",
+        "validity_rate",
+        "completeness",
+        "duration_ms",
+    ]
+
+    lines = []
+    if include_header:
+        lines.append(",".join(columns))
+
+    for m in metrics:
+        row = [
+            m.id,
+            m.schema_name,
+            m.version,
+            m.timestamp.isoformat(),
+            str(m.record_count),
+            str(m.valid_count),
+            str(m.error_count),
+            f"{m.validity_rate:.6f}",
+            f"{m.completeness:.6f}",
+            f"{m.duration_ms:.3f}",
+        ]
+        lines.append(",".join(row))
+
+    return "\n".join(lines) + "\n"

pycharter/quality/tracking/models.py

@@ -0,0 +1,194 @@
+"""
+Quality Tracking Models - Data models for metrics tracking.
+
+Defines the core data structures for validation metrics
+and aggregated summaries.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ValidationMetric:
+    """
+    Single validation run metric.
+
+    Captures all relevant metrics from a single validation operation
+    for time-series tracking and analysis.
+
+    Attributes:
+        id: Unique identifier for this metric
+        schema_name: Name of the schema validated against
+        version: Version of the schema
+        timestamp: When the validation occurred
+        record_count: Number of records validated
+        valid_count: Number of valid records
+        error_count: Number of records with errors
+        validity_rate: Ratio of valid records (0.0 to 1.0)
+        completeness: Overall data completeness (0.0 to 1.0)
+        field_completeness: Per-field completeness ratios
+        duration_ms: Validation duration in milliseconds
+        errors_by_type: Count of errors by error type
+        metadata: Additional custom metadata
+    """
+
+    schema_name: str
+    version: str
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    record_count: int = 0
+    valid_count: int = 0
+    error_count: int = 0
+    validity_rate: float = 1.0
+    completeness: float = 1.0
+    field_completeness: Dict[str, float] = field(default_factory=dict)
+    duration_ms: float = 0.0
+    errors_by_type: Dict[str, int] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "id": self.id,
+            "schema_name": self.schema_name,
+            "version": self.version,
+            "timestamp": self.timestamp.isoformat(),
+            "record_count": self.record_count,
+            "valid_count": self.valid_count,
+            "error_count": self.error_count,
+            "validity_rate": self.validity_rate,
+            "completeness": self.completeness,
+            "field_completeness": self.field_completeness,
+            "duration_ms": self.duration_ms,
+            "errors_by_type": self.errors_by_type,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ValidationMetric":
+        """Create from dictionary."""
+        timestamp = data.get("timestamp")
+        if isinstance(timestamp, str):
+            timestamp = datetime.fromisoformat(timestamp)
+        elif timestamp is None:
+            timestamp = datetime.utcnow()
+
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            schema_name=data["schema_name"],
+            version=data["version"],
+            timestamp=timestamp,
+            record_count=data.get("record_count", 0),
+            valid_count=data.get("valid_count", 0),
+            error_count=data.get("error_count", 0),
+            validity_rate=data.get("validity_rate", 1.0),
+            completeness=data.get("completeness", 1.0),
+            field_completeness=data.get("field_completeness", {}),
+            duration_ms=data.get("duration_ms", 0.0),
+            errors_by_type=data.get("errors_by_type", {}),
+            metadata=data.get("metadata", {}),
+        )
+
+
+@dataclass
+class MetricsSummary:
+    """
+    Aggregated metrics summary for a schema over a time period.
+
+    Provides statistical aggregations of validation metrics
+    for trend analysis and monitoring.
+
+    Attributes:
+        schema_name: Name of the schema
+        period_start: Start of the summary period
+        period_end: End of the summary period
+        total_validations: Total number of validation runs
+        total_records: Total number of records validated
+        total_valid: Total number of valid records
+        total_errors: Total number of errors
+        avg_validity_rate: Average validity rate
+        min_validity_rate: Minimum validity rate
+        max_validity_rate: Maximum validity rate
+        avg_completeness: Average completeness
+        avg_duration_ms: Average validation duration
+        top_error_types: Most common error types with counts
+    """
+
+    schema_name: str
+    period_start: datetime
+    period_end: datetime
+    total_validations: int = 0
+    total_records: int = 0
+    total_valid: int = 0
+    total_errors: int = 0
+    avg_validity_rate: float = 0.0
+    min_validity_rate: float = 1.0
+    max_validity_rate: float = 0.0
+    avg_completeness: float = 0.0
+    avg_duration_ms: float = 0.0
+    top_error_types: Dict[str, int] = field(default_factory=dict)
+
+    @property
+    def overall_validity_rate(self) -> float:
+        """Calculate overall validity rate from totals."""
+        if self.total_records == 0:
+            return 1.0
+        return self.total_valid / self.total_records
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "schema_name": self.schema_name,
+            "period_start": self.period_start.isoformat(),
+            "period_end": self.period_end.isoformat(),
+            "total_validations": self.total_validations,
+            "total_records": self.total_records,
+            "total_valid": self.total_valid,
+            "total_errors": self.total_errors,
+            "avg_validity_rate": self.avg_validity_rate,
+            "min_validity_rate": self.min_validity_rate,
+            "max_validity_rate": self.max_validity_rate,
+            "avg_completeness": self.avg_completeness,
+            "avg_duration_ms": self.avg_duration_ms,
+            "overall_validity_rate": self.overall_validity_rate,
+            "top_error_types": self.top_error_types,
+        }
+
+
+@dataclass
+class MetricsFilter:
+    """
+    Filter criteria for querying metrics.
+
+    Attributes:
+        schema_name: Filter by schema name
+        version: Filter by schema version
+        since: Filter metrics after this time
+        until: Filter metrics before this time
+        min_validity_rate: Filter by minimum validity rate
+        limit: Maximum number of results
+        offset: Offset for pagination
+    """
+
+    schema_name: Optional[str] = None
+    version: Optional[str] = None
+    since: Optional[datetime] = None
+    until: Optional[datetime] = None
+    min_validity_rate: Optional[float] = None
+    limit: int = 100
+    offset: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary (for serialization)."""
+        return {
+            "schema_name": self.schema_name,
+            "version": self.version,
+            "since": self.since.isoformat() if self.since else None,
+            "until": self.until.isoformat() if self.until else None,
+            "min_validity_rate": self.min_validity_rate,
+            "limit": self.limit,
+            "offset": self.offset,
+        }