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

oscura/{onboarding → cli/onboarding}/wizard.py

@@ -9,7 +9,7 @@ non-expert users analyze their signals with intelligent recommendations.
   - Result interpretation
 
 Example:
-    >>> from oscura.onboarding import run_wizard
+    >>> from oscura.cli.onboarding import run_wizard
     >>> run_wizard(trace)
     Analysis Wizard
     Step 1: What type of signal is this?
@@ -403,45 +403,64 @@ class AnalysisWizard:
         """Generate a human-readable summary of the analysis."""
         lines = ["Analysis Summary:"]
 
+        self._add_signal_type_summary(lines)
+        self._add_frequency_summary(lines)
+        self._add_rise_time_summary(lines)
+        self._add_thd_summary(lines)
+        self._add_snr_summary(lines)
+
+        self.result.summary = "\n".join(lines)
+
+    def _add_signal_type_summary(self, lines: list[str]) -> None:
+        """Add signal type to summary."""
         if "signal_type" in self.result.measurements:
             lines.append(f"  Signal type: {self.result.measurements['signal_type']}")
 
-        if "frequency" in self.result.measurements:
-            freq = self.result.measurements["frequency"]
-            # Handle dict format from measure()
-            if isinstance(freq, dict):
-                freq = freq.get("value", 0)
+    def _add_frequency_summary(self, lines: list[str]) -> None:
+        """Add frequency to summary with appropriate units."""
+        if "frequency" not in self.result.measurements:
+            return
 
-            if freq >= 1e6:
-                lines.append(f"  Frequency: {freq / 1e6:.3f} MHz")
-            elif freq >= 1e3:
-                lines.append(f"  Frequency: {freq / 1e3:.3f} kHz")
-            else:
-                lines.append(f"  Frequency: {freq:.1f} Hz")
-
-        if "rise_time" in self.result.measurements:
-            rt = self.result.measurements["rise_time"]
-            # Handle dict format from measure()
-            if isinstance(rt, dict):
-                rt = rt.get("value", 0)
-
-            lines.append(f"  Rise time: {rt * 1e9:.2f} ns")
-
-        if "thd" in self.result.measurements:
-            thd = self.result.measurements["thd"]
-            # Handle dict format
-            if isinstance(thd, dict):
-                thd = thd.get("value", 0)
-            lines.append(f"  THD: {thd:.1f} dB")
-
-        if "snr" in self.result.measurements:
-            snr = self.result.measurements["snr"]
-            # Handle dict format
-            if isinstance(snr, dict):
-                snr = snr.get("value", 0)
-            lines.append(f"  SNR: {snr:.1f} dB")
+        freq = self._extract_value(self.result.measurements["frequency"])
+        if freq >= 1e6:
+            lines.append(f"  Frequency: {freq / 1e6:.3f} MHz")
+        elif freq >= 1e3:
+            lines.append(f"  Frequency: {freq / 1e3:.3f} kHz")
+        else:
+            lines.append(f"  Frequency: {freq:.1f} Hz")
+
+    def _add_rise_time_summary(self, lines: list[str]) -> None:
+        """Add rise time to summary."""
+        if "rise_time" not in self.result.measurements:
+            return
 
-        self.result.summary = "\n".join(lines)
+        rt = self._extract_value(self.result.measurements["rise_time"])
+        lines.append(f"  Rise time: {rt * 1e9:.2f} ns")
+
+    def _add_thd_summary(self, lines: list[str]) -> None:
+        """Add THD to summary."""
+        if "thd" not in self.result.measurements:
+            return
+
+        thd = self._extract_value(self.result.measurements["thd"])
+        lines.append(f"  THD: {thd:.1f} dB")
+
+    def _add_snr_summary(self, lines: list[str]) -> None:
+        """Add SNR to summary."""
+        if "snr" not in self.result.measurements:
+            return
+
+        snr = self._extract_value(self.result.measurements["snr"])
+        lines.append(f"  SNR: {snr:.1f} dB")
+
+    @staticmethod
+    def _extract_value(measurement: Any) -> float:
+        """Extract numeric value from measurement (handles dict format)."""
+        if isinstance(measurement, dict):
+            value: float = float(measurement.get("value", 0))
+            return value
+        result: float = float(measurement)
+        return result
 
 
 def run_wizard(trace: Any, interactive: bool = True) -> WizardResult:
@@ -458,7 +477,7 @@ def run_wizard(trace: Any, interactive: bool = True) -> WizardResult:
 
     Example:
         >>> import oscura as osc
-        >>> from oscura.onboarding import run_wizard
+        >>> from oscura.cli.onboarding import run_wizard
         >>> trace = osc.load("signal.csv")
         >>> result = run_wizard(trace)
     """

oscura/cli/progress.py

@@ -0,0 +1,147 @@
+"""Progress reporting utilities for CLI commands.
+
+Provides progress bars, status messages, and ETA calculations for long-running
+operations.
+
+
+Example:
+    >>> progress = ProgressReporter(stages=3)
+    >>> progress.start_stage("Loading data")
+    >>> # ... work ...
+    >>> progress.complete_stage()
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any
+
+try:
+    from tqdm import tqdm
+
+    TQDM_AVAILABLE = True
+except ImportError:
+    TQDM_AVAILABLE = False
+
+
+class ProgressReporter:
+    """Progress reporter for multi-stage operations.
+
+    Displays progress bars (if tqdm available) or status messages for
+    long-running CLI operations.
+
+    Args:
+        quiet: If True, suppress all output.
+        stages: Number of stages in operation.
+        use_tqdm: Force tqdm usage (default: auto-detect).
+
+    Example:
+        >>> reporter = ProgressReporter(stages=3)
+        >>> reporter.start_stage("Stage 1")
+        >>> time.sleep(1)
+        >>> reporter.complete_stage()
+        >>> reporter.start_stage("Stage 2")
+        >>> time.sleep(1)
+        >>> reporter.complete_stage()
+        >>> reporter.finish()
+    """
+
+    def __init__(
+        self,
+        quiet: bool = False,
+        stages: int = 1,
+        use_tqdm: bool | None = None,
+    ) -> None:
+        """Initialize progress reporter.
+
+        Args:
+            quiet: Suppress all output.
+            stages: Total number of stages.
+            use_tqdm: Force tqdm usage (None = auto-detect).
+        """
+        self.quiet = quiet
+        self.total_stages = stages
+        self.current_stage = 0
+        self.stage_name = ""
+        self.start_time = time.time()
+        self.stage_start = time.time()
+
+        # Determine if we can use tqdm
+        if use_tqdm is None:
+            self.use_tqdm = TQDM_AVAILABLE and not quiet and sys.stdout.isatty()
+        else:
+            self.use_tqdm = use_tqdm and TQDM_AVAILABLE and not quiet
+
+        self.pbar: Any = None
+        if self.use_tqdm:
+            self.pbar = tqdm(total=stages, desc="Progress", unit="stage")
+
+    def start_stage(self, name: str) -> None:
+        """Start a new stage.
+
+        Args:
+            name: Stage name/description.
+        """
+        self.current_stage += 1
+        self.stage_name = name
+        self.stage_start = time.time()
+
+        if not self.quiet:
+            if self.use_tqdm and self.pbar:
+                self.pbar.set_description(f"{name}")
+            else:
+                timestamp = time.strftime("%H:%M:%S")
+                print(
+                    f"[{timestamp}] [{self.current_stage}/{self.total_stages}] {name}...",
+                    file=sys.stderr,
+                )
+
+    def complete_stage(self) -> None:
+        """Mark current stage as complete."""
+        stage_duration = time.time() - self.stage_start
+
+        if not self.quiet:
+            if self.use_tqdm and self.pbar:
+                self.pbar.update(1)
+            else:
+                timestamp = time.strftime("%H:%M:%S")
+                print(
+                    f"[{timestamp}] {self.stage_name} completed ({stage_duration:.1f}s)",
+                    file=sys.stderr,
+                )
+
+    def update_progress(self, current: int, total: int, message: str = "") -> None:
+        """Update progress within current stage.
+
+        Args:
+            current: Current progress value.
+            total: Total progress value.
+            message: Optional progress message.
+        """
+        if not self.quiet and not self.use_tqdm:
+            pct = (current / total * 100) if total > 0 else 0
+            msg = f"{message} " if message else ""
+            print(f"  {msg}{current}/{total} ({pct:.1f}%)", file=sys.stderr, end="\r")
+
+    def finish(self) -> None:
+        """Finish progress reporting."""
+        total_duration = time.time() - self.start_time
+
+        if not self.quiet:
+            if self.use_tqdm and self.pbar:
+                self.pbar.close()
+            else:
+                timestamp = time.strftime("%H:%M:%S")
+                print(
+                    f"[{timestamp}] All stages complete ({total_duration:.1f}s total)",
+                    file=sys.stderr,
+                )
+
+    def __enter__(self) -> ProgressReporter:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.finish()

oscura/cli/shell.py

@@ -45,153 +45,177 @@ def get_oscura_namespace() -> dict[str, Any]:
     """
     namespace: dict[str, Any] = {}
 
-    # Core imports
+    _import_core_oscura(namespace)
+    _import_protocols(namespace)
+    _import_discovery(namespace)
+    _import_common_utilities(namespace)
+
+    return namespace
+
+
+def _import_core_oscura(namespace: dict[str, Any]) -> None:
+    """Import core Oscura functions and types."""
     try:
         import oscura as osc
 
         namespace["osc"] = osc
+        imports = _get_oscura_imports()
+        namespace.update(_build_namespace_dict(imports))
+    except ImportError as e:
+        print(f"Warning: Could not import Oscura: {e}")
+
+
+def _get_oscura_imports() -> dict[str, Any]:
+    """Get all Oscura imports as dictionary.
 
-        # Auto-import commonly used functions at top level
-        from oscura import (
-            DigitalTrace,
-            ProtocolPacket,
-            TraceMetadata,
-            # Core types
-            WaveformTrace,
-            # Math
-            add,
-            amplitude,
-            band_pass,
-            band_stop,
-            # Statistics
-            basic_stats,
-            detect_edges,
-            differentiate,
-            divide,
-            duty_cycle,
-            enob,
-            fall_time,
-            # Spectral
-            fft,
-            frequency,
-            get_supported_formats,
-            high_pass,
-            histogram,
-            integrate,
-            # Loaders
-            load,
-            # Filtering
-            low_pass,
-            mean,
-            measure,
-            multiply,
-            overshoot,
-            percentiles,
-            period,
-            psd,
-            pulse_width,
-            # Measurements
-            rise_time,
-            rms,
-            sfdr,
-            sinad,
-            snr,
-            spectrogram,
-            subtract,
-            thd,
-            # Digital
-            to_digital,
-            undershoot,
+    Returns:
+        Dictionary of imported symbols.
+    """
+    from oscura import (
+        DigitalTrace,
+        ProtocolPacket,
+        TraceMetadata,
+        WaveformTrace,
+        add,
+        amplitude,
+        band_pass,
+        band_stop,
+        basic_stats,
+        detect_edges,
+        differentiate,
+        divide,
+        duty_cycle,
+        enob,
+        fall_time,
+        fft,
+        frequency,
+        get_supported_formats,
+        high_pass,
+        histogram,
+        integrate,
+        load,
+        low_pass,
+        mean,
+        measure,
+        multiply,
+        overshoot,
+        percentiles,
+        period,
+        psd,
+        pulse_width,
+        rise_time,
+        rms,
+        sfdr,
+        sinad,
+        snr,
+        spectrogram,
+        subtract,
+        thd,
+        to_digital,
+        undershoot,
+    )
+
+    return {
+        "WaveformTrace": WaveformTrace,
+        "DigitalTrace": DigitalTrace,
+        "TraceMetadata": TraceMetadata,
+        "ProtocolPacket": ProtocolPacket,
+        "load": load,
+        "get_supported_formats": get_supported_formats,
+        "rise_time": rise_time,
+        "fall_time": fall_time,
+        "frequency": frequency,
+        "period": period,
+        "amplitude": amplitude,
+        "rms": rms,
+        "mean": mean,
+        "overshoot": overshoot,
+        "undershoot": undershoot,
+        "duty_cycle": duty_cycle,
+        "pulse_width": pulse_width,
+        "measure": measure,
+        "fft": fft,
+        "psd": psd,
+        "thd": thd,
+        "snr": snr,
+        "sinad": sinad,
+        "enob": enob,
+        "sfdr": sfdr,
+        "spectrogram": spectrogram,
+        "to_digital": to_digital,
+        "detect_edges": detect_edges,
+        "low_pass": low_pass,
+        "high_pass": high_pass,
+        "band_pass": band_pass,
+        "band_stop": band_stop,
+        "add": add,
+        "subtract": subtract,
+        "multiply": multiply,
+        "divide": divide,
+        "differentiate": differentiate,
+        "integrate": integrate,
+        "basic_stats": basic_stats,
+        "histogram": histogram,
+        "percentiles": percentiles,
+    }
+
+
+def _build_namespace_dict(imports: dict[str, Any]) -> dict[str, Any]:
+    """Build namespace dictionary from imports.
+
+    Args:
+        imports: Dictionary of imported symbols.
+
+    Returns:
+        Namespace dictionary.
+    """
+    return imports
+
+
+def _import_protocols(namespace: dict[str, Any]) -> None:
+    """Import protocol decoders."""
+    try:
+        from oscura.analyzers.protocols import (
+            decode_can,
+            decode_i2c,
+            decode_spi,
+            decode_uart,
         )
 
         namespace.update(
             {
-                "WaveformTrace": WaveformTrace,
-                "DigitalTrace": DigitalTrace,
-                "TraceMetadata": TraceMetadata,
-                "ProtocolPacket": ProtocolPacket,
-                "load": load,
-                "get_supported_formats": get_supported_formats,
-                "rise_time": rise_time,
-                "fall_time": fall_time,
-                "frequency": frequency,
-                "period": period,
-                "amplitude": amplitude,
-                "rms": rms,
-                "mean": mean,
-                "overshoot": overshoot,
-                "undershoot": undershoot,
-                "duty_cycle": duty_cycle,
-                "pulse_width": pulse_width,
-                "measure": measure,
-                "fft": fft,
-                "psd": psd,
-                "thd": thd,
-                "snr": snr,
-                "sinad": sinad,
-                "enob": enob,
-                "sfdr": sfdr,
-                "spectrogram": spectrogram,
-                "to_digital": to_digital,
-                "detect_edges": detect_edges,
-                "low_pass": low_pass,
-                "high_pass": high_pass,
-                "band_pass": band_pass,
-                "band_stop": band_stop,
-                "add": add,
-                "subtract": subtract,
-                "multiply": multiply,
-                "divide": divide,
-                "differentiate": differentiate,
-                "integrate": integrate,
-                "basic_stats": basic_stats,
-                "histogram": histogram,
-                "percentiles": percentiles,
+                "decode_uart": decode_uart,
+                "decode_spi": decode_spi,
+                "decode_i2c": decode_i2c,
+                "decode_can": decode_can,
             }
         )
+    except ImportError:
+        pass
 
-        # Protocol decoders
-        try:
-            from oscura.analyzers.protocols import (
-                decode_can,
-                decode_i2c,
-                decode_spi,
-                decode_uart,
-            )
-
-            namespace.update(
-                {
-                    "decode_uart": decode_uart,
-                    "decode_spi": decode_spi,
-                    "decode_i2c": decode_i2c,
-                    "decode_can": decode_can,
-                }
-            )
-        except ImportError:
-            pass
-
-        # Discovery
-        try:
-            from oscura.discovery import (
-                characterize_signal,
-                decode_protocol,
-                find_anomalies,
-            )
-
-            namespace.update(
-                {
-                    "characterize_signal": characterize_signal,
-                    "find_anomalies": find_anomalies,
-                    "decode_protocol": decode_protocol,
-                }
-            )
-        except ImportError:
-            pass
 
-    except ImportError as e:
-        print(f"Warning: Could not import Oscura: {e}")
+def _import_discovery(namespace: dict[str, Any]) -> None:
+    """Import discovery functions."""
+    try:
+        from oscura.discovery import (
+            characterize_signal,
+            decode_protocol,
+            find_anomalies,
+        )
+
+        namespace.update(
+            {
+                "characterize_signal": characterize_signal,
+                "find_anomalies": find_anomalies,
+                "decode_protocol": decode_protocol,
+            }
+        )
+    except ImportError:
+        pass
+
 
-    # Common utilities
+def _import_common_utilities(namespace: dict[str, Any]) -> None:
+    """Import common utilities like numpy and matplotlib."""
     try:
         import matplotlib.pyplot as plt
 
@@ -206,8 +230,6 @@ def get_oscura_namespace() -> dict[str, Any]:
     except ImportError:
         pass
 
-    return namespace
-
 
 def setup_history() -> None:
     """Set up readline history with persistence."""