Skip to content

v0.1.53 - Graceful Event-Timeout Handling (2025-12-14)

What Changed?

This release fixes event-timeout handling in streaming operations. Previously, when no detection event arrived within the configured timeout window, the measurement would fail immediately with an error. Now, streaming continues gracefully with visual feedback, allowing measurements to complete even with sparse event rates. Users see clear progress messages indicating which event is being waited for and how long the timeout is.

What's New

Main Feature: Graceful Event-Timeout Handling

What it does: When collecting detection events with measure or read commands, if no event arrives within the event_timeout period, the streaming now continues to the next event instead of failing. Users receive visual feedback with progress information (e.g., "⏱ Waiting for event 1/2: No event received within 5.0s timeout").

How to use it: The feature works automatically with existing commands. Just use measurement commands as normal:

# Count-based measurement (continues through timeouts)
kazunoko measure "1:400;2:460;3:430" 10 -v

# Time-based measurement (continues through timeouts)
kazunoko measure "1:400;2:460;3:430" 60 --use-duration -v

Code example(if relevant):

from kazunoko import connect, Measure, MeasureConfig

config = MeasureConfig(
    thresholds={1: 300, 2: 300, 3: 300},
    event_timeout=5.0  # Wait up to 5 seconds per event
)

with connect() as device:
    measure = Measure(device, config)
    measure.setup()

    # Streaming continues even if events timeout
    for event in measure.stream_by_count(100):
        print(event.detected_at)

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Setup
task env:setup

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • New EventTimeout exception to distinguish event-level timeout from communication timeout
  • Graceful timeout handling in stream_by_count() and stream_by_time() methods
  • Progress feedback messages with event count and timeout duration during streaming

🔧 Changed

  • stream_by_count() now continues on event timeout instead of raising exception
  • Event timeout messages now display with stopwatch emoji (⏱) and progress info
  • Removed ResponseTimeout error handling from measure command (handled internally now)

🐛 Fixed

  • Fixed issue where streaming would fail immediately when no event arrived within timeout window
  • Streaming now correctly skips timeout events and continues to the next iteration

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Existing code continues to work unchanged
  • The EventTimeout exception is a new exception type that only appears in new internal flows
  • CLI behavior is improved but maintains same command signatures
  • Users with low event rates will benefit from more resilient streaming

Tests Passed

  • ✅ Builds without errors
  • ✅ Event timeout handling works with sparse event rates
  • ✅ Progress messages display correctly with event count
  • ✅ Streaming completes successfully even with multiple timeouts
  • ✅ Both count-based and time-based streaming work correctly

Release Details

  • Date: 2025-12-14
  • Version: v0.1.53
  • Files Changed: 4 (measure.py, cli.py, exceptions.py, init.py)
  • Commits:
  • 919bbae: fix: handle event-timeout gracefully in streaming
  • 1cfbdd7: fix: improve event timeout message with progress information
  • bbab960: style: change event timeout indicator from hourglass to stopwatch
  • 3ed8782: fix: correct event timeout handling in stream_by_count

Next Steps

  • Consider adding animated spinner for longer timeout waits
  • Explore configurable timeout messages for different use cases
  • Monitor user feedback on event timeout frequency