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

oscura/{ui → jupyter/ui}/progressive_display.py

@@ -5,7 +5,7 @@ results first with options to drill down into details on demand.
 
 
 Example:
-    >>> from oscura.ui import ProgressiveDisplay
+    >>> from oscura.jupyter.ui import ProgressiveDisplay
     >>> display = ProgressiveDisplay()
     >>> output = display.render(result)
     >>> print(output.summary())  # Level 1: Summary
@@ -215,7 +215,27 @@ class ProgressiveDisplay:
             >>> output = display.render(characterization_result)
             >>> print(output.summary())
         """
-        # Level 1: Build summary (3-5 key items)
+        level1_content = self._build_level1_summary(result)
+        level2_sections = self._build_level2_sections(result)
+        level3_data = self._build_level3_expert_data(result)
+        current_level = self._determine_current_level()
+
+        return ProgressiveOutput(
+            level1_content=level1_content,
+            level2_sections=level2_sections,
+            level3_data=level3_data,
+            current_level=current_level,
+        )
+
+    def _build_level1_summary(self, result: Any) -> str:
+        """Build Level 1 summary content.
+
+        Args:
+            result: Analysis result.
+
+        Returns:
+            Summary string with key items.
+        """
         level1_items = []
 
         if hasattr(result, "signal_type"):
@@ -231,85 +251,136 @@ class ProgressiveDisplay:
         if hasattr(result, "status"):
             level1_items.append(f"Status: {result.status}")
 
-        # Limit to max_summary_items
         level1_items = level1_items[: self.max_summary_items]
 
-        level1_content = "\n".join(level1_items)
-
         if not level1_items:
-            level1_content = "Analysis complete. Expand for details."
+            return "Analysis complete. Expand for details."
+
+        return "\n".join(level1_items)
+
+    def _build_level2_sections(self, result: Any) -> list[Section]:
+        """Build Level 2 detailed sections.
+
+        Args:
+            result: Analysis result.
+
+        Returns:
+            List of Section objects.
+        """
+        sections = []
+
+        params_section = self._build_parameters_section(result)
+        if params_section:
+            sections.append(params_section)
 
-        # Level 2: Build sections
-        level2_sections = []
+        quality_section = self._build_quality_metrics_section(result)
+        if quality_section:
+            sections.append(quality_section)
 
-        # Parameters section
-        if hasattr(result, "parameters") and result.parameters:
-            params = result.parameters
-            summary = f"{len(params)} parameters detected"
+        findings_section = self._build_findings_section(result)
+        if findings_section:
+            sections.append(findings_section)
+
+        return sections
+
+    def _build_parameters_section(self, result: Any) -> Section | None:
+        """Build parameters section.
+
+        Args:
+            result: Analysis result.
 
-            content = "Parameters:\n"
-            for key, value in params.items():
+        Returns:
+            Section or None if no parameters.
+        """
+        if not (hasattr(result, "parameters") and result.parameters):
+            return None
+
+        params = result.parameters
+        summary = f"{len(params)} parameters detected"
+
+        content = "Parameters:\n"
+        for key, value in params.items():
+            content += f"  {key}: {value}\n"
+
+        return Section(
+            title="Parameters",
+            summary=summary,
+            content=content,
+            is_collapsed=self.enable_collapsible_sections,
+            detail_level=2,
+        )
+
+    def _build_quality_metrics_section(self, result: Any) -> Section | None:
+        """Build quality metrics section.
+
+        Args:
+            result: Analysis result.
+
+        Returns:
+            Section or None if no quality data.
+        """
+        if not (hasattr(result, "quality") or hasattr(result, "metrics")):
+            return None
+
+        metrics = getattr(result, "metrics", {})
+        summary = "Quality assessment available"
+        content = "Quality Metrics:\n"
+
+        if hasattr(result, "quality"):
+            content += f"  Overall: {result.quality}\n"
+
+        if metrics:
+            for key, value in metrics.items():
                 content += f"  {key}: {value}\n"
 
-            level2_sections.append(
-                Section(
-                    title="Parameters",
-                    summary=summary,
-                    content=content,
-                    is_collapsed=self.enable_collapsible_sections,
-                    detail_level=2,
-                )
-            )
-
-        # Quality metrics section
-        if hasattr(result, "quality") or hasattr(result, "metrics"):
-            metrics = getattr(result, "metrics", {})
-
-            summary = "Quality assessment available"
-            content = "Quality Metrics:\n"
-
-            if hasattr(result, "quality"):
-                content += f"  Overall: {result.quality}\n"
-
-            if metrics:
-                for key, value in metrics.items():
-                    content += f"  {key}: {value}\n"
-
-            level2_sections.append(
-                Section(
-                    title="Quality Metrics",
-                    summary=summary,
-                    content=content,
-                    is_collapsed=self.enable_collapsible_sections,
-                    detail_level=2,
-                )
-            )
-
-        # Findings section
-        if hasattr(result, "findings") and result.findings:
-            findings = result.findings
-
-            summary = f"{len(findings)} findings"
-            content = "Findings:\n"
-
-            for i, finding in enumerate(findings, 1):
-                if hasattr(finding, "title") and hasattr(finding, "description"):
-                    content += f"\n{i}. {finding.title}\n"
-                    content += f"   {finding.description}\n"
-                else:
-                    content += f"\n{i}. {finding}\n"
-
-            level2_sections.append(
-                Section(
-                    title="Findings",
-                    summary=summary,
-                    content=content,
-                    is_collapsed=self.enable_collapsible_sections,
-                    detail_level=2,
-                )
-            )
-
-        # Level 3: Build expert data
+        return Section(
+            title="Quality Metrics",
+            summary=summary,
+            content=content,
+            is_collapsed=self.enable_collapsible_sections,
+            detail_level=2,
+        )
+
+    def _build_findings_section(self, result: Any) -> Section | None:
+        """Build findings section.
+
+        Args:
+            result: Analysis result.
+
+        Returns:
+            Section or None if no findings.
+        """
+        if not (hasattr(result, "findings") and result.findings):
+            return None
+
+        findings = result.findings
+        summary = f"{len(findings)} findings"
+        content = "Findings:\n"
+
+        for i, finding in enumerate(findings, 1):
+            if hasattr(finding, "title") and hasattr(finding, "description"):
+                content += f"\n{i}. {finding.title}\n"
+                content += f"   {finding.description}\n"
+            else:
+                content += f"\n{i}. {finding}\n"
+
+        return Section(
+            title="Findings",
+            summary=summary,
+            content=content,
+            is_collapsed=self.enable_collapsible_sections,
+            detail_level=2,
+        )
+
+    def _build_level3_expert_data(self, result: Any) -> dict[str, Any]:
+        """Build Level 3 expert data.
+
+        Args:
+            result: Analysis result.
+
+        Returns:
+            Dict of expert-level data.
+        """
         level3_data = {}
 
         if hasattr(result, "raw_data"):
@@ -321,16 +392,16 @@ class ProgressiveDisplay:
         if hasattr(result, "debug_trace"):
             level3_data["debug_trace"] = result.debug_trace
 
-        # Determine current level
-        level_map = {"summary": 1, "intermediate": 2, "expert": 3}
-        current_level = level_map.get(self.default_level, 1)
+        return level3_data
 
-        return ProgressiveOutput(
-            level1_content=level1_content,
-            level2_sections=level2_sections,
-            level3_data=level3_data,
-            current_level=current_level,
-        )
+    def _determine_current_level(self) -> int:
+        """Determine current detail level from default.
+
+        Returns:
+            Current level (1-3).
+        """
+        level_map = {"summary": 1, "intermediate": 2, "expert": 3}
+        return level_map.get(self.default_level, 1)
 
 
 __all__ = [

oscura/loaders/__init__.py

@@ -95,6 +95,7 @@ from oscura.loaders import (
     csv,
     hdf5,
 )
+from oscura.loaders.binary import load_binary
 
 # Import configurable binary loading functionality
 from oscura.loaders.configurable import (
@@ -122,6 +123,44 @@ from oscura.loaders.preprocessing import (
     get_idle_statistics,
     trim_idle,
 )
+
+# LAZY IMPORT: load_touchstone is loaded on first use to avoid 14.5s import penalty
+# The touchstone loader imports signal_integrity which pulls in the entire analyzer chain
+# See .claude/PERFORMANCE_PROFILE_2026-01-25.md for performance analysis
+_load_touchstone_impl: Any = None
+
+
+def load_touchstone(path: str | Path) -> Any:
+    """Load S-parameter data from Touchstone file (lazy import).
+
+    This function uses lazy imports to avoid a 14.5 second import penalty
+    from the touchstone -> signal_integrity -> analyzer dependency chain.
+
+    Supports .s1p through .s8p formats and both Touchstone 1.0
+    and 2.0 file formats.
+
+    Args:
+        path: Path to Touchstone file.
+
+    Returns:
+        SParameterData with loaded S-parameters.
+
+    Raises:
+        LoaderError: If file cannot be read.
+        FormatError: If file format is invalid.
+
+    Example:
+        >>> s_params = load_touchstone("cable.s2p")
+        >>> print(f"Loaded {s_params.n_ports}-port, {len(s_params.frequencies)} points")
+    """
+    global _load_touchstone_impl
+    if _load_touchstone_impl is None:
+        from oscura.loaders.touchstone import load_touchstone as _impl
+
+        _load_touchstone_impl = _impl
+    return _load_touchstone_impl(path)
+
+
 from oscura.loaders.validation import (
     PacketValidator,
     SequenceGap,
@@ -302,7 +341,7 @@ def load_all_channels(
     path: str | PathLike[str],
     *,
     format: str | None = None,
-) -> dict[str, WaveformTrace | DigitalTrace]:
+) -> dict[str, WaveformTrace | DigitalTrace | IQTrace]:
     """Load all channels from a multi-channel waveform file.
 
     Reads the file once and extracts all available channels (both analog
@@ -360,12 +399,12 @@ def load_all_channels(
         # For other formats, try loading as single channel
         trace = load(path, format=format)
         channel_name = getattr(trace.metadata, "channel_name", None) or "ch1"
-        return {channel_name: trace}  # type: ignore[dict-item]
+        return {channel_name: trace}
 
 
 def _load_all_channels_tektronix(
     path: Path,
-) -> dict[str, WaveformTrace | DigitalTrace]:
+) -> dict[str, WaveformTrace | DigitalTrace | IQTrace]:
     """Load all channels from a Tektronix WFM file.
 
     Args:
@@ -377,16 +416,52 @@ def _load_all_channels_tektronix(
     Raises:
         LoaderError: If the file cannot be read or parsed.
     """
+    wfm = _read_tektronix_file(path)
+    channels: dict[str, WaveformTrace | DigitalTrace | IQTrace] = {}
+
+    # Extract analog waveforms
+    _extract_analog_waveforms(wfm, path, channels)
+
+    # Extract digital waveforms
+    _extract_digital_waveforms(wfm, path, channels)
+
+    # Handle direct waveform formats (single file = single channel)
+    if not channels:
+        _extract_direct_waveform(wfm, path, channels)
+
+    if not channels:
+        raise LoaderError(
+            "No channels found in file",
+            file_path=str(path),
+            fix_hint="File may be empty or use an unsupported format variant.",
+        )
+
+    return channels
+
+
+def _read_tektronix_file(path: Path) -> Any:
+    """Read Tektronix WFM file, falling back to single channel if tm_data_types unavailable.
+
+    Args:
+        path: Path to file.
+
+    Returns:
+        WFM file object.
+
+    Raises:
+        LoaderError: If file cannot be read.
+    """
     try:
-        import tm_data_types  # type: ignore[import-not-found, import-untyped]
+        import tm_data_types  # type: ignore[import-untyped]
     except ImportError:
         # Fall back to single channel loading
         trace = load(path, format="tektronix")
         channel_name = getattr(trace.metadata, "channel_name", None) or "ch1"
-        return {channel_name: trace}  # type: ignore[dict-item]
+        # Return a dict-like object to maintain compatibility
+        return {"__fallback__": {channel_name: trace}}
 
     try:
-        wfm = tm_data_types.read_file(str(path))
+        return tm_data_types.read_file(str(path))
     except Exception as e:
         raise LoaderError(
             "Failed to read Tektronix WFM file",
@@ -394,72 +469,103 @@ def _load_all_channels_tektronix(
             details=str(e),
         ) from e
 
-    channels: dict[str, WaveformTrace | DigitalTrace] = {}
 
-    # Extract analog waveforms
-    if hasattr(wfm, "analog_waveforms") and wfm.analog_waveforms:
-        import numpy as np
-
-        from oscura.loaders.tektronix import _build_waveform_trace
-
-        for i, awfm in enumerate(wfm.analog_waveforms):
-            try:
-                data = np.array(awfm.y_data, dtype=np.float64)
-                x_increment = getattr(awfm, "x_increment", 1e-6)
-                sample_rate = 1.0 / x_increment if x_increment > 0 else 1e6
-                vertical_scale = getattr(awfm, "y_scale", None)
-                vertical_offset = getattr(awfm, "y_offset", None)
-                channel_name = getattr(awfm, "name", f"CH{i + 1}")
-
-                trace = _build_waveform_trace(
-                    data=data,
-                    sample_rate=sample_rate,
-                    vertical_scale=vertical_scale,
-                    vertical_offset=vertical_offset,
-                    channel_name=channel_name,
-                    path=path,
-                    wfm=awfm,
-                )
-                channels[f"ch{i + 1}"] = trace
-            except Exception as e:
-                logger.warning("Failed to extract analog channel %d: %s", i + 1, e)
+def _extract_analog_waveforms(
+    wfm: Any, path: Path, channels: dict[str, WaveformTrace | DigitalTrace | IQTrace]
+) -> None:
+    """Extract analog waveforms from WFM file.
 
-    # Extract digital waveforms
-    if hasattr(wfm, "digital_waveforms") and wfm.digital_waveforms:
-        from oscura.loaders.tektronix import _load_digital_waveform
+    Args:
+        wfm: WFM file object.
+        path: Path to file.
+        channels: Dictionary to populate with channels.
+    """
+    if not hasattr(wfm, "analog_waveforms") or not wfm.analog_waveforms:
+        return
+
+    import numpy as np
+
+    from oscura.loaders.tektronix import _build_waveform_trace
+
+    for i, awfm in enumerate(wfm.analog_waveforms):
+        try:
+            data = np.array(awfm.y_data, dtype=np.float64)
+            x_increment = getattr(awfm, "x_increment", 1e-6)
+            sample_rate = 1.0 / x_increment if x_increment > 0 else 1e6
+            vertical_scale = getattr(awfm, "y_scale", None)
+            vertical_offset = getattr(awfm, "y_offset", None)
+            channel_name = getattr(awfm, "name", f"CH{i + 1}")
+
+            trace = _build_waveform_trace(
+                data=data,
+                sample_rate=sample_rate,
+                vertical_scale=vertical_scale,
+                vertical_offset=vertical_offset,
+                channel_name=channel_name,
+                path=path,
+                wfm=awfm,
+            )
+            channels[f"ch{i + 1}"] = trace
+        except Exception as e:
+            logger.warning("Failed to extract analog channel %d: %s", i + 1, e)
 
-        for i, dwfm in enumerate(wfm.digital_waveforms):
-            try:
-                trace = _load_digital_waveform(dwfm, path, i)
-                channels[f"d{i + 1}"] = trace
-            except Exception as e:
-                logger.warning("Failed to extract digital channel %d: %s", i + 1, e)
 
-    # Handle direct waveform formats (single file = single channel)
-    if not channels:
-        wfm_type = type(wfm).__name__
+def _extract_digital_waveforms(
+    wfm: Any, path: Path, channels: dict[str, WaveformTrace | DigitalTrace | IQTrace]
+) -> None:
+    """Extract digital waveforms from WFM file.
 
-        if wfm_type == "DigitalWaveform" or hasattr(wfm, "y_axis_byte_values"):
-            from oscura.loaders.tektronix import _load_digital_waveform
+    Args:
+        wfm: WFM file object.
+        path: Path to file.
+        channels: Dictionary to populate with channels.
+    """
+    if not hasattr(wfm, "digital_waveforms") or not wfm.digital_waveforms:
+        return
 
-            trace = _load_digital_waveform(wfm, path, 0)
-            channel_name = trace.metadata.channel_name or "d1"
-            channels[channel_name.lower()] = trace
+    from oscura.loaders.tektronix import _load_digital_waveform
 
-        elif hasattr(wfm, "y_axis_values") or hasattr(wfm, "y_data"):
-            # Direct analog waveform
-            trace = load(path, format="tektronix")
-            channel_name = trace.metadata.channel_name or "ch1"
-            channels[channel_name.lower()] = trace  # type: ignore[assignment]
+    for i, dwfm in enumerate(wfm.digital_waveforms):
+        try:
+            trace = _load_digital_waveform(dwfm, path, i)
+            channels[f"d{i + 1}"] = trace
+        except Exception as e:
+            logger.warning("Failed to extract digital channel %d: %s", i + 1, e)
 
-    if not channels:
-        raise LoaderError(
-            "No channels found in file",
-            file_path=str(path),
-            fix_hint="File may be empty or use an unsupported format variant.",
-        )
 
-    return channels
+def _extract_direct_waveform(
+    wfm: Any, path: Path, channels: dict[str, WaveformTrace | DigitalTrace | IQTrace]
+) -> None:
+    """Extract single channel from direct waveform format.
+
+    Args:
+        wfm: WFM file object.
+        path: Path to file.
+        channels: Dictionary to populate with channels.
+    """
+    wfm_type = type(wfm).__name__
+
+    if wfm_type == "DigitalWaveform" or hasattr(wfm, "y_axis_byte_values"):
+        from oscura.loaders.tektronix import _load_digital_waveform
+
+        trace = _load_digital_waveform(wfm, path, 0)
+        channel_name = trace.metadata.channel_name or "d1"
+        channels[channel_name.lower()] = trace
+
+    elif wfm_type == "IQWaveform" or (
+        hasattr(wfm, "i_axis_values") and hasattr(wfm, "q_axis_values")
+    ):
+        # IQWaveform format (RF/SDR data)
+        loaded_trace = load(path, format="tektronix")
+        channel_name = loaded_trace.metadata.channel_name or "iq1"
+        channels[channel_name.lower()] = loaded_trace
+
+    elif hasattr(wfm, "y_axis_values") or hasattr(wfm, "y_data"):
+        # Direct analog waveform
+        loaded_trace = load(path, format="tektronix")
+        # Add both analog and digital traces to channels
+        channel_name = loaded_trace.metadata.channel_name or "ch1"
+        channels[channel_name.lower()] = loaded_trace
 
 
 def get_supported_formats() -> list[str]:
@@ -535,9 +641,11 @@ __all__ = [
     "hdf5",
     "load",
     "load_all_channels",
+    "load_binary",
     "load_binary_packets",
     "load_lazy",
     "load_packets_streaming",
+    "load_touchstone",
     "load_trace_lazy",
     "trim_idle",
 ]