oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/session/annotations.py

@@ -1,289 +0,0 @@
-"""Trace annotation support.
-
-This module provides annotation capabilities for marking points of interest
-in signal traces.
-
-
-Example:
-    >>> layer = AnnotationLayer("Debug Markers")
-    >>> layer.add(Annotation(time=1.5e-6, text="Glitch detected"))
-    >>> layer.add(Annotation(time_range=(2e-6, 3e-6), text="Data packet"))
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from datetime import datetime
-from enum import Enum
-from typing import Any
-
-
-class AnnotationType(Enum):
-    """Types of annotations."""
-
-    POINT = "point"  # Single time point
-    RANGE = "range"  # Time range
-    VERTICAL = "vertical"  # Vertical line
-    HORIZONTAL = "horizontal"  # Horizontal line
-    REGION = "region"  # 2D region (time + amplitude)
-    TEXT = "text"  # Free-floating text
-
-
-@dataclass
-class Annotation:
-    """Single annotation on a trace.
-
-    Attributes:
-        text: Annotation text/label
-        time: Time point (for point annotations)
-        time_range: (start, end) time range
-        amplitude: Amplitude value (for horizontal lines)
-        amplitude_range: (min, max) amplitude range
-        annotation_type: Type of annotation
-        color: Display color (hex or name)
-        style: Line style ('solid', 'dashed', 'dotted')
-        visible: Whether annotation is visible
-        created_at: Creation timestamp
-        metadata: Additional metadata
-    """
-
-    text: str
-    time: float | None = None
-    time_range: tuple[float, float] | None = None
-    amplitude: float | None = None
-    amplitude_range: tuple[float, float] | None = None
-    annotation_type: AnnotationType = AnnotationType.POINT
-    color: str = "#FF6B6B"
-    style: str = "solid"
-    visible: bool = True
-    created_at: datetime = field(default_factory=datetime.now)
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-    def __post_init__(self) -> None:
-        """Infer annotation type from provided parameters."""
-        if self.annotation_type == AnnotationType.POINT:
-            if self.time_range is not None:
-                self.annotation_type = AnnotationType.RANGE
-            elif self.amplitude is not None and self.time is None:
-                self.annotation_type = AnnotationType.HORIZONTAL
-            elif self.amplitude_range is not None and self.time_range is not None:
-                self.annotation_type = AnnotationType.REGION  # type: ignore[unreachable]
-
-    @property
-    def start_time(self) -> float | None:
-        """Get start time for range annotations."""
-        if self.time_range:
-            return self.time_range[0]
-        return self.time
-
-    @property
-    def end_time(self) -> float | None:
-        """Get end time for range annotations."""
-        if self.time_range:
-            return self.time_range[1]
-        return self.time
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "text": self.text,
-            "time": self.time,
-            "time_range": self.time_range,
-            "amplitude": self.amplitude,
-            "amplitude_range": self.amplitude_range,
-            "annotation_type": self.annotation_type.value,
-            "color": self.color,
-            "style": self.style,
-            "visible": self.visible,
-            "created_at": self.created_at.isoformat(),
-            "metadata": self.metadata,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> Annotation:
-        """Create from dictionary."""
-        data = data.copy()
-        data["annotation_type"] = AnnotationType(data.get("annotation_type", "point"))
-        if "created_at" in data and isinstance(data["created_at"], str):
-            data["created_at"] = datetime.fromisoformat(data["created_at"])
-        return cls(**data)
-
-
-@dataclass
-class AnnotationLayer:
-    """Collection of related annotations.
-
-    Attributes:
-        name: Layer name
-        annotations: List of annotations
-        visible: Whether layer is visible
-        locked: Whether layer is locked (read-only)
-        color: Default color for new annotations
-        description: Layer description
-    """
-
-    name: str
-    annotations: list[Annotation] = field(default_factory=list)
-    visible: bool = True
-    locked: bool = False
-    color: str = "#FF6B6B"
-    description: str = ""
-
-    def add(
-        self,
-        annotation: Annotation | None = None,
-        *,
-        text: str = "",
-        time: float | None = None,
-        time_range: tuple[float, float] | None = None,
-        **kwargs: Any,
-    ) -> Annotation:
-        """Add annotation to layer.
-
-        Args:
-            annotation: Pre-built Annotation object.
-            text: Annotation text (if not using pre-built).
-            time: Time point.
-            time_range: Time range.
-            **kwargs: Additional Annotation parameters.
-
-        Returns:
-            Added annotation.
-
-        Raises:
-            ValueError: If layer is locked.
-        """
-        if self.locked:
-            raise ValueError(f"Layer '{self.name}' is locked")
-
-        if annotation is None:
-            annotation = Annotation(
-                text=text,
-                time=time,
-                time_range=time_range,
-                color=kwargs.pop("color", self.color),
-                **kwargs,
-            )
-
-        self.annotations.append(annotation)
-        return annotation
-
-    def remove(self, annotation: Annotation) -> bool:
-        """Remove annotation from layer.
-
-        Args:
-            annotation: Annotation to remove.
-
-        Returns:
-            True if removed, False if not found.
-
-        Raises:
-            ValueError: If layer is locked.
-        """
-        if self.locked:
-            raise ValueError(f"Layer '{self.name}' is locked")
-
-        try:
-            self.annotations.remove(annotation)
-            return True
-        except ValueError:
-            return False
-
-    def find_at_time(
-        self,
-        time: float,
-        tolerance: float = 0.0,
-    ) -> list[Annotation]:
-        """Find annotations at or near a specific time.
-
-        Args:
-            time: Time to search.
-            tolerance: Time tolerance for matching.
-
-        Returns:
-            List of matching annotations.
-        """
-        matches = []
-        for ann in self.annotations:
-            if ann.time is not None:
-                if abs(ann.time - time) <= tolerance:
-                    matches.append(ann)
-            elif ann.time_range is not None and (
-                ann.time_range[0] - tolerance <= time <= ann.time_range[1] + tolerance
-            ):
-                matches.append(ann)
-        return matches
-
-    def find_in_range(
-        self,
-        start_time: float,
-        end_time: float,
-    ) -> list[Annotation]:
-        """Find annotations within a time range.
-
-        Args:
-            start_time: Range start.
-            end_time: Range end.
-
-        Returns:
-            List of annotations within range.
-        """
-        matches = []
-        for ann in self.annotations:
-            ann_start = ann.start_time
-            ann_end = ann.end_time
-
-            if ann_start is not None and (
-                start_time <= ann_start <= end_time
-                or (ann_end is not None and ann_start <= end_time and ann_end >= start_time)
-            ):
-                matches.append(ann)
-
-        return matches
-
-    def clear(self) -> int:
-        """Remove all annotations.
-
-        Returns:
-            Number of annotations removed.
-
-        Raises:
-            ValueError: If layer is locked.
-        """
-        if self.locked:
-            raise ValueError(f"Layer '{self.name}' is locked")
-
-        count = len(self.annotations)
-        self.annotations.clear()
-        return count
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "name": self.name,
-            "annotations": [a.to_dict() for a in self.annotations],
-            "visible": self.visible,
-            "locked": self.locked,
-            "color": self.color,
-            "description": self.description,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> AnnotationLayer:
-        """Create from dictionary."""
-        annotations = [Annotation.from_dict(a) for a in data.get("annotations", [])]
-        return cls(
-            name=data["name"],
-            annotations=annotations,
-            visible=data.get("visible", True),
-            locked=data.get("locked", False),
-            color=data.get("color", "#FF6B6B"),
-            description=data.get("description", ""),
-        )
-
-
-__all__ = [
-    "Annotation",
-    "AnnotationLayer",
-    "AnnotationType",
-]

oscura/session/history.py

@@ -1,313 +0,0 @@
-"""Operation history tracking.
-
-This module provides operation history tracking for analysis sessions.
-
-
-Example:
-    >>> history = OperationHistory()
-    >>> history.record('load', {'file': 'capture.wfm'})
-    >>> history.record('measure_rise_time', {'result': 1.5e-9})
-    >>> print(history.to_script())
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any
-
-
-@dataclass
-class HistoryEntry:
-    """Single history entry recording an operation.
-
-    Attributes:
-        operation: Operation name (function/method called)
-        parameters: Input parameters
-        result: Operation result (summary)
-        timestamp: When operation was performed
-        duration_ms: Operation duration in milliseconds
-        success: Whether operation succeeded
-        error_message: Error message if failed
-        metadata: Additional metadata
-    """
-
-    operation: str
-    parameters: dict[str, Any] = field(default_factory=dict)
-    result: Any = None
-    timestamp: datetime = field(default_factory=datetime.now)
-    duration_ms: float = 0.0
-    success: bool = True
-    error_message: str | None = None
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "operation": self.operation,
-            "parameters": self.parameters,
-            "result": self._serialize_result(self.result),
-            "timestamp": self.timestamp.isoformat(),
-            "duration_ms": self.duration_ms,
-            "success": self.success,
-            "error_message": self.error_message,
-            "metadata": self.metadata,
-        }
-
-    @staticmethod
-    def _serialize_result(result: Any) -> Any:
-        """Serialize result for JSON storage."""
-        if result is None:
-            return None
-        if isinstance(result, str | int | float | bool):
-            return result
-        if isinstance(result, dict):
-            return {k: HistoryEntry._serialize_result(v) for k, v in result.items()}
-        if isinstance(result, list | tuple):
-            return [HistoryEntry._serialize_result(v) for v in result]
-        # For complex objects, store string representation
-        return str(result)
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> HistoryEntry:
-        """Create from dictionary."""
-        data = data.copy()
-        if "timestamp" in data and isinstance(data["timestamp"], str):
-            data["timestamp"] = datetime.fromisoformat(data["timestamp"])
-        return cls(**data)
-
-    def to_code(self) -> str:
-        """Generate Python code to replay this operation.
-
-        Returns:
-            Python code string.
-        """
-        # Format parameters
-        params = []
-        for k, v in self.parameters.items():
-            if isinstance(v, str):
-                params.append(f'{k}="{v}"')
-            else:
-                params.append(f"{k}={v!r}")
-
-        param_str = ", ".join(params)
-        return f"osc.{self.operation}({param_str})"
-
-
-@dataclass
-class OperationHistory:
-    """History of analysis operations.
-
-    Supports recording, replaying, and exporting operation history.
-
-    Attributes:
-        entries: List of history entries
-        max_entries: Maximum entries to keep (0 = unlimited)
-        auto_record: Whether to automatically record operations
-    """
-
-    entries: list[HistoryEntry] = field(default_factory=list)
-    max_entries: int = 0
-    auto_record: bool = True
-    _current_session_start: datetime = field(default_factory=datetime.now)
-
-    def record(
-        self,
-        operation: str,
-        parameters: dict[str, Any] | None = None,
-        result: Any = None,
-        duration_ms: float = 0.0,
-        success: bool = True,
-        error_message: str | None = None,
-        **metadata: Any,
-    ) -> HistoryEntry:
-        """Record an operation.
-
-        Args:
-            operation: Operation name.
-            parameters: Input parameters.
-            result: Operation result.
-            duration_ms: Duration in milliseconds.
-            success: Whether operation succeeded.
-            error_message: Error message if failed.
-            **metadata: Additional metadata.
-
-        Returns:
-            Created history entry.
-        """
-        entry = HistoryEntry(
-            operation=operation,
-            parameters=parameters or {},
-            result=result,
-            duration_ms=duration_ms,
-            success=success,
-            error_message=error_message,
-            metadata=metadata,
-        )
-
-        self.entries.append(entry)
-
-        # Trim if exceeded max entries
-        if self.max_entries > 0 and len(self.entries) > self.max_entries:
-            self.entries = self.entries[-self.max_entries :]
-
-        return entry
-
-    def undo(self) -> HistoryEntry | None:
-        """Remove and return the last entry.
-
-        Returns:
-            Removed entry, or None if empty.
-        """
-        if self.entries:
-            return self.entries.pop()
-        return None
-
-    def clear(self) -> int:
-        """Clear all history.
-
-        Returns:
-            Number of entries cleared.
-        """
-        count = len(self.entries)
-        self.entries.clear()
-        return count
-
-    def find(
-        self,
-        operation: str | None = None,
-        success_only: bool = False,
-        since: datetime | None = None,
-    ) -> list[HistoryEntry]:
-        """Find entries matching criteria.
-
-        Args:
-            operation: Filter by operation name.
-            success_only: Only return successful operations.
-            since: Only return entries after this time.
-
-        Returns:
-            Matching entries.
-        """
-        results = []
-        for entry in self.entries:
-            if operation and entry.operation != operation:
-                continue
-            if success_only and not entry.success:
-                continue
-            if since and entry.timestamp < since:
-                continue
-            results.append(entry)
-        return results
-
-    def to_script(
-        self,
-        include_imports: bool = True,
-        include_comments: bool = True,
-    ) -> str:
-        """Export history as Python script.
-
-        Args:
-            include_imports: Include import statements.
-            include_comments: Include timestamp comments.
-
-        Returns:
-            Python script string.
-
-        Example:
-            >>> script = history.to_script()
-            >>> print(script)
-            # Generated by Oscura
-            import oscura as osc
-            osc.load("capture.wfm")
-            result = osc.measure_rise_time()
-        """
-        lines = []
-
-        if include_imports:
-            lines.extend(
-                [
-                    "#!/usr/bin/env python3",
-                    '"""Oscura analysis script.',
-                    "",
-                    f"Generated: {datetime.now().isoformat()}",
-                    '"""',
-                    "",
-                    "import oscura as osc",
-                    "",
-                ]
-            )
-
-        for entry in self.entries:
-            if not entry.success:
-                continue
-
-            if include_comments:
-                lines.append(f"# {entry.timestamp.strftime('%H:%M:%S')} - {entry.operation}")
-
-            lines.append(entry.to_code())
-            lines.append("")
-
-        return "\n".join(lines)
-
-    def summary(self) -> dict[str, Any]:
-        """Get history summary statistics.
-
-        Returns:
-            Dictionary with summary statistics.
-        """
-        if not self.entries:
-            return {
-                "total_operations": 0,
-                "successful": 0,
-                "failed": 0,
-                "total_duration_ms": 0,
-                "unique_operations": 0,
-            }
-
-        successful = sum(1 for e in self.entries if e.success)
-        failed = len(self.entries) - successful
-        total_duration = sum(e.duration_ms for e in self.entries)
-        unique_ops = len({e.operation for e in self.entries})
-
-        # Operation frequency
-        op_counts: dict[str, int] = {}
-        for entry in self.entries:
-            op_counts[entry.operation] = op_counts.get(entry.operation, 0) + 1
-
-        return {
-            "total_operations": len(self.entries),
-            "successful": successful,
-            "failed": failed,
-            "total_duration_ms": total_duration,
-            "unique_operations": unique_ops,
-            "operation_counts": op_counts,
-            "session_start": self._current_session_start.isoformat(),
-            "last_operation": self.entries[-1].timestamp.isoformat() if self.entries else None,
-        }
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "entries": [e.to_dict() for e in self.entries],
-            "max_entries": self.max_entries,
-            "session_start": self._current_session_start.isoformat(),
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> OperationHistory:
-        """Create from dictionary."""
-        entries = [HistoryEntry.from_dict(e) for e in data.get("entries", [])]
-        history = cls(
-            entries=entries,
-            max_entries=data.get("max_entries", 0),
-        )
-        if "session_start" in data:
-            history._current_session_start = datetime.fromisoformat(data["session_start"])
-        return history
-
-
-__all__ = [
-    "HistoryEntry",
-    "OperationHistory",
-]