Skip to content

v0.9.3 - Monitor TUI Real-time Updates (2025-12-27)

What Changed?

This release fixes a critical bug in the monitor.py example script where the --watch mode TUI was not updating in real-time when new events were written to JSONL files. The fix resolves file buffering issues and improves UI reactivity, enabling true real-time monitoring of detector events.

What's New

Main Feature: Real-time TUI Updates for File Monitoring

What it does: The monitor.py script's --watch mode now correctly displays events as they are written to JSONL files in real-time, rather than waiting for the file to be closed.

How to use it:

# Monitor a directory for JSONL event files with real-time updates
uv run examples/monitor.py --watch /path/to/data/directory

# Events will now appear immediately as they are written

Technical improvements:

  • Fixed file buffering that prevented line-by-line reading
  • Added proper file position tracking for incremental reads
  • Improved reactive attribute initialization for Textual widgets
  • Enhanced debug logging for troubleshooting

Installation

Quick Start

# Get the release
git checkout v0.9.3

# Setup
uv sync

# Run monitor with watch mode
uv run examples/monitor.py --watch /tmp/detector_data

What's Different from the Last Version?

🐛 Fixed

  • File Monitoring: Fixed --watch mode not updating TUI in real-time
  • Changed from buffered for line in f to unbuffered while readline() loop
  • Added buffering=1 parameter for line-based buffering
  • Update file position after each line read instead of at end of file

  • Events now appear immediately instead of waiting for file close

  • UI Reactivity: Improved Textual reactive attribute handling

  • Changed from reactive([]) to reactive(list) for proper initialization
  • Added type hints for reactive attributes

  • Refactored UI update logic into dedicated _update_ui_widgets() method

  • Startup Behavior: Added initial file reading on startup

  • Existing JSONL files are now processed when monitoring starts
  • Prevents missing events from pre-existing files
  • Background thread ensures non-blocking startup

🔧 Changed

  • Logging: Enhanced debug logging for file monitoring
  • Added on_any_event() handler to log all filesystem events
  • Track lines read and file positions in _read_new_lines()
  • Changed file event logs from DEBUG to INFO level for better visibility

Is It Safe to Upgrade?

Backward Compatible: Yes

  • No breaking changes to the monitor.py API
  • All existing functionality preserved
  • Only affects the --watch mode behavior (improves real-time updates)
  • Pipe mode and other features unchanged

Tests Passed

  • ✅ Builds without errors
  • ✅ Watch mode updates TUI in real-time with new events
  • ✅ Existing files processed on startup
  • ✅ Pipe mode continues to work correctly
  • ✅ Thread safety maintained with call_from_thread()

Release Details

  • Date: 2025-12-27
  • Version: v0.9.3
  • Files Changed: 1 (examples/monitor.py)
  • Commits: 97e8371

Next Steps

  • Further UI improvements for monitor.py (event filtering, search)
  • Performance optimization for high-frequency event streams
  • Additional example scripts for data analysis