timetracer 1.1.0__py3-none-any.whl

timetracer/storage/s3.py

@@ -0,0 +1,364 @@
+"""
+S3 storage backend for Timetracer cassettes.
+
+Enables storing and retrieving cassettes from AWS S3 or S3-compatible storage.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterator
+
+if TYPE_CHECKING:
+    from mypy_boto3_s3 import S3Client
+
+
+@dataclass
+class S3Config:
+    """Configuration for S3 storage."""
+    bucket: str
+    prefix: str = "cassettes"
+    region: str | None = None
+    endpoint_url: str | None = None  # For S3-compatible (MinIO, LocalStack)
+    access_key: str | None = None
+    secret_key: str | None = None
+
+    @classmethod
+    def from_env(cls) -> "S3Config":
+        """
+        Load S3 configuration from environment variables.
+
+        Environment variables:
+            TIMETRACER_S3_BUCKET: S3 bucket name (required)
+            TIMETRACER_S3_PREFIX: Key prefix (default: "cassettes")
+            TIMETRACER_S3_REGION: AWS region
+            TIMETRACER_S3_ENDPOINT: Custom endpoint URL (for MinIO, etc.)
+            AWS_ACCESS_KEY_ID: AWS access key
+            AWS_SECRET_ACCESS_KEY: AWS secret key
+        """
+        bucket = os.environ.get("TIMETRACER_S3_BUCKET")
+        if not bucket:
+            raise ValueError("TIMETRACER_S3_BUCKET environment variable is required")
+
+        return cls(
+            bucket=bucket,
+            prefix=os.environ.get("TIMETRACER_S3_PREFIX", "cassettes"),
+            region=os.environ.get("TIMETRACER_S3_REGION") or os.environ.get("AWS_REGION"),
+            endpoint_url=os.environ.get("TIMETRACER_S3_ENDPOINT"),
+            access_key=os.environ.get("AWS_ACCESS_KEY_ID"),
+            secret_key=os.environ.get("AWS_SECRET_ACCESS_KEY"),
+        )
+
+
+class S3Store:
+    """
+    S3 storage backend for cassettes.
+
+    Usage:
+        from timetracer.storage.s3 import S3Store, S3Config
+
+        config = S3Config(bucket="my-cassettes", prefix="api-traces")
+        store = S3Store(config)
+
+        # Upload a local cassette
+        store.upload("./cassettes/2026-01-15/POST__checkout__a91c.json")
+
+        # Download a cassette
+        store.download("2026-01-15/POST__checkout__a91c.json", "./local_copy.json")
+
+        # List cassettes
+        for key in store.list():
+            print(key)
+    """
+
+    def __init__(self, config: S3Config) -> None:
+        """
+        Initialize S3 store.
+
+        Args:
+            config: S3 configuration.
+        """
+        self.config = config
+        self._client: "S3Client | None" = None
+
+    @property
+    def client(self) -> "S3Client":
+        """Get or create S3 client."""
+        if self._client is None:
+            self._client = self._create_client()
+        return self._client
+
+    def _create_client(self) -> "S3Client":
+        """Create boto3 S3 client."""
+        try:
+            import boto3
+        except ImportError:
+            raise ImportError(
+                "boto3 is required for S3 storage. "
+                "Install with: pip install timetracer[s3]"
+            )
+
+        kwargs: dict[str, Any] = {}
+
+        if self.config.region:
+            kwargs["region_name"] = self.config.region
+
+        if self.config.endpoint_url:
+            kwargs["endpoint_url"] = self.config.endpoint_url
+
+        if self.config.access_key and self.config.secret_key:
+            kwargs["aws_access_key_id"] = self.config.access_key
+            kwargs["aws_secret_access_key"] = self.config.secret_key
+
+        return boto3.client("s3", **kwargs)
+
+    def _make_key(self, path: str) -> str:
+        """Create S3 key from path."""
+        # Normalize path
+        path = path.replace("\\", "/")
+
+        # Remove leading slashes
+        path = path.lstrip("/")
+
+        # Add prefix
+        if self.config.prefix:
+            return f"{self.config.prefix.rstrip('/')}/{path}"
+        return path
+
+    def upload(
+        self,
+        local_path: str,
+        remote_key: str | None = None,
+    ) -> str:
+        """
+        Upload a cassette to S3.
+
+        Args:
+            local_path: Path to local cassette file.
+            remote_key: Optional S3 key. If None, uses filename.
+
+        Returns:
+            S3 key where cassette was uploaded.
+        """
+        local_path = Path(local_path)
+
+        if not local_path.exists():
+            raise FileNotFoundError(f"Cassette not found: {local_path}")
+
+        # Determine key
+        if remote_key is None:
+            # Use date/filename structure
+            remote_key = local_path.name
+            if local_path.parent.name and local_path.parent.name != ".":
+                remote_key = f"{local_path.parent.name}/{local_path.name}"
+
+        s3_key = self._make_key(remote_key)
+
+        # Upload
+        self.client.upload_file(
+            str(local_path),
+            self.config.bucket,
+            s3_key,
+            ExtraArgs={"ContentType": "application/json"},
+        )
+
+        return s3_key
+
+    def download(
+        self,
+        remote_key: str,
+        local_path: str,
+    ) -> str:
+        """
+        Download a cassette from S3.
+
+        Args:
+            remote_key: S3 key (without prefix).
+            local_path: Where to save locally.
+
+        Returns:
+            Local path where file was saved.
+        """
+        s3_key = self._make_key(remote_key)
+        local_path = Path(local_path)
+
+        # Create parent directory
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Download
+        self.client.download_file(
+            self.config.bucket,
+            s3_key,
+            str(local_path),
+        )
+
+        return str(local_path)
+
+    def read(self, remote_key: str) -> dict[str, Any]:
+        """
+        Read a cassette directly from S3.
+
+        Args:
+            remote_key: S3 key (without prefix).
+
+        Returns:
+            Cassette data as dict.
+        """
+        s3_key = self._make_key(remote_key)
+
+        response = self.client.get_object(
+            Bucket=self.config.bucket,
+            Key=s3_key,
+        )
+
+        body = response["Body"].read()
+        return json.loads(body.decode("utf-8"))
+
+    def write(self, remote_key: str, data: dict[str, Any]) -> str:
+        """
+        Write cassette data directly to S3.
+
+        Args:
+            remote_key: S3 key (without prefix).
+            data: Cassette data as dict.
+
+        Returns:
+            S3 key where cassette was written.
+        """
+        s3_key = self._make_key(remote_key)
+
+        body = json.dumps(data, indent=2).encode("utf-8")
+
+        self.client.put_object(
+            Bucket=self.config.bucket,
+            Key=s3_key,
+            Body=body,
+            ContentType="application/json",
+        )
+
+        return s3_key
+
+    def list(
+        self,
+        prefix: str = "",
+        limit: int = 100,
+    ) -> Iterator[str]:
+        """
+        List cassettes in S3.
+
+        Args:
+            prefix: Additional prefix filter.
+            limit: Maximum number of results.
+
+        Yields:
+            S3 keys (relative to store prefix).
+        """
+        s3_prefix = self._make_key(prefix)
+
+        paginator = self.client.get_paginator("list_objects_v2")
+        pages = paginator.paginate(
+            Bucket=self.config.bucket,
+            Prefix=s3_prefix,
+            PaginationConfig={"MaxItems": limit},
+        )
+
+        base_prefix = self.config.prefix.rstrip("/") + "/" if self.config.prefix else ""
+
+        for page in pages:
+            for obj in page.get("Contents", []):
+                key = obj["Key"]
+                # Remove base prefix for relative key
+                if key.startswith(base_prefix):
+                    key = key[len(base_prefix):]
+                yield key
+
+    def delete(self, remote_key: str) -> None:
+        """
+        Delete a cassette from S3.
+
+        Args:
+            remote_key: S3 key (without prefix).
+        """
+        s3_key = self._make_key(remote_key)
+
+        self.client.delete_object(
+            Bucket=self.config.bucket,
+            Key=s3_key,
+        )
+
+    def exists(self, remote_key: str) -> bool:
+        """
+        Check if a cassette exists in S3.
+
+        Args:
+            remote_key: S3 key (without prefix).
+
+        Returns:
+            True if cassette exists.
+        """
+        s3_key = self._make_key(remote_key)
+
+        try:
+            self.client.head_object(
+                Bucket=self.config.bucket,
+                Key=s3_key,
+            )
+            return True
+        except Exception:
+            return False
+
+    def sync_upload(
+        self,
+        local_dir: str,
+        remote_prefix: str = "",
+    ) -> list[str]:
+        """
+        Sync local cassettes to S3.
+
+        Args:
+            local_dir: Local directory with cassettes.
+            remote_prefix: Optional prefix in S3.
+
+        Returns:
+            List of uploaded S3 keys.
+        """
+        local_dir = Path(local_dir)
+        uploaded = []
+
+        for json_file in local_dir.rglob("*.json"):
+            relative = json_file.relative_to(local_dir)
+            remote_key = f"{remote_prefix}/{relative}" if remote_prefix else str(relative)
+            remote_key = remote_key.replace("\\", "/")
+
+            key = self.upload(str(json_file), remote_key)
+            uploaded.append(key)
+
+        return uploaded
+
+    def sync_download(
+        self,
+        local_dir: str,
+        remote_prefix: str = "",
+    ) -> list[str]:
+        """
+        Sync S3 cassettes to local directory.
+
+        Args:
+            local_dir: Local directory to download to.
+            remote_prefix: Optional prefix filter in S3.
+
+        Returns:
+            List of downloaded local paths.
+        """
+        local_dir = Path(local_dir)
+        downloaded = []
+
+        for remote_key in self.list(prefix=remote_prefix, limit=1000):
+            local_path = local_dir / remote_key
+            self.download(remote_key, str(local_path))
+            downloaded.append(str(local_path))
+
+        return downloaded

timetracer/timeline/__init__.py

@@ -0,0 +1,6 @@
+"""Timeline module for HTML visualization."""
+
+from timetracer.timeline.generator import generate_timeline
+from timetracer.timeline.template import render_timeline_html
+
+__all__ = ["generate_timeline", "render_timeline_html"]

timetracer/timeline/generator.py

@@ -0,0 +1,150 @@
+"""
+Timeline data generator.
+
+Converts cassette data into timeline-friendly format for visualization.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from timetracer.cassette import read_cassette
+from timetracer.types import Cassette
+
+
+@dataclass
+class TimelineEvent:
+    """A single event on the timeline."""
+    id: int
+    label: str
+    event_type: str
+    start_ms: float
+    duration_ms: float
+    end_ms: float
+    status: int | None = None
+    url: str | None = None
+    is_error: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TimelineData:
+    """Complete timeline data for visualization."""
+    title: str
+    method: str
+    path: str
+    total_duration_ms: float
+    recorded_at: str
+
+    # Main request span
+    request_start: float = 0.0
+    request_end: float = 0.0
+    response_status: int = 0
+
+    # All events
+    events: list[TimelineEvent] = field(default_factory=list)
+
+    # Stats
+    event_count: int = 0
+    error_count: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON/template use."""
+        return {
+            "title": self.title,
+            "method": self.method,
+            "path": self.path,
+            "total_duration_ms": self.total_duration_ms,
+            "recorded_at": self.recorded_at,
+            "request": {
+                "start": self.request_start,
+                "end": self.request_end,
+                "status": self.response_status,
+            },
+            "events": [
+                {
+                    "id": e.id,
+                    "label": e.label,
+                    "type": e.event_type,
+                    "start_ms": e.start_ms,
+                    "duration_ms": e.duration_ms,
+                    "end_ms": e.end_ms,
+                    "status": e.status,
+                    "url": e.url,
+                    "is_error": e.is_error,
+                }
+                for e in self.events
+            ],
+            "stats": {
+                "event_count": self.event_count,
+                "error_count": self.error_count,
+            },
+        }
+
+
+def generate_timeline(cassette_path: str) -> TimelineData:
+    """
+    Generate timeline data from a cassette file.
+
+    Args:
+        cassette_path: Path to the cassette file.
+
+    Returns:
+        TimelineData ready for visualization.
+    """
+    cassette = read_cassette(cassette_path)
+    return _cassette_to_timeline(cassette)
+
+
+def _cassette_to_timeline(cassette: Cassette) -> TimelineData:
+    """Convert Cassette to TimelineData."""
+    req = cassette.request
+    res = cassette.response
+
+    timeline = TimelineData(
+        title=f"{req.method} {req.path}",
+        method=req.method,
+        path=req.path,
+        total_duration_ms=res.duration_ms,
+        recorded_at=cassette.session.recorded_at,
+        request_start=0.0,
+        request_end=res.duration_ms,
+        response_status=res.status,
+    )
+
+    # Convert events
+    error_count = 0
+    for event in cassette.events:
+        is_error = (event.result.status or 0) >= 400 or event.result.error is not None
+        if is_error:
+            error_count += 1
+
+        # Create label
+        sig = event.signature
+        if sig.url:
+            # Shorten URL for display
+            url_short = sig.url
+            if len(url_short) > 50:
+                url_short = url_short[:47] + "..."
+            label = f"{sig.method} {url_short}"
+        else:
+            label = f"{event.event_type.value}"
+
+        timeline_event = TimelineEvent(
+            id=event.eid,
+            label=label,
+            event_type=event.event_type.value,
+            start_ms=event.start_offset_ms,
+            duration_ms=event.duration_ms,
+            end_ms=event.start_offset_ms + event.duration_ms,
+            status=event.result.status,
+            url=sig.url,
+            is_error=is_error,
+        )
+        timeline.events.append(timeline_event)
+
+    timeline.event_count = len(timeline.events)
+    timeline.error_count = error_count
+
+    return timeline