oscura 0.8.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

oscura/loaders/tss.py

@@ -13,7 +13,7 @@ A .tss session file typically contains:
 Example:
     >>> import oscura as osc
     >>> trace = osc.load("oscilloscope_session.tss")
-    >>> print(f"Channel: {trace.metadata.channel_name}")
+    >>> print(f"Channel: {trace.metadata.channel}")
     >>> print(f"Sample rate: {trace.metadata.sample_rate} Hz")
 
     >>> # Load specific channel
@@ -93,7 +93,7 @@ def load_tss(
         )
 
     # Select channel
-    trace, channel_name = _select_channel(waveforms, channel, path)
+    trace, channel = _select_channel(waveforms, channel, path)
 
     # Enrich metadata with session information
     try:
@@ -317,18 +317,18 @@ def _load_all_waveforms(path: Path) -> dict[str, WaveformTrace | DigitalTrace |
 
         for wfm_name in sorted(wfm_files):  # Sort for consistent ordering
             # Derive channel name from filename
-            channel_name = _derive_channel_name(wfm_name)
+            channel = _derive_channel(wfm_name)
 
             # Load waveform
             trace = _load_wfm_from_archive(zf, wfm_name, path)
 
             # Store with normalized channel name
-            waveforms[channel_name] = trace
+            waveforms[channel] = trace
 
     return waveforms
 
 
-def _derive_channel_name(wfm_filename: str) -> str:
+def _derive_channel(wfm_filename: str) -> str:
     """Derive channel name from .wfm filename.
 
     Args:
@@ -338,13 +338,13 @@ def _derive_channel_name(wfm_filename: str) -> str:
         Normalized channel name (lowercase, e.g., "ch1", "ch2", "d0").
 
     Examples:
-        >>> _derive_channel_name("CH1.wfm")
+        >>> _derive_channel("CH1.wfm")
         'ch1'
-        >>> _derive_channel_name("subdir/CH2_Voltage.wfm")
+        >>> _derive_channel("subdir/CH2_Voltage.wfm")
         'ch2'
-        >>> _derive_channel_name("D0.wfm")
+        >>> _derive_channel("D0.wfm")
         'd0'
-        >>> _derive_channel_name("MATH1.wfm")
+        >>> _derive_channel("MATH1.wfm")
         'math1'
     """
     # Get base filename without path
@@ -373,27 +373,27 @@ def _select_channel(
         path: Path to session file (for error messages).
 
     Returns:
-        Tuple of (selected_trace, channel_name).
+        Tuple of (selected_trace, channel).
 
     Raises:
         LoaderError: If channel not found or index out of range.
     """
     if channel is None:
         # Default: first channel (alphabetically sorted)
-        channel_name = sorted(waveforms.keys())[0]
-        return waveforms[channel_name], channel_name
+        channel = sorted(waveforms.keys())[0]
+        return waveforms[channel], channel
 
     if isinstance(channel, int):
         # Select by index
-        channel_names = sorted(waveforms.keys())
-        if channel < 0 or channel >= len(channel_names):
+        channels = sorted(waveforms.keys())
+        if channel < 0 or channel >= len(channels):
             raise LoaderError(
                 f"Channel index {channel} out of range",
                 file_path=str(path),
-                fix_hint=f"Available channels: {', '.join(channel_names)} (indices 0-{len(channel_names) - 1})",
+                fix_hint=f"Available channels: {', '.join(channels)} (indices 0-{len(channels) - 1})",
             )
-        channel_name = channel_names[channel]
-        return waveforms[channel_name], channel_name
+        channel = channels[channel]
+        return waveforms[channel], channel
 
     # Select by name (case-insensitive)
     channel_lower = channel.lower()
@@ -426,26 +426,19 @@ def _enrich_metadata_from_session(
         Trace with enriched metadata.
     """
     # Create new metadata with session information
-    from dataclasses import replace
 
     metadata = trace.metadata
 
-    # Update source file to point to .tss instead of temp .wfm
-    metadata = replace(metadata, source_file=source_file)
-
-    # Add trigger info from session if available
-    if "trigger" in session_metadata and metadata.trigger_info is None:
-        metadata = replace(metadata, trigger_info=session_metadata["trigger"])
+    # Note: source_file and trigger_info attributes removed from TraceMetadata
 
     # Return trace with updated metadata
     if isinstance(trace, WaveformTrace):
         return WaveformTrace(data=trace.data, metadata=metadata)
     if isinstance(trace, DigitalTrace):
-        return DigitalTrace(data=trace.data, metadata=metadata, edges=trace.edges)
+        return DigitalTrace(data=trace.data, metadata=metadata)
     # IQTrace
     return IQTrace(
-        i_data=trace.i_data,
-        q_data=trace.q_data,
+        data=trace.data,
         metadata=metadata,
     )
 

oscura/loaders/validation.py

@@ -475,24 +475,31 @@ class PacketValidator:
 
     @staticmethod
     def _crc32(data: bytes, poly: int = 0xEDB88320) -> int:
-        """Compute CRC-32 checksum.
+        """Compute CRC-32 checksum using native implementation.
 
         Args:
             data: Data to checksum.
             poly: CRC polynomial (default: 0xEDB88320 for CRC-32).
+                  Note: Only standard CRC-32 polynomial is supported by native implementation.
 
         Returns:
             CRC-32 value.
+
+        Note:
+            Uses zlib.crc32() for performance (~100x faster than pure Python).
+            Custom polynomials are not supported - raises ValueError if non-standard poly provided.
         """
-        crc = 0xFFFFFFFF
-        for byte in data:
-            crc ^= byte
-            for _ in range(8):
-                if crc & 1:
-                    crc = (crc >> 1) ^ poly
-                else:
-                    crc >>= 1
-        return crc ^ 0xFFFFFFFF
+        import zlib
+
+        # Verify standard CRC-32 polynomial (zlib only supports this)
+        if poly != 0xEDB88320:
+            raise ValueError(
+                f"Non-standard CRC polynomial {poly:#x} not supported by native implementation. "
+                "Only standard CRC-32 (0xEDB88320) is available."
+            )
+
+        # zlib.crc32 returns signed int on some platforms, mask to unsigned
+        return zlib.crc32(data) & 0xFFFFFFFF
 
     def get_statistics(self) -> ValidationStats:
         """Get aggregate validation statistics.

oscura/loaders/vcd.py

@@ -16,7 +16,7 @@ import mmap
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 from numpy.typing import NDArray
@@ -130,7 +130,7 @@ def load_vcd(
         data, edges = _changes_to_samples(changes, header.timescale, sample_rate)
         metadata = _build_trace_metadata(path, target_var, header, sample_rate)
 
-        return DigitalTrace(data=data.astype(np.bool_), metadata=metadata, edges=edges)
+        return DigitalTrace(data=data.astype(np.bool_), metadata=metadata)
 
     except UnicodeDecodeError as e:
         raise FormatError(
@@ -239,15 +239,20 @@ def _build_trace_metadata(
     path: Path, target_var: VCDVariable, header: VCDHeader, sample_rate: float
 ) -> TraceMetadata:
     """Build trace metadata from VCD information."""
+    # Build trigger_info from VCD header
+    trigger_info: dict[str, Any] = {}
+    if header.timescale is not None:
+        trigger_info["timescale"] = header.timescale
+    if header.date:
+        trigger_info["date"] = header.date
+    if header.version:
+        trigger_info["version"] = header.version
+
     return TraceMetadata(
         sample_rate=sample_rate,
+        channel=target_var.name,
         source_file=str(path),
-        channel_name=target_var.name,
-        trigger_info={
-            "timescale": header.timescale,
-            "var_type": target_var.var_type,
-            "bit_width": target_var.size,
-        },
+        trigger_info=trigger_info if trigger_info else None,
     )
 
 

oscura/loaders/wav.py

@@ -250,13 +250,8 @@ def load_wav(
     # Build metadata
     metadata = TraceMetadata(
         sample_rate=float(sample_rate),
+        channel=channel_name,
         source_file=str(path),
-        channel_name=channel_name,
-        trigger_info={
-            "original_dtype": str(data.dtype),
-            "n_channels": data.shape[1] if data.ndim == 2 else 1,
-            "normalized": normalize,
-        },
     )
 
     return WaveformTrace(data=audio_data, metadata=metadata)

oscura/pipeline/__init__.py

@@ -0,0 +1,76 @@
+"""YAML-based pipeline system for Oscura.
+
+This package provides a complete pipeline execution framework with:
+- YAML configuration for declarative workflows
+- 60+ built-in handlers for common operations
+- Transaction semantics with automatic rollback
+- Conditional logic and parallel execution
+- Template variables and composition
+
+Quick Start:
+    >>> from oscura.pipeline import Pipeline, register_all_handlers
+    >>>
+    >>> # Load and execute a pipeline
+    >>> pipeline = Pipeline.load("analysis.yaml")
+    >>> register_all_handlers(pipeline)
+    >>> results = pipeline.execute()
+    >>>
+    >>> # Access results
+    >>> trace = results.outputs["load_trace"]["trace"]
+    >>> frames = results.outputs["decode_uart"]["frames"]
+
+Example YAML:
+    ```yaml
+    pipeline:
+      name: uart_analysis
+      version: 1.0.0
+      steps:
+        - name: load_trace
+          type: input.file
+          params:
+            path: ${input_file}
+          outputs:
+            trace: waveform
+
+        - name: decode_uart
+          type: decoder.uart
+          inputs:
+            trace: load_trace.waveform
+          params:
+            baud_rate: 115200
+          outputs:
+            frames: decoded_frames
+    ```
+"""
+
+from oscura.core.config.pipeline import (
+    Pipeline,
+    PipelineDefinition,
+    PipelineExecutionError,
+    PipelineResult,
+    PipelineStep,
+    PipelineValidationError,
+)
+from oscura.pipeline.handlers import (
+    get_all_handlers,
+    get_handler,
+    list_handler_types,
+    register_all_handlers,
+    register_handler,
+)
+
+__all__ = [
+    # Core classes
+    "Pipeline",
+    "PipelineDefinition",
+    "PipelineExecutionError",
+    "PipelineResult",
+    "PipelineStep",
+    "PipelineValidationError",
+    "get_all_handlers",
+    "get_handler",
+    "list_handler_types",
+    "register_all_handlers",
+    # Registry functions
+    "register_handler",
+]

oscura/pipeline/handlers/__init__.py

@@ -0,0 +1,165 @@
+"""Pipeline handler registry system.
+
+This module provides a centralized registry for pipeline step handlers.
+Handlers are functions that process specific step types (e.g., "input.file",
+"decoder.uart") and return outputs that can be used by subsequent steps.
+
+Handler Signature:
+    All handlers must follow this signature:
+
+    def handler(inputs: dict[str, Any], params: dict[str, Any], step_name: str) -> dict[str, Any]:
+        '''Handler for step type.
+
+        Args:
+            inputs: Input data from previous steps
+            params: Step parameters from YAML
+            step_name: Name of step being executed (for error reporting)
+
+        Returns:
+            Dictionary of outputs to pass to next steps
+
+        Raises:
+            PipelineExecutionError: If step execution fails
+        '''
+
+Example:
+    >>> from oscura.pipeline.handlers import register_handler
+    >>>
+    >>> @register_handler("custom.step")
+    >>> def handle_custom(inputs: dict[str, Any], params: dict[str, Any], step_name: str) -> dict[str, Any]:
+    ...     result = do_custom_processing(inputs, params)
+    ...     return {"result": result}
+    >>>
+    >>> # Auto-register all handlers
+    >>> from oscura.core.config.pipeline import Pipeline
+    >>> from oscura.pipeline.handlers import register_all_handlers
+    >>>
+    >>> pipeline = Pipeline.load("analysis.yaml")
+    >>> register_all_handlers(pipeline)
+    >>> results = pipeline.execute()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from oscura.core.config.pipeline import Pipeline
+
+
+# Global handler registry
+_HANDLER_REGISTRY: dict[str, Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]]] = {}
+
+
+def register_handler(
+    step_type: str,
+) -> Callable[
+    [Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]]],
+    Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]],
+]:
+    """Decorator to register a handler for a step type.
+
+    Args:
+        step_type: Step type identifier (e.g., "input.file", "decoder.uart")
+
+    Returns:
+        Decorator function
+
+    Example:
+        >>> @register_handler("input.file")
+        >>> def handle_input_file(inputs: dict[str, Any], params: dict[str, Any], step_name: str) -> dict[str, Any]:
+        ...     # Load file and return trace
+        ...     return {"trace": loaded_trace}
+    """
+
+    def decorator(
+        func: Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]],
+    ) -> Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]]:
+        """Register handler function."""
+        _HANDLER_REGISTRY[step_type] = func
+        return func
+
+    return decorator
+
+
+def get_handler(
+    step_type: str,
+) -> Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]] | None:
+    """Get handler for a step type.
+
+    Args:
+        step_type: Step type identifier
+
+    Returns:
+        Handler function or None if not found
+    """
+    return _HANDLER_REGISTRY.get(step_type)
+
+
+def get_all_handlers() -> dict[
+    str, Callable[[dict[str, Any], dict[str, Any], str], dict[str, Any]]
+]:
+    """Get all registered handlers.
+
+    Returns:
+        Dictionary mapping step types to handler functions
+    """
+    return _HANDLER_REGISTRY.copy()
+
+
+def list_handler_types() -> list[str]:
+    """List all registered handler types.
+
+    Returns:
+        Sorted list of step type identifiers
+    """
+    return sorted(_HANDLER_REGISTRY.keys())
+
+
+def register_all_handlers(pipeline: Pipeline) -> None:
+    """Register all handlers with a pipeline.
+
+    This is the main entry point for setting up a pipeline with all
+    available handlers. Import this after importing handler modules.
+
+    Args:
+        pipeline: Pipeline instance to register handlers with
+
+    Example:
+        >>> from oscura.core.config.pipeline import Pipeline
+        >>> from oscura.pipeline.handlers import register_all_handlers
+        >>>
+        >>> pipeline = Pipeline.load("analysis.yaml")
+        >>> register_all_handlers(pipeline)
+        >>> results = pipeline.execute()
+    """
+    for step_type, handler in _HANDLER_REGISTRY.items():
+        pipeline.register_handler(step_type, handler)
+
+
+# Import all handler modules to trigger registration
+# These imports must come after the registry is defined
+from oscura.pipeline.handlers import (
+    analyzers,
+    decoders,
+    exporters,
+    filters,
+    loaders,
+    transforms,
+)
+
+__all__ = [
+    "analyzers",
+    "decoders",
+    "exporters",
+    "filters",
+    "get_all_handlers",
+    "get_handler",
+    "list_handler_types",
+    "loaders",
+    "register_all_handlers",
+    "register_handler",
+    "transforms",
+]