refactor: enforce strict typing and numpy docstrings across codebase#6
Merged
Conversation
- Applied NumPy docstring standard to all audio generation functions and the ContinuousOscillator class. - Added type hints for all function arguments and return types. - Imported typing.Optional and typing.Any for stricter mypy compliance.
- Applied NumPy docstring standard to `save_calibration`, `load_calibration`, and `calibrate_fs_robust`. - Added strict type hints, including `Optional` for load handling. - Explicitly cast returns to floats to ensure type consistency.
- Added module-level docstring describing the configuration purpose. - Added explicit type annotations (e.g., `: float`, `: int`, `: str`) to all constants to support strict static analysis. - Converted TIMEOUT to float for consistency with serial library expectations.
- Added `typing` imports (Generator, Optional, Type) for strict type checking. - Documented `DAQInterface` class and methods with NumPy-style docstrings. - Added explicit return type `Generator[np.ndarray, None, None]` to `stream_generator`. - Added safety check `if self.ser is None` to methods to satisfy type checker.
- Applied NumPy docstring standard to `check_signal_health` and `analyze_spectrum_peaks`. - Added strict type hints, including `Tuple` return types. - Explicitly cast `dominant_freq` to float to satisfy static analysis.
- Applied NumPy docstring standard to all DSP functions (`compute_spectrum`, `calculate_selective_thd`, etc.). - Added strict type hints, including `Tuple[np.ndarray, np.ndarray]` for spectral returns. - Explicitly cast float returns to ensure type safety. - Documented array shapes (e.g., `(N,)`, `(N/2+1,)`) in docstrings to clarify FFT outputs.
- Applied NumPy docstring standard to `capture_sweep_transfer`, `capture_steady_transfer`, and others. - Added strict type hints for all parameters and return types. - Fixed a bug in `capture_instrument_clip` where `diagnostics.plot_health_check` was called instead of the correct `plots.plot_health_check`. - Explicitly cast numpy scalars to floats in `io.save_signal` calls to ensure JSON serialization compatibility later.
- Applied NumPy docstring standard to all IO functions (`save_signal`, `load_signal`, etc.). - Added strict type hints, utilizing `typing.Optional`, `Tuple`, and `Any`. - Clarified return types for `load_signal` and `load_latest_file` to explicitly handle tuple unpacking.
- Applied NumPy docstring standard to all metric calculation functions. - Added strict type hints (`Dict[str, Any]`, `Tuple`, `Optional`). - Refined comments in `compute_bode_data_broken` and `generate_inverse_filter` for clarity. - Explicitly cast float returns in `calculate_gain_metrics` to ensure JSON serialization safety.
- Applied NumPy docstring standard to all plotting functions (`plot_gain_stage`, `plot_bode_response`, etc.). - Added strict type hints, including `Dict`, `Union`, `Optional`, and `Tuple` for robustness. - Refined inline comments and function summaries for clarity. - Explicitly cast variables where necessary to satisfy static type checkers (e.g., `vol_metric`, `pad_inches`).
- Applied NumPy docstring standard to `generate_video`, `check_ffmpeg`, and effect setup functions. - Added strict type hints, including `Callable`, `Dict`, and matplotlib object types (`Figure`, `Axes`). - Refined comments to better explain the rendering loop and stabilization logic.
- Applied NumPy docstring standard to `run_live_scope`, `run_playback_scope`, and `analyze_signal_plot`. - Added strict type hints (`Iterable`, `Callable`, `Tuple`) and matplotlib specific types (`Figure`, `Axes`, `Line2D`). - Clarified blitting logic and sync mechanism in comments. - Standardized import order and formatting.
- Added docstrings to `capture_burst` and `main` following the NumPy standard. - Added basic `int` type hints. - Avoided importing the `typing` module to ensure compatibility with standard MicroPython firmware.
- Applied NumPy docstring standard to `test_can_import_package`. - Added return type hint `-> None` for the test function.
- Added module-level and function-level docstrings. - Added return type hint to `main`.
- Added module-level docstring explaining the script's purpose. - Added type hint to the `MODE` configuration constant. - Added docstring and return type hint to `main`. - Added `noqa` comment to suppress linter warnings for the sys.path import hack.
- Added module-level docstring describing the continuous streaming functionality. - Added docstring and return type hint to `main`. - Added `noqa` comment to suppress linter warnings for imports.
- Added module-level docstring describing the single-shot capture functionality. - Added docstring and return type hint to `main`. - Added `noqa` comment to suppress linter warnings for imports.
- Added module-level docstring describing the phase portrait visualization. - Added type hints to global configuration constants and `main` function. - Added safety check for zero-division during normalization. - Added `noqa` comment for sys.path import.
- Added module-level docstring describing the drone recording process. - Added type hints to global configuration constants and `main` function. - Added explicit type hint `List[np.ndarray]` for the frames buffer. - Refined comments for clarity.
- Added module-level docstring describing the landscape rendering script. - Added return type hint to `main`. - Added safety check for `fs` being None. - Added `noqa` comment for imports.
- Added module-level docstring describing the sweep playback and visualization logic. - Added type hints to global configuration constants and `main` function. - Added `noqa` comment for the sys.path import. - Documented the synchronization logic between `viz.run_live_scope` and `start_playback`.
- Added module-level docstring describing the continuous waveform playback. - Added type hints to global configuration constants and `main` function. - Added `noqa` comment for the sys.path import. - Refined comments to clarify the auto-start behavior.
- Added module-level docstring describing the CLI tool. - Switched data loading to `src.io.load_signal` for consistency and robustness. - Added strict type casting (e.g., `int(args.zoom)`) to match `src.plots` signature. - Added `noqa` comment for the sys.path import.
- Renamed `run_oscilloscope` to `main` for project-wide consistency. - Added module-level docstring describing the manual blitting implementation. - Added strict type hints to variables and the main function. - Refined comments to explain the blitting optimization steps clearly. - Added `noqa` comment for the sys.path import.
- Added module-level docstring describing the playback utility. - Added return type hint to `main`. - Added logic comments to explain the data normalization step. - Added `noqa` comment for the sys.path import.
…o.py - Added module-level docstring describing the video rendering workflow. - Added type hints for `VIDEO_SETTINGS` and `main` function. - Added `noqa` comment for the sys.path import. - Refined comments to clarify the configuration options (CRF, presets).
- Enabled `strict = true` mode for high code quality. - Added overrides for external libraries lacking type stubs (scipy, sounddevice, serial, seaborn). - Excluded untyped directories (notebooks, firmware, schematics).
- Cast fig.canvas to Any to access backend-specific blitting methods (copy_from_bbox). - Fix color type mismatch in joyplot by converting string to rgba. - Use mcolors.Normalize instead of plt.Normalize. - Convert numpy array to list for LineCollection compatibility.
- Explicitly cast numpy scalars to int in calibration slicing. - Cast return types in metrics.py to match signatures. - Add type ignores for numpy functions returning Any (astype, random, mean) where stubs are insufficient.
- Explicitly cast the properties dictionary from `scipy.signal.find_peaks` to `Dict[str, Any]`. - Fixes a static analysis error where Pylance could not verify that "peak_heights" existed in the return type `_PeakProperties_0`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR performs a comprehensive refactor of the
src/,scripts/,firmware/, andtests/directories to establish a professional software engineering standard across the repository.The primary goals were:
mypystrict mode to catch potential bugs and improve developer experience (IDE autocompletion).[tool.mypy]configuration topyproject.toml.Key Changes
1. Source Code (
src/)audio.py): Added strict typing for NumPy arrays and sounddevice streams. Fixed return types for generator functions.daq.py): RefactoredDAQInterfacecontext manager with proper__enter__return types and safe resource management.dsp.py): Added explicit casting for NumPy scalar returns (e.g.,np.float64->float) to satisfy type checkers.viz.py,plots.py,render.py):fig.canvastoAnyfor blitting access).io.py,config.py,metrics.py,calibration.py): Added return type annotations (-> None,-> Tuple[...]) and refined error handling logic.2. Scripts (
scripts/)capture/,analysis/,fun/,signal/, andvisualization/.main()for consistency.argparsewith strict type handling where applicable.src.ioloaders to replace ad-hoc NumPy loading.3. Firmware (
firmware/main.py)capture_burstandmain.int) while avoidingtypingmodule imports to ensure MicroPython compatibility.4. Configuration & Dependencies (
pyproject.toml)[tool.mypy]configuration withstrict = true.schematic.pyand Jupyter notebooks.[[tool.mypy.overrides]]for untyped libraries (sounddevice,scipy).scipy-stubs>=1.17.0.2types-pyserial>=3.5.0.20251001types-seaborn>=0.13.2.20251221types-colorama>=0.4.15.20250801types-decorator>=5.2.0.20251101types-defusedxml>=0.7.0.20250822types-jsonschema>=4.26.0.20260109types-pexpect>=4.9.0.20260127types-pygments>=2.19.0.20251121Verification
uv run mypy .-> 0 errors.TypedDicterrors in DSP logic via explicit casting.play_sweep.py,render_scope_video.py).Checklist
mypypasses in strict mode.pyproject.tomlupdated with new dev dependencies.