timetracer 1.1.0__py3-none-any.whl

timetracer/diff/__init__.py

@@ -0,0 +1,6 @@
+"""Diff module for cassette comparison."""
+
+from timetracer.diff.engine import DiffReport, diff_cassettes
+from timetracer.diff.report import format_diff_report
+
+__all__ = ["diff_cassettes", "DiffReport", "format_diff_report"]

timetracer/diff/engine.py

@@ -0,0 +1,311 @@
+"""
+Diff engine for comparing cassettes.
+
+Compares two cassettes and produces a detailed report of differences.
+Useful for regression detection and debugging.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from timetracer.cassette import read_cassette
+from timetracer.types import Cassette, DependencyEvent
+
+
+@dataclass
+class EventDiff:
+    """Difference between two events."""
+    event_index: int
+    event_type: str
+
+    # What changed
+    status_changed: bool = False
+    old_status: int | None = None
+    new_status: int | None = None
+
+    duration_changed: bool = False
+    old_duration_ms: float = 0.0
+    new_duration_ms: float = 0.0
+    duration_delta_ms: float = 0.0
+    duration_delta_pct: float = 0.0
+
+    url_changed: bool = False
+    old_url: str | None = None
+    new_url: str | None = None
+
+    body_changed: bool = False
+
+    # Is this a critical diff?
+    is_critical: bool = False
+    summary: str = ""
+
+
+@dataclass
+class ResponseDiff:
+    """Difference between response data."""
+    status_changed: bool = False
+    old_status: int = 0
+    new_status: int = 0
+
+    duration_changed: bool = False
+    old_duration_ms: float = 0.0
+    new_duration_ms: float = 0.0
+    duration_delta_ms: float = 0.0
+    duration_delta_pct: float = 0.0
+
+    body_changed: bool = False
+
+
+@dataclass
+class DiffReport:
+    """Complete diff report between two cassettes."""
+    cassette_a_path: str
+    cassette_b_path: str
+
+    # Request info
+    method: str = ""
+    path: str = ""
+
+    # Overall result
+    has_differences: bool = False
+    is_regression: bool = False
+
+    # Response diff
+    response_diff: ResponseDiff = field(default_factory=ResponseDiff)
+
+    # Event diffs
+    event_count_a: int = 0
+    event_count_b: int = 0
+    event_count_changed: bool = False
+    event_diffs: list[EventDiff] = field(default_factory=list)
+
+    # Unmatched events
+    extra_events_a: list[int] = field(default_factory=list)
+    extra_events_b: list[int] = field(default_factory=list)
+
+    # Summary stats
+    total_duration_delta_ms: float = 0.0
+    critical_diffs: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "cassette_a": self.cassette_a_path,
+            "cassette_b": self.cassette_b_path,
+            "request": {
+                "method": self.method,
+                "path": self.path,
+            },
+            "has_differences": self.has_differences,
+            "is_regression": self.is_regression,
+            "response": {
+                "status_changed": self.response_diff.status_changed,
+                "old_status": self.response_diff.old_status,
+                "new_status": self.response_diff.new_status,
+                "duration_delta_ms": self.response_diff.duration_delta_ms,
+                "duration_delta_pct": self.response_diff.duration_delta_pct,
+            },
+            "events": {
+                "count_a": self.event_count_a,
+                "count_b": self.event_count_b,
+                "count_changed": self.event_count_changed,
+                "diffs": [
+                    {
+                        "index": d.event_index,
+                        "type": d.event_type,
+                        "summary": d.summary,
+                        "is_critical": d.is_critical,
+                    }
+                    for d in self.event_diffs
+                ],
+                "extra_in_a": self.extra_events_a,
+                "extra_in_b": self.extra_events_b,
+            },
+            "summary": {
+                "total_duration_delta_ms": self.total_duration_delta_ms,
+                "critical_diffs": self.critical_diffs,
+            },
+        }
+
+
+def diff_cassettes(
+    path_a: str,
+    path_b: str,
+    *,
+    duration_threshold_pct: float = 20.0,
+) -> DiffReport:
+    """
+    Compare two cassettes and produce a diff report.
+
+    Args:
+        path_a: Path to first cassette (baseline).
+        path_b: Path to second cassette (comparison).
+        duration_threshold_pct: Percentage change to flag as significant.
+
+    Returns:
+        DiffReport with all differences.
+    """
+    cassette_a = read_cassette(path_a)
+    cassette_b = read_cassette(path_b)
+
+    report = DiffReport(
+        cassette_a_path=path_a,
+        cassette_b_path=path_b,
+        method=cassette_a.request.method,
+        path=cassette_a.request.path,
+    )
+
+    # Compare response
+    _compare_response(cassette_a, cassette_b, report, duration_threshold_pct)
+
+    # Compare events
+    _compare_events(cassette_a, cassette_b, report, duration_threshold_pct)
+
+    # Determine overall status
+    report.has_differences = (
+        report.response_diff.status_changed
+        or report.response_diff.duration_changed
+        or report.event_count_changed
+        or len(report.event_diffs) > 0
+    )
+
+    # Is it a regression? (status worsened or significant slowdown)
+    report.is_regression = (
+        (report.response_diff.status_changed and report.response_diff.new_status >= 400)
+        or report.response_diff.duration_delta_pct > duration_threshold_pct
+        or report.critical_diffs > 0
+    )
+
+    return report
+
+
+def _compare_response(
+    a: Cassette,
+    b: Cassette,
+    report: DiffReport,
+    threshold_pct: float,
+) -> None:
+    """Compare response data."""
+    res_a = a.response
+    res_b = b.response
+
+    diff = report.response_diff
+
+    # Status
+    if res_a.status != res_b.status:
+        diff.status_changed = True
+        diff.old_status = res_a.status
+        diff.new_status = res_b.status
+
+    # Duration
+    diff.old_duration_ms = res_a.duration_ms
+    diff.new_duration_ms = res_b.duration_ms
+    diff.duration_delta_ms = res_b.duration_ms - res_a.duration_ms
+
+    if res_a.duration_ms > 0:
+        diff.duration_delta_pct = (diff.duration_delta_ms / res_a.duration_ms) * 100
+
+    if abs(diff.duration_delta_pct) > threshold_pct:
+        diff.duration_changed = True
+
+    # Track total duration delta
+    report.total_duration_delta_ms = diff.duration_delta_ms
+
+
+def _compare_events(
+    a: Cassette,
+    b: Cassette,
+    report: DiffReport,
+    threshold_pct: float,
+) -> None:
+    """Compare dependency events."""
+    events_a = a.events
+    events_b = b.events
+
+    report.event_count_a = len(events_a)
+    report.event_count_b = len(events_b)
+    report.event_count_changed = len(events_a) != len(events_b)
+
+    # Compare events pairwise
+    min_count = min(len(events_a), len(events_b))
+
+    for i in range(min_count):
+        event_a = events_a[i]
+        event_b = events_b[i]
+
+        diff = _compare_single_event(i, event_a, event_b, threshold_pct)
+        if diff:
+            report.event_diffs.append(diff)
+            if diff.is_critical:
+                report.critical_diffs += 1
+
+    # Track extra events
+    if len(events_a) > min_count:
+        report.extra_events_a = list(range(min_count, len(events_a)))
+    if len(events_b) > min_count:
+        report.extra_events_b = list(range(min_count, len(events_b)))
+
+
+def _compare_single_event(
+    index: int,
+    a: DependencyEvent,
+    b: DependencyEvent,
+    threshold_pct: float,
+) -> EventDiff | None:
+    """Compare two events at the same index."""
+    diff = EventDiff(
+        event_index=index,
+        event_type=a.event_type.value,
+    )
+
+    has_diff = False
+    summaries = []
+
+    # Status change
+    if a.result.status != b.result.status:
+        diff.status_changed = True
+        diff.old_status = a.result.status
+        diff.new_status = b.result.status
+        has_diff = True
+        summaries.append(f"status: {a.result.status} → {b.result.status}")
+
+        # Critical if went from success to error
+        if (a.result.status or 0) < 400 and (b.result.status or 0) >= 400:
+            diff.is_critical = True
+
+    # Duration change
+    diff.old_duration_ms = a.duration_ms
+    diff.new_duration_ms = b.duration_ms
+    diff.duration_delta_ms = b.duration_ms - a.duration_ms
+
+    if a.duration_ms > 0:
+        diff.duration_delta_pct = (diff.duration_delta_ms / a.duration_ms) * 100
+
+    if abs(diff.duration_delta_pct) > threshold_pct:
+        diff.duration_changed = True
+        has_diff = True
+        direction = "slower" if diff.duration_delta_ms > 0 else "faster"
+        summaries.append(f"{abs(diff.duration_delta_pct):.0f}% {direction}")
+
+    # URL change
+    if a.signature.url != b.signature.url:
+        diff.url_changed = True
+        diff.old_url = a.signature.url
+        diff.new_url = b.signature.url
+        diff.is_critical = True
+        has_diff = True
+        summaries.append("URL changed")
+
+    # Body change (by hash)
+    if a.signature.body_hash != b.signature.body_hash:
+        diff.body_changed = True
+        has_diff = True
+        summaries.append("request body changed")
+
+    if not has_diff:
+        return None
+
+    diff.summary = "; ".join(summaries)
+    return diff

timetracer/diff/report.py

@@ -0,0 +1,113 @@
+"""
+Diff report formatting.
+
+Provides human-readable output for diff reports.
+"""
+
+from __future__ import annotations
+
+from timetracer.diff.engine import DiffReport
+
+
+def format_diff_report(report: DiffReport, use_color: bool = True) -> str:
+    """
+    Format a diff report as human-readable text.
+
+    Args:
+        report: The diff report to format.
+        use_color: Whether to include ANSI color codes.
+
+    Returns:
+        Formatted string.
+    """
+    lines = []
+
+    # Header
+    lines.append("")
+    lines.append("=" * 70)
+    lines.append("timetracer DIFF REPORT")
+    lines.append("=" * 70)
+    lines.append("")
+
+    # Files
+    lines.append(f"Baseline:   {report.cassette_a_path}")
+    lines.append(f"Comparison: {report.cassette_b_path}")
+    lines.append("")
+
+    # Request
+    lines.append(f"Request: {report.method} {report.path}")
+    lines.append("")
+
+    # Overall result
+    if report.is_regression:
+        icon = "[FAIL]"
+        status = "REGRESSION DETECTED"
+    elif report.has_differences:
+        icon = "[WARN]"
+        status = "DIFFERENCES FOUND"
+    else:
+        icon = "[OK]"
+        status = "NO DIFFERENCES"
+
+    lines.append(f"{icon} {status}")
+    lines.append("")
+
+    # Response diff
+    lines.append("-" * 40)
+    lines.append("RESPONSE")
+    lines.append("-" * 40)
+
+    rd = report.response_diff
+
+    if rd.status_changed:
+        lines.append(f"  Status:   {rd.old_status} → {rd.new_status}")
+    else:
+        lines.append(f"  Status:   {rd.old_status} (unchanged)")
+
+    if rd.duration_changed:
+        direction = "(slower)" if rd.duration_delta_ms > 0 else "(faster)"
+        lines.append(
+            f"  Duration: {rd.old_duration_ms:.0f}ms → {rd.new_duration_ms:.0f}ms "
+            f"({direction} {abs(rd.duration_delta_pct):.1f}%)"
+        )
+    else:
+        lines.append(f"  Duration: {rd.old_duration_ms:.0f}ms → {rd.new_duration_ms:.0f}ms")
+
+    lines.append("")
+
+    # Events diff
+    lines.append("-" * 40)
+    lines.append("EVENTS")
+    lines.append("-" * 40)
+
+    if report.event_count_changed:
+        lines.append(f"  Count: {report.event_count_a} → {report.event_count_b}")
+    else:
+        lines.append(f"  Count: {report.event_count_a} (unchanged)")
+
+    if report.event_diffs:
+        lines.append("")
+        lines.append("  Changed events:")
+        for diff in report.event_diffs:
+            icon = "[FAIL]" if diff.is_critical else "[WARN]"
+            lines.append(f"    {icon} #{diff.event_index} [{diff.event_type}]: {diff.summary}")
+
+    if report.extra_events_a:
+        lines.append("")
+        lines.append(f"  Events only in baseline: {report.extra_events_a}")
+
+    if report.extra_events_b:
+        lines.append("")
+        lines.append(f"  Events only in comparison: {report.extra_events_b}")
+
+    lines.append("")
+
+    # Summary
+    lines.append("-" * 40)
+    lines.append("SUMMARY")
+    lines.append("-" * 40)
+    lines.append(f"  Total duration change: {report.total_duration_delta_ms:+.0f}ms")
+    lines.append(f"  Critical differences:  {report.critical_diffs}")
+    lines.append("")
+
+    return "\n".join(lines)

timetracer/exceptions.py

@@ -0,0 +1,113 @@
+"""
+Centralized exceptions for Timetracer.
+
+All custom exceptions are defined here to ensure consistent error handling.
+"""
+
+from typing import Any
+
+
+class TimetracerError(Exception):
+    """Base exception for all Timetracer errors."""
+    pass
+
+
+class CassetteError(TimetracerError):
+    """Base exception for cassette-related errors."""
+    pass
+
+
+class CassetteNotFoundError(CassetteError):
+    """Raised when a cassette file cannot be found."""
+
+    def __init__(self, path: str):
+        self.path = path
+        super().__init__(f"Cassette not found: {path}")
+
+
+class CassetteSchemaError(CassetteError):
+    """Raised when a cassette has an invalid or incompatible schema."""
+
+    def __init__(self, path: str, expected_version: str, actual_version: str | None):
+        self.path = path
+        self.expected_version = expected_version
+        self.actual_version = actual_version
+        super().__init__(
+            f"Cassette schema mismatch in {path}: "
+            f"expected {expected_version}, got {actual_version}"
+        )
+
+
+class ReplayMismatchError(TimetracerError):
+    """
+    Raised when a dependency call during replay doesn't match the recorded cassette.
+
+    This provides detailed information to help debug what changed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        cassette_path: str | None = None,
+        endpoint: str | None = None,
+        event_index: int | None = None,
+        expected: dict[str, Any] | None = None,
+        actual: dict[str, Any] | None = None,
+        hint: str | None = None,
+    ):
+        self.cassette_path = cassette_path
+        self.endpoint = endpoint
+        self.event_index = event_index
+        self.expected = expected or {}
+        self.actual = actual or {}
+        self.hint = hint
+
+        # Build detailed error message
+        lines = [message, ""]
+
+        if cassette_path:
+            lines.append(f"cassette: {cassette_path}")
+        if endpoint:
+            lines.append(f"endpoint: {endpoint}")
+        if event_index is not None:
+            lines.append(f"event index: #{event_index}")
+
+        if expected:
+            lines.append("")
+            lines.append("expected:")
+            for key, value in expected.items():
+                lines.append(f"  {key}: {value}")
+
+        if actual:
+            lines.append("")
+            lines.append("actual:")
+            for key, value in actual.items():
+                lines.append(f"  {key}: {value}")
+
+        if hint:
+            lines.append("")
+            lines.append(f"hint: {hint}")
+
+        super().__init__("\n".join(lines))
+
+
+class ConfigurationError(TimetracerError):
+    """Raised when there's an invalid configuration."""
+    pass
+
+
+class PluginError(TimetracerError):
+    """Base exception for plugin-related errors."""
+    pass
+
+
+class PluginNotFoundError(PluginError):
+    """Raised when a requested plugin is not available."""
+
+    def __init__(self, plugin_name: str):
+        self.plugin_name = plugin_name
+        super().__init__(
+            f"Plugin '{plugin_name}' not found. "
+            f"Make sure it's installed: pip install timetracer[{plugin_name}]"
+        )

timetracer/integrations/__init__.py

@@ -0,0 +1,27 @@
+"""Framework integrations for Timetracer."""
+
+from timetracer.integrations.fastapi import TimeTraceMiddleware, auto_setup
+
+# Alias for backwards compatibility
+timetracerMiddleware = TimeTraceMiddleware
+
+# Flask is optional
+try:
+    from timetracer.integrations.flask import TimeTraceMiddleware as FlaskMiddleware
+    from timetracer.integrations.flask import auto_setup as flask_auto_setup
+    from timetracer.integrations.flask import init_app
+    _HAS_FLASK = True
+except ImportError:
+    _HAS_FLASK = False
+    FlaskMiddleware = None
+    init_app = None
+    flask_auto_setup = None
+
+__all__ = [
+    "TimeTraceMiddleware",
+    "timetracerMiddleware",  # Alias
+    "auto_setup",
+    "FlaskMiddleware",
+    "init_app",
+    "flask_auto_setup",
+]