oscura 0.1.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

oscura/automotive/j1939/__init__.py

@@ -4,8 +4,6 @@ This module provides J1939 protocol decoding for heavy-duty vehicles
 (trucks, buses, agriculture, marine).
 """
 
-from __future__ import annotations
-
 __all__ = ["J1939Decoder", "J1939Message", "extract_pgn"]
 
 try:

oscura/automotive/loaders/__init__.py

@@ -8,8 +8,6 @@ This module provides loaders for common automotive logging file formats:
 - PCAP (Packet Capture - SocketCAN)
 """
 
-from __future__ import annotations
-
 __all__ = [
     "detect_format",
     "load_asc",

oscura/automotive/loaders/asc.py

@@ -9,8 +9,6 @@ ASC format example:
     0.010000 1 280 Rx d 8 0A 0B 0C 0D 0E 0F 10 11
 """
 
-from __future__ import annotations
-
 import re
 from pathlib import Path
 

oscura/automotive/loaders/blf.py

@@ -5,8 +5,6 @@ BLF is a proprietary binary format used by Vector tools (CANoe, CANalyzer, etc.)
 for logging CAN bus data.
 """
 
-from __future__ import annotations
-
 from pathlib import Path
 
 from oscura.automotive.can.models import CANMessage, CANMessageList

oscura/automotive/loaders/csv_can.py

@@ -9,8 +9,6 @@ Common CSV format:
     0.010000,0x280,0A0B0C0D0E0F1011
 """
 
-from __future__ import annotations
-
 import csv
 from pathlib import Path
 

oscura/automotive/obd/__init__.py

@@ -4,8 +4,6 @@ This module provides OBD-II (On-Board Diagnostics) protocol decoding
 for standard vehicle diagnostics.
 """
 
-from __future__ import annotations
-
 __all__ = ["PID", "OBD2Decoder", "OBD2Response"]
 
 try:

oscura/automotive/uds/__init__.py

@@ -36,8 +36,6 @@ Example:
     UDSService(0x10 DiagnosticSessionControl [Request], sub=0x01)
 """
 
-from __future__ import annotations
-
 __all__ = [
     "UDSDecoder",
     "UDSNegativeResponse",

oscura/automotive/uds/models.py

@@ -3,8 +3,6 @@
 This module defines the core data structures for UDS protocol analysis.
 """
 
-from __future__ import annotations
-
 from dataclasses import dataclass
 
 __all__ = [

oscura/builders/__init__.py

@@ -7,7 +7,7 @@ generation without manual numpy operations.
 Example:
     >>> import oscura as osc
     >>> # Simple sine wave with noise
-    >>> signal = (osc.SignalBuilder(sample_rate=1e6, duration=0.01)
+    >>> trace = (osc.SignalBuilder(sample_rate=1e6, duration=0.01)
     ...     .add_sine(frequency=1000, amplitude=1.0)
     ...     .add_noise(snr_db=40)
     ...     .build())
@@ -19,23 +19,21 @@ Example:
     ...     .build())
     >>>
     >>> # Multi-channel SPI transaction
-    >>> spi = (osc.SignalBuilder(sample_rate=10e6)
-    ...     .add_spi(clock_freq=1e6, data_mosi=b"\\x9F\\x00\\x00")
-    ...     .build())
+    >>> builder = osc.SignalBuilder(sample_rate=10e6)
+    >>> builder.add_spi(clock_freq=1e6, data_mosi=b"\\x9F\\x00\\x00")
+    >>> channels = builder.build_channels()  # Returns dict[str, WaveformTrace]
+
+API:
+    - SignalBuilder.build() returns WaveformTrace for single-channel signals
+    - SignalBuilder.build_channels() returns dict[str, WaveformTrace] for multi-channel
 
 References:
     - Oscura Signal Generation Guide
     - Protocol Test Signal Specifications
 """
 
-from oscura.builders.signal_builder import (
-    GeneratedSignal,
-    SignalBuilder,
-    SignalMetadata,
-)
+from oscura.builders.signal_builder import SignalBuilder
 
 __all__ = [
-    "GeneratedSignal",
     "SignalBuilder",
-    "SignalMetadata",
 ]

oscura/builders/signal_builder.py

@@ -5,7 +5,7 @@ composition of signals for test data generation, demos, and protocol testing.
 
 Example:
     >>> from oscura import SignalBuilder
-    >>> signal = (SignalBuilder()
+    >>> trace = (SignalBuilder()
     ...     .sample_rate(10e6)
     ...     .duration(0.01)
     ...     .add_sine(frequency=1000, amplitude=1.0)
@@ -16,12 +16,11 @@ The builder supports:
 - Analog waveforms (sine, square, triangle, chirp, multitone)
 - Protocol signals (UART, SPI, I2C, CAN)
 - Noise and impairments (gaussian, pink, jitter, quantization)
-- Multi-channel signals
+- Multi-channel signals (use build_channels() to get all channels)
 """
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
@@ -31,167 +30,6 @@ from scipy import signal as scipy_signal
 from oscura.core.types import TraceMetadata, WaveformTrace
 
 
-@dataclass
-class SignalMetadata:
-    """Metadata for generated signals.
-
-    Attributes:
-        sample_rate: Sample rate in Hz.
-        duration: Signal duration in seconds.
-        channel_names: List of channel names.
-        description: Human-readable description.
-        generator: Name of generator that created this signal.
-        parameters: Dictionary of generation parameters.
-    """
-
-    sample_rate: float
-    duration: float
-    channel_names: list[str] = field(default_factory=lambda: ["ch1"])
-    description: str = ""
-    generator: str = "SignalBuilder"
-    parameters: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class GeneratedSignal:
-    """Container for generated signal data.
-
-    Attributes:
-        data: Dictionary mapping channel names to signal arrays.
-        metadata: Signal metadata.
-    """
-
-    data: dict[str, np.ndarray[Any, np.dtype[np.float64]]]
-    metadata: SignalMetadata
-    _time: np.ndarray[Any, np.dtype[np.float64]] | None = field(default=None, repr=False)
-
-    @property
-    def time(self) -> np.ndarray[Any, np.dtype[np.float64]]:
-        """Get time array, computing if necessary."""
-        if self._time is None:
-            n_samples = len(next(iter(self.data.values())))
-            self._time = np.arange(n_samples) / self.metadata.sample_rate
-        return self._time
-
-    @property
-    def num_channels(self) -> int:
-        """Number of channels in signal."""
-        return len(self.data)
-
-    @property
-    def num_samples(self) -> int:
-        """Number of samples per channel."""
-        return len(next(iter(self.data.values())))
-
-    def get_channel(self, name: str) -> np.ndarray[Any, np.dtype[np.float64]]:
-        """Get signal data for a specific channel.
-
-        Args:
-            name: Channel name.
-
-        Returns:
-            Signal array for the channel.
-
-        Raises:
-            KeyError: If channel name not found.
-        """
-        if name not in self.data:
-            available = list(self.data.keys())
-            raise KeyError(f"Channel '{name}' not found. Available: {available}")
-        return self.data[name]
-
-    def to_trace(self, channel: str | None = None) -> WaveformTrace:
-        """Convert to WaveformTrace for Oscura analysis.
-
-        Args:
-            channel: Channel name to convert. If None, uses first channel.
-
-        Returns:
-            WaveformTrace instance ready for analysis.
-        """
-        if channel is None:
-            channel = self.metadata.channel_names[0]
-
-        data = self.get_channel(channel)
-        trace_meta = TraceMetadata(
-            sample_rate=self.metadata.sample_rate,
-            channel_name=channel,
-        )
-        return WaveformTrace(data=data, metadata=trace_meta)
-
-    def save_npz(self, path: Path | str) -> None:
-        """Save signal to NPZ format.
-
-        Args:
-            path: Output file path.
-        """
-        path = Path(path)
-        path.parent.mkdir(parents=True, exist_ok=True)
-
-        save_dict: dict[str, Any] = {
-            "sample_rate": self.metadata.sample_rate,
-            "duration": self.metadata.duration,
-            "channel_names": np.array(self.metadata.channel_names),
-            "description": self.metadata.description,
-            "generator": self.metadata.generator,
-        }
-
-        # Add channel data
-        for name, data in self.data.items():
-            save_dict[name] = data
-
-        # Add parameters as JSON-serializable
-        for key, value in self.metadata.parameters.items():
-            if isinstance(value, (int, float, str, bool)):
-                save_dict[f"param_{key}"] = value
-
-        np.savez_compressed(path, **save_dict)
-
-    @classmethod
-    def load_npz(cls, path: Path | str) -> GeneratedSignal:
-        """Load signal from NPZ format.
-
-        Args:
-            path: Input file path.
-
-        Returns:
-            GeneratedSignal instance.
-        """
-        path = Path(path)
-        loaded = np.load(path, allow_pickle=True)
-
-        sample_rate = float(loaded["sample_rate"])
-        duration = float(loaded["duration"])
-        channel_names = list(loaded.get("channel_names", ["ch1"]))
-        description = str(loaded.get("description", ""))
-        generator = str(loaded.get("generator", "unknown"))
-
-        # Extract channel data
-        data = {}
-        for name in channel_names:
-            if name in loaded:
-                data[name] = loaded[name]
-
-        # Extract parameters
-        parameters: dict[str, Any] = {}
-        for key in loaded.files:
-            if key.startswith("param_"):
-                param_name = key[6:]  # Remove "param_" prefix
-                value = loaded[key]
-                parameters[param_name] = value.item() if value.ndim == 0 else value
-
-        metadata = SignalMetadata(
-            sample_rate=sample_rate,
-            duration=duration,
-            channel_names=channel_names,
-            description=description,
-            generator=generator,
-            parameters=parameters,
-        )
-
-        return cls(data=data, metadata=metadata)
-
-
 class SignalBuilder:
     """Fluent builder for composable signal generation.
 
@@ -200,7 +38,7 @@ class SignalBuilder:
 
     Example:
         >>> # Simple sine wave with noise
-        >>> signal = (SignalBuilder()
+        >>> trace = (SignalBuilder()
         ...     .sample_rate(1e6)
         ...     .duration(0.01)
         ...     .add_sine(frequency=1000, amplitude=1.0)
@@ -208,7 +46,7 @@ class SignalBuilder:
         ...     .build())
         >>>
         >>> # UART signal with realistic characteristics
-        >>> uart_signal = (SignalBuilder()
+        >>> uart_trace = (SignalBuilder()
         ...     .sample_rate(10e6)
         ...     .add_uart(baud_rate=115200, data=b"Hello Oscura!", config="8N1")
         ...     .add_noise(snr_db=30)
@@ -1050,14 +888,34 @@ class SignalBuilder:
 
     # ========== Build Methods ==========
 
-    def build(self) -> GeneratedSignal:
-        """Build and return signal.
+    def build(self, channel: str | None = None) -> WaveformTrace:
+        """Build and return signal as WaveformTrace.
+
+        This is the primary build method that returns a WaveformTrace ready
+        for analysis with Oscura. For multi-channel signals, specify which
+        channel to return, or use build_channels() to get all channels.
+
+        Args:
+            channel: Channel name to build. If None, uses first channel.
+                For single-channel signals, this parameter is optional.
 
         Returns:
-            GeneratedSignal containing all channels and metadata.
+            WaveformTrace ready for Oscura analysis.
 
         Raises:
-            ValueError: If no signals have been added.
+            ValueError: If no signals have been added or channel doesn't exist.
+
+        Example:
+            >>> builder = SignalBuilder(sample_rate=1e6).add_sine(1000)
+            >>> trace = builder.build()
+            >>> print(f"Generated {len(trace.data)} samples")
+
+            >>> # Multi-channel
+            >>> builder = SignalBuilder(sample_rate=1e6)
+            >>> builder.add_sine(1000, channel="sig")
+            >>> builder.add_square(500, channel="clk")
+            >>> sig_trace = builder.build(channel="sig")
+            >>> clk_trace = builder.build(channel="clk")
         """
         if not self._channels:
             raise ValueError("No signals added. Call add_* methods before build().")
@@ -1068,44 +926,94 @@ class SignalBuilder:
             if len(signal) < max_len:
                 self._channels[name] = np.pad(signal, (0, max_len - len(signal)), mode="edge")
 
-        # Calculate actual duration from signal length
-        actual_duration = max_len / self._sample_rate
+        # Determine which channel to return
+        if channel is None:
+            # Use first channel
+            channel = next(iter(self._channels.keys()))
+        elif channel not in self._channels:
+            available = list(self._channels.keys())
+            raise ValueError(f"Channel '{channel}' not found. Available: {available}")
+
+        # Get channel data
+        data = self._channels[channel]
 
-        metadata = SignalMetadata(
+        # Build TraceMetadata
+        trace_metadata = TraceMetadata(
             sample_rate=self._sample_rate,
-            duration=actual_duration,
-            channel_names=list(self._channels.keys()),
-            description=self._description,
-            generator="SignalBuilder",
-            parameters=self._parameters,
+            channel_name=channel,
         )
 
-        return GeneratedSignal(data=self._channels.copy(), metadata=metadata)
+        return WaveformTrace(data=data, metadata=trace_metadata)
 
-    def build_trace(self, channel: str | None = None) -> WaveformTrace:
-        """Build and return as WaveformTrace for direct use with Oscura.
+    def build_channels(self) -> dict[str, WaveformTrace]:
+        """Build and return all channels as dictionary of WaveformTraces.
 
-        Args:
-            channel: Channel to return as trace. If None, uses first channel.
+        Use this method when you need all channels from a multi-channel
+        signal generation.
 
         Returns:
-            WaveformTrace ready for Oscura analysis.
+            Dictionary mapping channel names to WaveformTrace objects.
+
+        Raises:
+            ValueError: If no signals have been added.
+
+        Example:
+            >>> builder = SignalBuilder(sample_rate=1e6)
+            >>> builder.add_sine(1000, channel="sig")
+            >>> builder.add_square(500, channel="clk")
+            >>> channels = builder.build_channels()
+            >>> print(f"Generated {len(channels)} channels")
+            >>> sig_trace = channels["sig"]
+            >>> clk_trace = channels["clk"]
         """
-        signal = self.build()
-        return signal.to_trace(channel)
+        if not self._channels:
+            raise ValueError("No signals added. Call add_* methods before build().")
+
+        # Ensure all channels have same length (pad if necessary)
+        max_len = max(len(s) for s in self._channels.values())
+        for name, signal in self._channels.items():
+            if len(signal) < max_len:
+                self._channels[name] = np.pad(signal, (0, max_len - len(signal)), mode="edge")
+
+        # Build WaveformTrace for each channel
+        traces: dict[str, WaveformTrace] = {}
+        for channel_name, data in self._channels.items():
+            trace_metadata = TraceMetadata(
+                sample_rate=self._sample_rate,
+                channel_name=channel_name,
+            )
+            traces[channel_name] = WaveformTrace(data=data, metadata=trace_metadata)
+
+        return traces
 
-    def save_npz(self, path: Path | str) -> GeneratedSignal:
+    def save_npz(self, path: Path | str, channel: str | None = None) -> WaveformTrace:
         """Build and save signal to NPZ format.
 
         Args:
             path: Output file path.
+            channel: Channel to save (for multi-channel signals).
 
         Returns:
-            GeneratedSignal that was saved.
+            WaveformTrace that was saved.
+
+        Example:
+            >>> builder = SignalBuilder().sample_rate(1e6).add_sine(1000)
+            >>> trace = builder.save_npz("signal.npz")
         """
-        signal = self.build()
-        signal.save_npz(path)
-        return signal
+        trace = self.build(channel=channel)
+
+        # Save as NPZ using numpy
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        np.savez_compressed(
+            path,
+            data=trace.data,
+            sample_rate=trace.metadata.sample_rate,
+            channel_name=trace.metadata.channel_name or "ch1",
+        )
+
+        return trace
 
     # ========== Internal Methods ==========
 

oscura/cli/main.py

@@ -11,8 +11,6 @@ Example:
     $ oscura shell   # Interactive REPL
 """
 
-from __future__ import annotations
-
 import json
 import logging
 import sys

oscura/cli/shell.py

@@ -23,8 +23,6 @@ References:
     - IPython-style interaction patterns
 """
 
-from __future__ import annotations
-
 import atexit
 import code
 import contextlib

oscura/config/loader.py

@@ -9,8 +9,6 @@ Example:
     >>> config = load_config_file("pipeline.yaml", schema="pipeline")
 """
 
-from __future__ import annotations
-
 import json
 from pathlib import Path
 from typing import Any

oscura/core/backend_selector.py

@@ -43,7 +43,7 @@ except (ImportError, AttributeError):
     HAS_GPU = False
 
 try:
-    import numba  # type: ignore[import-untyped]
+    import numba  # type: ignore[import-not-found]
 
     HAS_NUMBA = True
     del numba

oscura/core/correlation.py

@@ -16,8 +16,6 @@ References:
     - Thread-local and async-safe context management
 """
 
-from __future__ import annotations
-
 import asyncio
 import contextvars
 import functools

oscura/core/exceptions.py

@@ -13,8 +13,6 @@ Example:
     ...
 """
 
-from __future__ import annotations
-
 from typing import Any
 
 # Documentation base URL
@@ -285,6 +283,7 @@ class InsufficientDataError(AnalysisError):
         required: int | None = None,
         available: int | None = None,
         analysis_type: str | None = None,
+        fix_hint: str | None = None,
     ) -> None:
         """Initialize InsufficientDataError.
 
@@ -293,6 +292,7 @@ class InsufficientDataError(AnalysisError):
             required: Minimum number of samples or features required.
             available: Actual number available.
             analysis_type: Type of analysis that failed.
+            fix_hint: Optional custom fix suggestion (overrides default).
         """
         self.required = required
         self.available = available
@@ -303,7 +303,9 @@ class InsufficientDataError(AnalysisError):
         elif required is not None:
             details = f"Minimum required: {required}"
 
-        fix_hint = "Acquire more data or reduce analysis window."
+        # Use default fix hint if not provided
+        if fix_hint is None:
+            fix_hint = "Acquire more data or reduce analysis window."
 
         super().__init__(
             message,
@@ -520,6 +522,61 @@ class ExportError(OscuraError):
         )
 
 
+class SecurityError(OscuraError):
+    """Security validation failed.
+
+    Raised when security checks fail, such as signature verification
+    or file integrity validation.
+
+    Attributes:
+        file_path: Path to the file that failed security checks.
+        check_type: Type of security check that failed.
+    """
+
+    docs_path: str = "errors#security"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        file_path: str | None = None,
+        check_type: str | None = None,
+        details: str | None = None,
+        fix_hint: str | None = None,
+    ) -> None:
+        """Initialize SecurityError.
+
+        Args:
+            message: Brief description of the error.
+            file_path: Path to the file that failed security checks.
+            check_type: Type of security check that failed.
+            details: Additional context about the error.
+            fix_hint: Suggestion for how to fix the error.
+        """
+        self.file_path = file_path
+        self.check_type = check_type
+
+        details_parts = []
+        if file_path:
+            details_parts.append(f"File: {file_path}")
+        if check_type:
+            details_parts.append(f"Check: {check_type}")
+        if details:
+            details_parts.append(details)
+
+        combined_details = ". ".join(details_parts) if details_parts else None
+
+        if fix_hint is None:
+            fix_hint = "Only load files from trusted sources. File may be corrupted or tampered."
+
+        super().__init__(
+            message,
+            details=combined_details,
+            fix_hint=fix_hint,
+            docs_path=self.docs_path,
+        )
+
+
 __all__ = [
     "DOCS_BASE_URL",
     "AnalysisError",
@@ -530,6 +587,7 @@ __all__ = [
     "LoaderError",
     "OscuraError",
     "SampleRateError",
+    "SecurityError",
     "UnsupportedFormatError",
     "ValidationError",
 ]

oscura/core/lazy.py

@@ -49,7 +49,9 @@ from __future__ import annotations
 import functools
 import threading
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+T = TypeVar("T")
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -149,7 +151,7 @@ def reset_lazy_stats() -> None:
         _global_stats = LazyComputeStats()
 
 
-class LazyResult[T]:
+class LazyResult(Generic[T]):
     """Deferred computation wrapper with thread-safe compute-once semantics.
 
     Wraps a computation function that will be called only when the result is
@@ -557,7 +559,7 @@ class LazyDict(dict[str, Any]):
         ]
 
 
-def lazy[T](fn: Callable[..., T]) -> Callable[..., LazyResult[T]]:
+def lazy(fn: Callable[..., T]) -> Callable[..., LazyResult[T]]:
     """Decorator to make a function return a LazyResult.
 
     Wraps a function so it returns a LazyResult instead of computing

oscura/core/memory_limits.py

@@ -13,8 +13,6 @@ References:
     See oscura.config.memory for global memory configuration.
 """
 
-from __future__ import annotations
-
 import warnings
 from typing import Any