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

oscura/{filtering → utils/filtering}/design.py

@@ -6,7 +6,7 @@ order calculation from specifications.
 
 
 Example:
-    >>> from oscura.filtering.design import LowPassFilter, design_filter
+    >>> from oscura.utils.filtering.design import LowPassFilter, design_filter
     >>> # Simple filter creation
     >>> lpf = LowPassFilter(cutoff=1e6, sample_rate=10e6, order=4)
     >>> # Spec-based design
@@ -25,12 +25,164 @@ import numpy as np
 from scipy import signal
 
 from oscura.core.exceptions import AnalysisError
-from oscura.filtering.base import IIRFilter
+from oscura.utils.filtering.base import IIRFilter
 
 FilterType = Literal["butterworth", "chebyshev1", "chebyshev2", "bessel", "elliptic"]
 BandType = Literal["lowpass", "highpass", "bandpass", "bandstop"]
 
 
+def _normalize_cutoff(
+    cutoff: float | tuple[float, float],
+    sample_rate: float,
+    analog: bool,
+) -> float | tuple[float, float]:
+    """Normalize cutoff frequency for digital filters.
+
+    Args:
+        cutoff: Cutoff frequency in Hz.
+        sample_rate: Sample rate in Hz.
+        analog: If True, return as-is (analog filter).
+
+    Returns:
+        Normalized cutoff frequency (0-1 for digital, Hz for analog).
+    """
+    if analog:
+        return cutoff
+
+    nyquist = sample_rate / 2
+    if isinstance(cutoff, tuple):
+        return (cutoff[0] / nyquist, cutoff[1] / nyquist)
+    else:
+        return cutoff / nyquist
+
+
+def _validate_normalized_cutoff(
+    Wn: float | tuple[float, float],
+    cutoff: float | tuple[float, float],
+    sample_rate: float,
+    analog: bool,
+) -> None:
+    """Validate normalized cutoff frequency is in valid range.
+
+    Args:
+        Wn: Normalized cutoff frequency.
+        cutoff: Original cutoff in Hz.
+        sample_rate: Sample rate in Hz.
+        analog: If True, skip validation (analog filter).
+
+    Raises:
+        AnalysisError: If cutoff is out of range.
+    """
+    if analog:
+        return
+
+    nyquist = sample_rate / 2
+    if isinstance(Wn, tuple):
+        if not (0 < Wn[0] < 1 and 0 < Wn[1] < 1):
+            raise AnalysisError(
+                f"Normalized cutoff must be in (0, 1), got {Wn}. "
+                f"Cutoff {cutoff} Hz must be less than Nyquist {nyquist} Hz."
+            )
+    elif not 0 < Wn < 1:
+        raise AnalysisError(
+            f"Normalized cutoff must be in (0, 1), got {Wn}. "
+            f"Cutoff {cutoff} Hz must be less than Nyquist {nyquist} Hz."
+        )
+
+
+def _design_butterworth(
+    order: int,
+    Wn: float | tuple[float, float],
+    btype: BandType,
+    analog: bool,
+    output: Literal["sos", "ba"],
+    sample_rate: float,
+) -> IIRFilter:
+    """Design Butterworth filter."""
+    if output == "sos":
+        sos = signal.butter(order, Wn, btype=btype, analog=analog, output="sos")
+        return IIRFilter(sample_rate=sample_rate, sos=sos)
+    else:
+        b, a = signal.butter(order, Wn, btype=btype, analog=analog, output="ba")
+        return IIRFilter(sample_rate=sample_rate, ba=(b, a))
+
+
+def _design_chebyshev1(
+    order: int,
+    ripple_db: float,
+    Wn: float | tuple[float, float],
+    btype: BandType,
+    analog: bool,
+    output: Literal["sos", "ba"],
+    sample_rate: float,
+) -> IIRFilter:
+    """Design Chebyshev Type I filter."""
+    if output == "sos":
+        sos = signal.cheby1(order, ripple_db, Wn, btype=btype, analog=analog, output="sos")
+        return IIRFilter(sample_rate=sample_rate, sos=sos)
+    else:
+        b, a = signal.cheby1(order, ripple_db, Wn, btype=btype, analog=analog, output="ba")
+        return IIRFilter(sample_rate=sample_rate, ba=(b, a))
+
+
+def _design_chebyshev2(
+    order: int,
+    stopband_atten_db: float,
+    Wn: float | tuple[float, float],
+    btype: BandType,
+    analog: bool,
+    output: Literal["sos", "ba"],
+    sample_rate: float,
+) -> IIRFilter:
+    """Design Chebyshev Type II filter."""
+    if output == "sos":
+        sos = signal.cheby2(order, stopband_atten_db, Wn, btype=btype, analog=analog, output="sos")
+        return IIRFilter(sample_rate=sample_rate, sos=sos)
+    else:
+        b, a = signal.cheby2(order, stopband_atten_db, Wn, btype=btype, analog=analog, output="ba")
+        return IIRFilter(sample_rate=sample_rate, ba=(b, a))
+
+
+def _design_bessel(
+    order: int,
+    Wn: float | tuple[float, float],
+    btype: BandType,
+    analog: bool,
+    output: Literal["sos", "ba"],
+    sample_rate: float,
+) -> IIRFilter:
+    """Design Bessel filter."""
+    if output == "sos":
+        sos = signal.bessel(order, Wn, btype=btype, analog=analog, output="sos", norm="phase")
+        return IIRFilter(sample_rate=sample_rate, sos=sos)
+    else:
+        b, a = signal.bessel(order, Wn, btype=btype, analog=analog, output="ba", norm="phase")
+        return IIRFilter(sample_rate=sample_rate, ba=(b, a))
+
+
+def _design_elliptic(
+    order: int,
+    ripple_db: float,
+    stopband_atten_db: float,
+    Wn: float | tuple[float, float],
+    btype: BandType,
+    analog: bool,
+    output: Literal["sos", "ba"],
+    sample_rate: float,
+) -> IIRFilter:
+    """Design Elliptic filter."""
+    if output == "sos":
+        sos = signal.ellip(
+            order, ripple_db, stopband_atten_db, Wn, btype=btype, analog=analog, output="sos"
+        )
+        return IIRFilter(sample_rate=sample_rate, sos=sos)
+    else:
+        b, a = signal.ellip(
+            order, ripple_db, stopband_atten_db, Wn, btype=btype, analog=analog, output="ba"
+        )
+        return IIRFilter(sample_rate=sample_rate, ba=(b, a))
+
+
 def design_filter(
     filter_type: FilterType,
     cutoff: float | tuple[float, float],
@@ -71,27 +223,11 @@ def design_filter(
     References:
         scipy.signal.iirfilter, butter, cheby1, cheby2, ellip, bessel
     """
-    # Normalize cutoff frequency
-    if isinstance(cutoff, tuple):
-        Wn = cutoff if analog else (cutoff[0] / (sample_rate / 2), cutoff[1] / (sample_rate / 2))
-    else:
-        Wn = cutoff if analog else cutoff / (sample_rate / 2)  # type: ignore[assignment]
-
-    # Validate normalized frequency
-    if not analog:
-        if isinstance(Wn, tuple):
-            if not (0 < Wn[0] < 1 and 0 < Wn[1] < 1):
-                raise AnalysisError(
-                    f"Normalized cutoff must be in (0, 1), got {Wn}. "
-                    f"Cutoff {cutoff} Hz must be less than Nyquist {sample_rate / 2} Hz."
-                )
-        elif not 0 < Wn < 1:  # type: ignore[unreachable]
-            raise AnalysisError(
-                f"Normalized cutoff must be in (0, 1), got {Wn}. "
-                f"Cutoff {cutoff} Hz must be less than Nyquist {sample_rate / 2} Hz."
-            )
+    # Normalize and validate cutoff
+    Wn = _normalize_cutoff(cutoff, sample_rate, analog)
+    _validate_normalized_cutoff(Wn, cutoff, sample_rate, analog)
 
-    # Design filter
+    # Validate filter type
     ftype_map = {
         "butterworth": "butter",
         "chebyshev1": "cheby1",
@@ -99,85 +235,25 @@ def design_filter(
         "bessel": "bessel",
         "elliptic": "ellip",
     }
-    ftype = ftype_map.get(filter_type)
-    if ftype is None:
+    if filter_type not in ftype_map:
         raise AnalysisError(f"Unknown filter type: {filter_type}")
 
+    # Design filter
     try:
         if filter_type == "butterworth":
-            if output == "sos":
-                sos = signal.butter(order, Wn, btype=btype, analog=analog, output="sos")
-                return IIRFilter(sample_rate=sample_rate, sos=sos)
-            else:
-                b, a = signal.butter(order, Wn, btype=btype, analog=analog, output="ba")
-                return IIRFilter(sample_rate=sample_rate, ba=(b, a))
-
+            return _design_butterworth(order, Wn, btype, analog, output, sample_rate)
         elif filter_type == "chebyshev1":
-            if output == "sos":
-                sos = signal.cheby1(order, ripple_db, Wn, btype=btype, analog=analog, output="sos")
-                return IIRFilter(sample_rate=sample_rate, sos=sos)
-            else:
-                b, a = signal.cheby1(order, ripple_db, Wn, btype=btype, analog=analog, output="ba")
-                return IIRFilter(sample_rate=sample_rate, ba=(b, a))
-
+            return _design_chebyshev1(order, ripple_db, Wn, btype, analog, output, sample_rate)
         elif filter_type == "chebyshev2":
-            if output == "sos":
-                sos = signal.cheby2(
-                    order,
-                    stopband_atten_db,
-                    Wn,
-                    btype=btype,
-                    analog=analog,
-                    output="sos",
-                )
-                return IIRFilter(sample_rate=sample_rate, sos=sos)
-            else:
-                b, a = signal.cheby2(
-                    order,
-                    stopband_atten_db,
-                    Wn,
-                    btype=btype,
-                    analog=analog,
-                    output="ba",
-                )
-                return IIRFilter(sample_rate=sample_rate, ba=(b, a))
-
+            return _design_chebyshev2(
+                order, stopband_atten_db, Wn, btype, analog, output, sample_rate
+            )
         elif filter_type == "bessel":
-            if output == "sos":
-                sos = signal.bessel(
-                    order, Wn, btype=btype, analog=analog, output="sos", norm="phase"
-                )
-                return IIRFilter(sample_rate=sample_rate, sos=sos)
-            else:
-                b, a = signal.bessel(
-                    order, Wn, btype=btype, analog=analog, output="ba", norm="phase"
-                )
-                return IIRFilter(sample_rate=sample_rate, ba=(b, a))
-
+            return _design_bessel(order, Wn, btype, analog, output, sample_rate)
         elif filter_type == "elliptic":
-            if output == "sos":
-                sos = signal.ellip(
-                    order,
-                    ripple_db,
-                    stopband_atten_db,
-                    Wn,
-                    btype=btype,
-                    analog=analog,
-                    output="sos",
-                )
-                return IIRFilter(sample_rate=sample_rate, sos=sos)
-            else:
-                b, a = signal.ellip(
-                    order,
-                    ripple_db,
-                    stopband_atten_db,
-                    Wn,
-                    btype=btype,
-                    analog=analog,
-                    output="ba",
-                )
-                return IIRFilter(sample_rate=sample_rate, ba=(b, a))
-
+            return _design_elliptic(
+                order, ripple_db, stopband_atten_db, Wn, btype, analog, output, sample_rate
+            )
         else:
             raise AnalysisError(f"Unsupported filter type: {filter_type}")
 

oscura/{filtering → utils/filtering}/filters.py

@@ -1,13 +1,13 @@
 """Filter convenience functions namespace.
 
 This module provides a namespace for filter functions to support:
-    from oscura.filtering import filters
+    from oscura.utils.filtering import filters
     filters.low_pass(trace, cutoff=1000)
 
 Re-exports convenience functions from the filtering package.
 """
 
-from oscura.filtering.convenience import (
+from oscura.utils.filtering.convenience import (
     band_pass,
     band_stop,
     high_pass,

oscura/{filtering → utils/filtering}/introspection.py

@@ -5,7 +5,7 @@ step response, and pole-zero diagrams.
 
 
 Example:
-    >>> from oscura.filtering import LowPassFilter, plot_bode
+    >>> from oscura.utils.filtering import LowPassFilter, plot_bode
     >>> filt = LowPassFilter(cutoff=1e6, sample_rate=10e6, order=4)
     >>> fig = plot_bode(filt)
     >>> plt.show()
@@ -21,7 +21,7 @@ if TYPE_CHECKING:
     from matplotlib.figure import Figure
     from numpy.typing import NDArray
 
-from oscura.filtering.base import Filter, IIRFilter
+from oscura.utils.filtering.base import Filter, IIRFilter
 
 
 class FilterIntrospection:

oscura/utils/geometry.py

@@ -0,0 +1,31 @@
+"""Geometric utility functions for visualization.
+
+This module provides geometric calculation utilities used across visualization modules.
+"""
+
+
+def generate_leader_line(
+    anchor: tuple[float, float],
+    label: tuple[float, float],
+) -> list[tuple[float, float]]:
+    """Generate orthogonal leader line from anchor to label.
+
+    Creates an L-shaped leader line connecting an anchor point to a label position.
+    The line is orthogonal (horizontal then vertical or vice versa).
+
+    Args:
+        anchor: Anchor point (x, y)
+        label: Label position (x, y)
+
+    Returns:
+        List of points for leader line [(x1, y1), (x2, y2), ...]
+
+    Example:
+        >>> generate_leader_line((0, 0), (10, 5))
+        [(0, 0), (10, 0), (10, 5)]
+    """
+    ax, ay = anchor
+    lx, ly = label
+
+    # Create L-shaped line: horizontal then vertical
+    return [(ax, ay), (lx, ay), (lx, ly)]

oscura/utils/imports.py

@@ -0,0 +1,184 @@
+"""Lazy import utilities for optional dependencies.
+
+This module provides utilities for handling optional dependencies gracefully,
+with helpful error messages directing users to install missing extras.
+"""
+
+from typing import Any
+
+
+class MissingOptionalDependency(ImportError):
+    """Raised when an optional dependency is required but not installed."""
+
+
+def require_matplotlib() -> Any:
+    """Import and return matplotlib, or raise helpful error if not installed.
+
+    Returns:
+        matplotlib module
+
+    Raises:
+        MissingOptionalDependency: If matplotlib is not installed
+
+    Example:
+        >>> plt = require_matplotlib().pyplot
+        >>> plt.plot([1, 2, 3])
+    """
+    try:
+        import matplotlib
+
+        return matplotlib
+    except ImportError as e:
+        raise MissingOptionalDependency(
+            "Visualization features require matplotlib.\n\n"
+            "Install with:\n"
+            "  pip install oscura[visualization]    # Just matplotlib\n"
+            "  pip install oscura[standard]         # Recommended for most users\n"
+            "  pip install oscura[all]              # Everything\n\n"
+            "Or install matplotlib directly:\n"
+            "  pip install matplotlib\n"
+        ) from e
+
+
+def require_pandas() -> Any:
+    """Import and return pandas, or raise helpful error if not installed.
+
+    Returns:
+        pandas module
+
+    Raises:
+        MissingOptionalDependency: If pandas is not installed
+
+    Example:
+        >>> pd = require_pandas()
+        >>> df = pd.DataFrame({'a': [1, 2, 3]})
+    """
+    try:
+        import pandas
+
+        return pandas
+    except ImportError as e:
+        raise MissingOptionalDependency(
+            "DataFrame features require pandas.\n\n"
+            "Install with:\n"
+            "  pip install oscura[dataframes]       # Pandas + Excel export\n"
+            "  pip install oscura[standard]         # Recommended for most users\n"
+            "  pip install oscura[all]              # Everything\n\n"
+            "Or install pandas directly:\n"
+            "  pip install pandas\n"
+        ) from e
+
+
+def require_psutil() -> Any:
+    """Import and return psutil, or raise helpful error if not installed.
+
+    Returns:
+        psutil module
+
+    Raises:
+        MissingOptionalDependency: If psutil is not installed
+
+    Example:
+        >>> psutil = require_psutil()
+        >>> psutil.virtual_memory()
+    """
+    try:
+        import psutil
+
+        return psutil
+    except ImportError as e:
+        raise MissingOptionalDependency(
+            "System monitoring features require psutil.\n\n"
+            "Install with:\n"
+            "  pip install oscura[system]           # System utilities\n"
+            "  pip install oscura[standard]         # Recommended for most users\n"
+            "  pip install oscura[all]              # Everything\n\n"
+            "Or install psutil directly:\n"
+            "  pip install psutil\n"
+        ) from e
+
+
+def require_jinja2() -> Any:
+    """Import and return jinja2, or raise helpful error if not installed.
+
+    Returns:
+        jinja2 module
+
+    Raises:
+        MissingOptionalDependency: If jinja2 is not installed
+
+    Example:
+        >>> jinja2 = require_jinja2()
+        >>> template = jinja2.Template("Hello {{ name }}")
+    """
+    try:
+        import jinja2
+
+        return jinja2
+    except ImportError as e:
+        raise MissingOptionalDependency(
+            "Report generation features require jinja2.\n\n"
+            "Install with:\n"
+            "  pip install oscura[reporting]        # Report generation\n"
+            "  pip install oscura[standard]         # Recommended for most users\n"
+            "  pip install oscura[all]              # Everything\n\n"
+            "Or install jinja2 directly:\n"
+            "  pip install jinja2\n"
+        ) from e
+
+
+# Convenience functions for checking availability without raising errors
+def has_matplotlib() -> bool:
+    """Check if matplotlib is available.
+
+    Returns:
+        True if matplotlib can be imported, False otherwise
+    """
+    try:
+        import matplotlib  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def has_pandas() -> bool:
+    """Check if pandas is available.
+
+    Returns:
+        True if pandas can be imported, False otherwise
+    """
+    try:
+        import pandas  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def has_psutil() -> bool:
+    """Check if psutil is available.
+
+    Returns:
+        True if psutil can be imported, False otherwise
+    """
+    try:
+        import psutil  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def has_jinja2() -> bool:
+    """Check if jinja2 is available.
+
+    Returns:
+        True if jinja2 can be imported, False otherwise
+    """
+    try:
+        import jinja2  # noqa: F401
+
+        return True
+    except ImportError:
+        return False

oscura/utils/lazy.py

@@ -120,7 +120,7 @@ class LazyArray(LazyProxy[NDArray[np.floating[Any]]]):
 
     def shape(self) -> tuple[int, ...]:
         """Get shape (triggers computation)."""
-        return self.compute().shape  # type: ignore[no-any-return]
+        return self.compute().shape
 
     def dtype(self) -> np.dtype[Any]:
         """Get dtype (triggers computation)."""

oscura/{math → utils/math}/__init__.py

@@ -4,7 +4,7 @@ This module provides waveform math operations including arithmetic,
 interpolation, and mathematical transformations.
 """
 
-from oscura.math.arithmetic import (
+from oscura.utils.math.arithmetic import (
     absolute,
     add,
     differentiate,
@@ -17,7 +17,7 @@ from oscura.math.arithmetic import (
     scale,
     subtract,
 )
-from oscura.math.interpolation import (
+from oscura.utils.math.interpolation import (
     align_traces,
     downsample,
     interpolate,