Python Logger Support: Complete Feature Set and Module Integration

[jaycedowell]

Summary

This PR completes the Python logging integration across LSL by:
1. Extending logging support to 6 additional modules with verbose output
2. Enhancing the logger API with console/file logging and filtering capabilities
3. Creating a full-featured Tkinter GUI for log monitoring
4. Improving code quality with f-string conversion and proper documentation
5. Converting runtime warnings to use the logging system

Core Logger API Enhancements (lsl/logger.py)

New Functions

• enable_console_logging(level=None, stream=None) - Enable logging to stdout/stderr with optional level control
• disable_console_logging() - Disable console output
• enable_file_logging(filename, level=None, mode='a') - Enable logging to file with append/overwrite modes
• disable_file_logging() - Close and disable file logging
• add_filter(pattern) - Add module pattern filters (e.g., 'lsl.imaging.*')
• remove_filter(pattern) - Remove specific filter
• clear_filters() - Remove all active filters

Documentation Improvements

• Added complete Parameters/Returns sections to all function docstrings
• NumPy-style documentation throughout
• Enhanced inline comments

New Logger GUI Module (lsl/logger_gui.py)

A production-ready Tkinter GUI for real-time log monitoring with:

Features

• Real-time display with color-coded log levels (DEBUG=gray, INFO=black, WARNING=orange, ERROR/CRITICAL=red)
• Logger level control - Adjustable dropdown that changes both logger level and display filtering
• Console output toggle - Enable/disable stderr logging via checkbox
• File logging - Save logs to file with file dialog
• Pattern filtering - Module-based filtering with wildcards (e.g., 'lsl.sim.*', 'lsl_logger')
• Buffer management - Auto-trim at 10,000 lines to prevent memory issues
• Active filters display - Shows currently active filter patterns
• ThreadedHandler integration - Captures logs from any thread

Components

• LoggerFrame - Display widget with auto-scrolling and level-based hiding
• FilterFrame - Control panel for all filtering/logging options
• LoggerGUI - Complete standalone GUI window

Documentation

• Comprehensive module docstring with usage examples
• Detailed class docstrings with features and parameters
• Interactive demo mode when run standalone (python -m lsl.logger_gui)

Module Logging Extensions

Extended the logging pattern from lsl.common.sdf to 6 additional modules:

lsl/imaging/selfcal.py

• Converted all verbose output to pure logging
• DEBUG level for iteration progress (convergence metrics)
• INFO level for final calibration results
• Removed conditional if verbose: checks (kept parameter for API compatibility)

lsl/sim/vis.py

• Beam model selection notifications
• Julian date progress tracking
• Source visibility logging
• Converted positional error warning from warnings.warn() to logging.warning()

lsl/sim/dp.py

• TBN/DRX frame simulation progress
• Sample rate reporting
• Frame count updates

lsl/misc/scattering.py

• Multi-path scattering results
• Iteration counts and convergence metrics
• Best-fit scattering time reporting

lsl/writer/uvfits.py & lsl/writer/fitsidi.py

• Stand ID mapping notifications
• Geometry configuration logging

All modules follow the backward-compatible pattern:

if verbose:
    print("message")
LSL_LOGGER.info("message")

Code Quality Improvements

String Formatting Modernization

• Converted old % formatting to f-strings throughout updated modules
• Improved readability and maintainability
  Examples:
  "Using %d-order" % deg → f"Using {deg}-order"
  "Best Gains: %s" % tempGains → f"Best Gains: {tempGains}"

Runtime Warnings Conversion

Converted appropriate warnings.warn() calls to logging.warning():

• lsl/sim/vis.py - Positional error warnings
• lsl/common/sdf.py - ASP filter degeneracy warnings
• lsl/common/_sdf_utils.py - Timezone search mode warnings

Retained warnings.warn() for API-level warnings (deprecation, usage issues).

[codecov]

Codecov Report

❌ Patch coverage is 84.29003% with 52 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.25%. Comparing base (e394c1d) to head (24cb267).

Files with missing lines	Patch %	Lines
lsl/logger_gui.py	87.50%	24 Missing ⚠️
lsl/sim/dp.py	70.00%	6 Missing ⚠️
lsl/writer/uvfits.py	33.33%	6 Missing ⚠️
lsl/sim/vis.py	70.58%	5 Missing ⚠️
lsl/imaging/selfcal.py	80.00%	4 Missing ⚠️
lsl/misc/scattering.py	66.66%	3 Missing ⚠️
lsl/writer/fitsidi.py	77.77%	2 Missing ⚠️
lsl/common/sdf.py	0.00%	1 Missing ⚠️
lsl/logger.py	98.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           logger     #103      +/-   ##
==========================================
+ Coverage   84.11%   84.25%   +0.13%     
==========================================
  Files          92       93       +1     
  Lines       24443    24726     +283     
==========================================
+ Hits        20561    20832     +271     
- Misses       3882     3894      +12     

Files with missing lines	Coverage Δ
lsl/common/_sdf_utils.py	91.47% <100.00%> (ø)
lsl/common/sdf.py	87.23% <0.00%> (ø)
lsl/logger.py	96.62% <98.11%> (+24.40%)	⬆️
lsl/writer/fitsidi.py	87.10% <77.77%> (+0.34%)	⬆️
lsl/misc/scattering.py	95.14% <66.66%> (+0.30%)	⬆️
lsl/imaging/selfcal.py	93.05% <80.00%> (+2.64%)	⬆️
lsl/sim/vis.py	85.10% <70.58%> (+0.15%)	⬆️
lsl/sim/dp.py	93.85% <70.00%> (+0.40%)	⬆️
lsl/writer/uvfits.py	86.06% <33.33%> (-0.66%)	⬇️
lsl/logger_gui.py	87.50% <87.50%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.