oscura 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

oscura/jupyter/magic.py

@@ -1,4 +1,4 @@
-"""IPython magic commands for TraceKit.
+"""IPython magic commands for Oscura.
 
 This module provides IPython/Jupyter magic commands for convenient
 trace analysis in notebooks.
@@ -82,8 +82,8 @@ except ImportError:
 
 
 @magics_class
-class TracekitMagics(Magics):  # type: ignore[misc]
-    """IPython magics for TraceKit analysis.
+class OscuraMagics(Magics):  # type: ignore[misc]
+    """IPython magics for Oscura analysis.
 
     Provides convenient shortcuts for loading traces, running measurements,
     and displaying results in Jupyter notebooks.
@@ -91,7 +91,7 @@ class TracekitMagics(Magics):  # type: ignore[misc]
 
     @line_magic  # type: ignore[misc, untyped-decorator]
     def oscura(self, line: str) -> Any:
-        """TraceKit line magic for quick operations.
+        """Oscura line magic for quick operations.
 
         Usage:
             %oscura load <filename>    - Load a trace file
@@ -106,7 +106,7 @@ class TracekitMagics(Magics):  # type: ignore[misc]
         Returns:
             Command result or None
         """
-        import oscura as tk
+        import oscura as osc
 
         parts = line.strip().split()
         if not parts:
@@ -129,7 +129,7 @@ class TracekitMagics(Magics):  # type: ignore[misc]
             return self._show_trace_info()
 
         elif cmd == "formats":
-            formats = tk.get_supported_formats()
+            formats = osc.get_supported_formats()
             print("Supported formats:")
             for fmt in formats:
                 print(f"  - {fmt}")
@@ -144,10 +144,10 @@ class TracekitMagics(Magics):  # type: ignore[misc]
 
     def _load_trace(self, filename: str) -> Any:
         """Load a trace file and store as current."""
-        import oscura as tk
+        import oscura as osc
 
         try:
-            trace = tk.load(filename)
+            trace = osc.load(filename)
             set_current_trace(trace, filename)
 
             # Display summary
@@ -169,7 +169,7 @@ class TracekitMagics(Magics):  # type: ignore[misc]
 
     def _run_measurements(self, measurement_names: list[str] | None) -> dict[str, Any]:
         """Run measurements on current trace."""
-        import oscura as tk
+        import oscura as osc
 
         trace = get_current_trace()
         if trace is None:
@@ -180,9 +180,9 @@ class TracekitMagics(Magics):  # type: ignore[misc]
             # Run specific measurements
             results = {}
             for name in measurement_names:
-                if hasattr(tk, name):
+                if hasattr(osc, name):
                     try:
-                        func = getattr(tk, name)
+                        func = getattr(osc, name)
                         results[name] = func(trace)
                     except Exception as e:
                         results[name] = f"Error: {e}"
@@ -191,7 +191,7 @@ class TracekitMagics(Magics):  # type: ignore[misc]
         else:
             # Run all measurements
             try:
-                results = tk.measure(trace)
+                results = osc.measure(trace)
             except Exception as e:
                 print(f"Error running measurements: {e}")
                 return {}
@@ -243,7 +243,7 @@ class TracekitMagics(Magics):  # type: ignore[misc]
     def _show_help(self) -> None:
         """Show magic command help."""
         help_text = """
-TraceKit Magic Commands
+Oscura Magic Commands
 =======================
 
 %oscura load <filename>    Load a trace file
@@ -282,23 +282,23 @@ Example:
 
         All oscura functions are auto-imported in the cell namespace.
         """
-        import oscura as tk
+        import oscura as osc
 
         # Build execution namespace with oscura imports
         namespace = {
-            "tk": tk,
-            "load": tk.load,
-            "measure": tk.measure,
-            "fft": tk.fft,
-            "psd": tk.psd,
-            "thd": tk.thd,
-            "snr": tk.snr,
-            "rise_time": tk.rise_time,
-            "fall_time": tk.fall_time,
-            "frequency": tk.frequency,
-            "amplitude": tk.amplitude,
-            "low_pass": tk.low_pass,
-            "high_pass": tk.high_pass,
+            "osc": osc,
+            "load": osc.load,
+            "measure": osc.measure,
+            "fft": osc.fft,
+            "psd": osc.psd,
+            "thd": osc.thd,
+            "snr": osc.snr,
+            "rise_time": osc.rise_time,
+            "fall_time": osc.fall_time,
+            "frequency": osc.frequency,
+            "amplitude": osc.amplitude,
+            "low_pass": osc.low_pass,
+            "high_pass": osc.high_pass,
         }
 
         # Add current trace if available
@@ -314,19 +314,19 @@ Example:
 
 
 def load_ipython_extension(ipython: InteractiveShell) -> None:
-    """Load TraceKit IPython extension.
+    """Load Oscura IPython extension.
 
     Called when user runs: %load_ext oscura
 
     Args:
         ipython: The IPython shell instance
     """
-    ipython.register_magics(TracekitMagics)
-    print("TraceKit magics loaded. Type '%oscura help' for usage.")
+    ipython.register_magics(OscuraMagics)
+    print("Oscura magics loaded. Type '%oscura help' for usage.")
 
 
 def unload_ipython_extension(ipython: InteractiveShell) -> None:
-    """Unload TraceKit IPython extension.
+    """Unload Oscura IPython extension.
 
     Args:
         ipython: The IPython shell instance

oscura/loaders/__init__.py

@@ -1,16 +1,16 @@
-"""TraceKit data loaders for various file formats.
+"""Oscura data loaders for various file formats.
 
 This module provides a unified load() function that auto-detects file formats
 and delegates to the appropriate loader.
 
 
 Example:
-    >>> import oscura as tk
-    >>> trace = tk.load("capture.wfm")
+    >>> import oscura as osc
+    >>> trace = osc.load("capture.wfm")
     >>> print(f"Loaded {len(trace.data)} samples")
 
     >>> # Load all channels from multi-channel file
-    >>> channels = tk.load_all_channels("multi_channel.wfm")
+    >>> channels = osc.load_all_channels("multi_channel.wfm")
     >>> for name, trace in channels.items():
     ...     print(f"{name}: {len(trace.data)} samples")
 """
@@ -135,12 +135,12 @@ def load(
         FileNotFoundError: If the file does not exist.
 
     Example:
-        >>> import oscura as tk
-        >>> trace = tk.load("oscilloscope_capture.wfm")
+        >>> import oscura as osc
+        >>> trace = osc.load("oscilloscope_capture.wfm")
         >>> print(f"Loaded {len(trace.data)} samples at {trace.metadata.sample_rate} Hz")
 
         >>> # Force specific loader
-        >>> trace = tk.load("data.bin", format="tektronix")
+        >>> trace = osc.load("data.bin", format="tektronix")
 
         >>> # Check if digital trace
         >>> if isinstance(trace, DigitalTrace):
@@ -306,8 +306,8 @@ def load_all_channels(
         FileNotFoundError: If the file does not exist.
 
     Example:
-        >>> import oscura as tk
-        >>> channels = tk.load_all_channels("multi_channel.wfm")
+        >>> import oscura as osc
+        >>> channels = osc.load_all_channels("multi_channel.wfm")
         >>> for name, trace in channels.items():
         ...     print(f"{name}: {len(trace.data)} samples")
         ch1: 10000 samples
@@ -472,7 +472,7 @@ def load_lazy(path: str | PathLike[str], **kwargs: Any) -> LazyWaveformTrace | W
         LazyWaveformTrace or WaveformTrace.
 
     Example:
-        >>> trace = tk.loaders.load_lazy("huge_trace.npy", sample_rate=1e9)
+        >>> trace = osc.loaders.load_lazy("huge_trace.npy", sample_rate=1e9)
         >>> print(f"Length: {trace.length}")  # Metadata available immediately
 
     References:

oscura/loaders/mmap_loader.py

@@ -7,7 +7,7 @@ file into memory but access it in chunks on-demand via the OS page cache.
 Key features:
 - Zero-copy data access via numpy.memmap
 - Chunked iteration for processing huge files
-- Integration with existing TraceKit loader infrastructure
+- Integration with existing Oscura loader infrastructure
 - Support for common binary formats (raw, NPY, structured)
 - Automatic fallback to regular loading for small files
 

oscura/loaders/pcap.py

@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
 # Try to import dpkt for full PCAP support
 try:
-    import dpkt  # type: ignore[import-not-found]
+    import dpkt  # type: ignore[import-untyped]
 
     DPKT_AVAILABLE = True
 except ImportError:

oscura/math/__init__.py

@@ -1,4 +1,4 @@
-"""Math and arithmetic operations module for TraceKit.
+"""Math and arithmetic operations module for Oscura.
 
 This module provides waveform math operations including arithmetic,
 interpolation, and mathematical transformations.

oscura/math/arithmetic.py

@@ -1,4 +1,4 @@
-"""Signal arithmetic operations for TraceKit.
+"""Signal arithmetic operations for Oscura.
 
 This module provides element-wise arithmetic operations for waveform traces
 including addition, subtraction, multiplication, division, differentiation,

oscura/math/interpolation.py

@@ -1,4 +1,4 @@
-"""Interpolation and resampling operations for TraceKit.
+"""Interpolation and resampling operations for Oscura.
 
 This module provides interpolation, resampling, and trace alignment
 functions for waveform data.

oscura/onboarding/__init__.py

@@ -1,4 +1,4 @@
-"""Onboarding and help system for TraceKit.
+"""Onboarding and help system for Oscura.
 
 This package provides interactive tutorials, context-sensitive help,
 and guided analysis features for new users.

oscura/onboarding/help.py

@@ -67,7 +67,7 @@ Common scales:
 - 1 MHz = 1,000,000 cycles/second (radio, slow digital)
 - 1 GHz = 1,000,000,000 cycles/second (fast digital, RF)
 
-TraceKit finds frequency by detecting repeated patterns in your signal.
+Oscura finds frequency by detecting repeated patterns in your signal.
 """,
         "when_to_use": [
             "Verifying clock frequency",
@@ -143,7 +143,7 @@ harmonics (1x, 3x, 5x, etc. of the fundamental).
         "related": ["psd", "thd", "snr", "spectrogram"],
     },
     "load": {
-        "summary": "Load a trace file - TraceKit's starting point",
+        "summary": "Load a trace file - Oscura's starting point",
         "plain_english": """
 load() reads waveform data from a file. It auto-detects the format,
 so you don't need to specify whether it's CSV, WFM, HDF5, etc.
@@ -157,7 +157,7 @@ Supported formats: CSV, Tektronix WFM, Rigol WFM, NumPy NPZ,
 HDF5, Sigrok sessions, VCD, TDMS, and more.
 """,
         "when_to_use": [
-            "Starting any TraceKit analysis",
+            "Starting any Oscura analysis",
             "Loading oscilloscope captures",
             "Importing logic analyzer data",
         ],
@@ -189,7 +189,7 @@ Results are returned in a dictionary for easy access.
 
 
 def get_help(topic: str) -> str | None:
-    """Get plain English help for a TraceKit function or concept.
+    """Get plain English help for a Oscura function or concept.
 
     Args:
         topic: Function name or concept to get help for
@@ -222,10 +222,10 @@ def get_help(topic: str) -> str | None:
 
     # Try to get docstring
     try:
-        import oscura as tk
+        import oscura as osc
 
-        if hasattr(tk, topic):
-            func = getattr(tk, topic)
+        if hasattr(osc, topic):
+            func = getattr(osc, topic)
             if func.__doc__:
                 return f"Help for {topic}:\n\n{func.__doc__}"
     except Exception:
@@ -467,29 +467,29 @@ def get_example(function_name: str) -> str | None:
     examples = {
         "load": """
 # Load a trace file
-import oscura as tk
-trace = tk.load("capture.csv")
+import oscura as osc
+trace = osc.load("capture.csv")
 print(f"Loaded {len(trace.data)} samples")
 """,
         "rise_time": """
 # Measure rise time
-import oscura as tk
-trace = tk.load("signal.csv")
-rt = tk.rise_time(trace)
+import oscura as osc
+trace = osc.load("signal.csv")
+rt = osc.rise_time(trace)
 print(f"Rise time: {rt*1e9:.2f} ns")
 """,
         "fft": """
 # Compute FFT spectrum
-import oscura as tk
-trace = tk.load("signal.csv")
-freq, mag = tk.fft(trace)
+import oscura as osc
+trace = osc.load("signal.csv")
+freq, mag = osc.fft(trace)
 print(f"Frequency resolution: {freq[1]:.2f} Hz")
 """,
         "measure": """
 # Run all measurements
-import oscura as tk
-trace = tk.load("signal.csv")
-results = tk.measure(trace)
+import oscura as osc
+trace = osc.load("signal.csv")
+results = osc.measure(trace)
 for name, value in results.items():
     print(f"{name}: {value}")
 """,

oscura/onboarding/tutorials.py

@@ -1,4 +1,4 @@
-"""Interactive tutorial system for TraceKit.
+"""Interactive tutorial system for Oscura.
 
 This module provides step-by-step interactive tutorials for new users,
 covering common analysis workflows.
@@ -11,7 +11,7 @@ covering common analysis workflows.
 Example:
     >>> from oscura.onboarding import run_tutorial
     >>> run_tutorial("getting_started")
-    Welcome to TraceKit!
+    Welcome to Oscura!
     Step 1/5: Loading a trace file
     ...
 """
@@ -74,17 +74,17 @@ def _register_getting_started() -> None:
         TutorialStep(
             title="Loading a Trace File",
             description="""
-TraceKit can load waveform data from many file formats.
+Oscura can load waveform data from many file formats.
 The simplest way is to use the load() function, which auto-detects the format.
 
 Think of a trace like a recording of an electrical signal over time -
 similar to how an audio file stores sound waves.
 """,
             code="""
-import oscura as tk
+import oscura as osc
 
 # Load a waveform file (replace with your file path)
-trace = tk.load("signal.csv")
+trace = osc.load("signal.csv")
 
 # See basic info
 print(f"Loaded {len(trace.data)} samples")
@@ -107,20 +107,20 @@ Once you have a trace, you can measure things like:
 These are the same measurements an oscilloscope would show you!
 """,
             code="""
-import oscura as tk
+import oscura as osc
 
-trace = tk.load("signal.csv")
+trace = osc.load("signal.csv")
 
 # Measure rise time (10% to 90% transition)
-rt = tk.rise_time(trace)
+rt = osc.rise_time(trace)
 print(f"Rise time: {rt*1e9:.2f} nanoseconds")
 
 # Measure frequency
-freq = tk.frequency(trace)
+freq = osc.frequency(trace)
 print(f"Frequency: {freq/1e6:.2f} MHz")
 
 # Get all measurements at once
-results = tk.measure(trace)
+results = osc.measure(trace)
 for name, value in results.items():
     print(f"{name}: {value}")
 """,
@@ -142,12 +142,12 @@ This is useful for:
 It's like looking at a music equalizer that shows bass, mid, and treble!
 """,
             code="""
-import oscura as tk
+import oscura as osc
 
-trace = tk.load("signal.csv")
+trace = osc.load("signal.csv")
 
 # Compute FFT (Fast Fourier Transform)
-freq, magnitude = tk.fft(trace)
+freq, magnitude = osc.fft(trace)
 
 # Find the dominant frequency
 import numpy as np
@@ -155,8 +155,8 @@ peak_idx = np.argmax(magnitude)
 print(f"Dominant frequency: {freq[peak_idx]/1e6:.2f} MHz")
 
 # Measure signal quality
-thd_value = tk.thd(trace)
-snr_value = tk.snr(trace)
+thd_value = osc.thd(trace)
+snr_value = osc.snr(trace)
 print(f"THD: {thd_value:.1f} dB")
 print(f"SNR: {snr_value:.1f} dB")
 """,
@@ -170,15 +170,15 @@ print(f"SNR: {snr_value:.1f} dB")
             title="Protocol Decoding",
             description="""
 If your signal is a digital communication protocol like UART, SPI, or I2C,
-TraceKit can decode it to show you the actual data being transmitted.
+Oscura can decode it to show you the actual data being transmitted.
 
 Think of it like translating Morse code back into text!
 """,
             code="""
-import oscura as tk
+import oscura as osc
 
 # Load a UART signal
-trace = tk.load("uart_signal.csv")
+trace = osc.load("uart_signal.csv")
 
 # Decode UART (auto-detects baud rate!)
 from oscura.analyzers.protocols import decode_uart
@@ -197,7 +197,7 @@ for pkt in packets[:5]:  # First 5 packets
         TutorialStep(
             title="Auto-Discovery for Beginners",
             description="""
-Not sure what your signal is? TraceKit can analyze it automatically!
+Not sure what your signal is? Oscura can analyze it automatically!
 
 The characterize_signal() function examines your trace and tells you:
 - What type of signal it likely is
@@ -207,10 +207,10 @@ The characterize_signal() function examines your trace and tells you:
 It's like having an expert look at your signal and give you hints!
 """,
             code="""
-import oscura as tk
+import oscura as osc
 from oscura.discovery import characterize_signal
 
-trace = tk.load("mystery_signal.csv")
+trace = osc.load("mystery_signal.csv")
 
 # Auto-characterize the signal
 result = characterize_signal(trace)
@@ -236,9 +236,9 @@ else:
 
     tutorial = Tutorial(
         id="getting_started",
-        title="Getting Started with TraceKit",
+        title="Getting Started with Oscura",
         description="""
-Welcome to TraceKit! This tutorial will teach you the basics of
+Welcome to Oscura! This tutorial will teach you the basics of
 signal analysis in 5 easy steps:
 
 1. Loading trace files
@@ -266,11 +266,11 @@ The Fast Fourier Transform (FFT) converts a time-domain signal into
 its frequency components. Think of it as breaking a chord into individual notes.
 """,
             code="""
-import oscura as tk
+import oscura as osc
 import numpy as np
 
-trace = tk.load("signal.csv")
-freq, mag = tk.fft(trace)
+trace = osc.load("signal.csv")
+freq, mag = osc.fft(trace)
 
 # Magnitude is in dB (decibels)
 # 0 dB = full scale, -20 dB = 10x smaller, -40 dB = 100x smaller
@@ -287,10 +287,10 @@ PSD is normalized per Hz, making it easier to compare signals with
 different durations or sample rates.
 """,
             code="""
-import oscura as tk
+import oscura as osc
 
-trace = tk.load("signal.csv")
-freq, psd = tk.psd(trace)
+trace = osc.load("signal.csv")
+freq, psd = osc.psd(trace)
 
 # Find where most power is concentrated
 import numpy as np

oscura/onboarding/wizard.py

@@ -99,7 +99,7 @@ class AnalysisWizard:
                 title="Signal Type Detection",
                 question="What type of analysis do you want to perform?",
                 options=[
-                    "Auto-detect (let TraceKit figure it out)",
+                    "Auto-detect (let Oscura figure it out)",
                     "Digital signal analysis",
                     "Analog/waveform analysis",
                     "Protocol decoding",
@@ -157,7 +157,7 @@ class AnalysisWizard:
             WizardResult with all collected data
         """
         print("\n" + "=" * 60)
-        print("TraceKit Analysis Wizard")
+        print("Oscura Analysis Wizard")
         print("=" * 60)
         print("Let's analyze your signal step by step.\n")
 
@@ -287,7 +287,7 @@ class AnalysisWizard:
 
     def _handle_measurements(self, choice: int) -> None:
         """Handle measurement selection."""
-        import oscura as tk
+        import oscura as osc
 
         if choice == 4:  # Skip
             print("\nSkipping measurements.")
@@ -297,22 +297,22 @@ class AnalysisWizard:
 
         try:
             if choice == 1:  # All
-                results = tk.measure(self.trace)
+                results = osc.measure(self.trace)
             elif choice == 2:  # Timing only
                 results = {
-                    "rise_time": tk.rise_time(self.trace),
-                    "fall_time": tk.fall_time(self.trace),
-                    "frequency": tk.frequency(self.trace),
-                    "period": tk.period(self.trace),
-                    "duty_cycle": tk.duty_cycle(self.trace),
+                    "rise_time": osc.rise_time(self.trace),
+                    "fall_time": osc.fall_time(self.trace),
+                    "frequency": osc.frequency(self.trace),
+                    "period": osc.period(self.trace),
+                    "duty_cycle": osc.duty_cycle(self.trace),
                 }
             elif choice == 3:  # Amplitude only
                 results = {
-                    "amplitude": tk.amplitude(self.trace),
-                    "rms": tk.rms(self.trace),
-                    "mean": tk.mean(self.trace),
-                    "overshoot": tk.overshoot(self.trace),
-                    "undershoot": tk.undershoot(self.trace),
+                    "amplitude": osc.amplitude(self.trace),
+                    "rms": osc.rms(self.trace),
+                    "mean": osc.mean(self.trace),
+                    "overshoot": osc.overshoot(self.trace),
+                    "undershoot": osc.undershoot(self.trace),
                 }
 
             self.result.measurements.update(results)
@@ -331,7 +331,7 @@ class AnalysisWizard:
         """Handle spectral analysis selection."""
         import numpy as np
 
-        import oscura as tk
+        import oscura as osc
 
         if choice == 4:  # Skip
             print("\nSkipping spectral analysis.")
@@ -341,14 +341,14 @@ class AnalysisWizard:
 
         try:
             if choice in (1, 3):  # FFT
-                freq, mag = tk.fft(self.trace)  # type: ignore[misc]
+                freq, mag = osc.fft(self.trace)  # type: ignore[misc]
                 peak_idx = np.argmax(mag)
                 self.result.measurements["fft_peak_freq"] = freq[peak_idx]
                 self.result.measurements["fft_peak_mag"] = mag[peak_idx]
                 print(f"  FFT peak: {freq[peak_idx] / 1e6:.3f} MHz at {mag[peak_idx]:.1f} dB")
 
             if choice in (2, 3):  # PSD
-                freq, _psd_vals = tk.psd(self.trace)
+                freq, _psd_vals = osc.psd(self.trace)
                 self.result.measurements["psd_computed"] = True
                 print(f"  PSD computed over {len(freq)} frequency bins")
 
@@ -357,7 +357,7 @@ class AnalysisWizard:
 
     def _handle_quality(self, choice: int) -> None:
         """Handle quality assessment selection."""
-        import oscura as tk
+        import oscura as osc
 
         if choice == 4:  # Skip
             print("\nSkipping quality assessment.")
@@ -367,8 +367,8 @@ class AnalysisWizard:
 
         try:
             if choice in (1, 3):  # THD and SNR
-                thd_val = tk.thd(self.trace)
-                snr_val = tk.snr(self.trace)
+                thd_val = osc.thd(self.trace)
+                snr_val = osc.snr(self.trace)
                 self.result.measurements["thd"] = thd_val
                 self.result.measurements["snr"] = snr_val
                 print(f"  THD: {thd_val:.1f} dB")
@@ -457,9 +457,9 @@ def run_wizard(trace: Any, interactive: bool = True) -> WizardResult:
         WizardResult with measurements, recommendations, and summary
 
     Example:
-        >>> import oscura as tk
+        >>> import oscura as osc
         >>> from oscura.onboarding import run_wizard
-        >>> trace = tk.load("signal.csv")
+        >>> trace = osc.load("signal.csv")
         >>> result = run_wizard(trace)
     """
     wizard = AnalysisWizard(trace)