Skip to content

v0.1.33 - Event Timeout & Code Refactoring (2025-12-13)

What Changed?

This release adds event timeout handling to the read command to prevent infinite waits when detection events are not received. The implementation introduces poll cycle-based timing, allowing users to gracefully handle scenarios with high thresholds. Additionally, the codebase has been refactored to improve maintainability by extracting reusable internal functions and improving code organization.

What's New

Main Feature: Event Timeout for Read Command

What it does: Adds a --event-timeout option to the read command that prevents infinite waiting when no detection events are received. When no event arrives within the specified timeout period, the command moves to the next poll cycle instead of hanging. This is especially useful when the detector threshold is set too high and no events are generated.

How to use it: Simply add the --event-timeout flag with a value (in seconds) to the read command:

# Default timeout (5s per cycle)
kazunoko read

# Custom timeout (2s per cycle)
kazunoko read --event-timeout 2.0

# 10 poll cycles with 3s timeout per cycle
kazunoko read --count 10 --event-timeout 3.0

# Verbose mode shows cycle progress
kazunoko read --event-timeout 2.0 -v

Code example(if relevant):

from kazunoko import connect, Command

with connect() as device:
    cmd = Command(device)
    # Each poll cycle waits up to 5 seconds for events
    for i in range(10):
        event = cmd.read()  # Will timeout after 5s and move to next cycle

Installation

Quick Start

# Get the release
git checkout v0.1.33

# Setup (if needed)
uv sync

# Try the new event timeout
uv run kazunoko read --event-timeout 3.0 -v
uv run kazunoko read --help

What's Different from the Last Version?

✅ Added

  • --event-timeout / -et option to read command (default: 5.0 seconds)
  • event_timeout() method to Options class for consistent timeout option handling
  • DEFAULT_EVENT_TIMEOUT and DEFAULT_TIMEOUT_RETRIES constants in constants.py
  • Three new internal functions in cli.py:
  • _display_response(): Display device responses with format/perspective selection
  • _poll_cycle(): Execute single poll cycle with event timeout handling
  • _read_events(): Main event reading loop across multiple poll cycles
  • Poll cycle-based event reading architecture for cleaner timeout handling

🔧 Changed

  • Semantics of --count in read command: Changed from event count to poll cycle count
  • Before: Read N events then exit
  • After: Run N poll cycles (each waiting up to --event-timeout seconds)
  • read command now uses nested while loops for clear cycle management
  • All CLI commands now use _display_response() for consistent output formatting (6 locations unified)
  • Renamed internal function from _display_event() to _display_response() for semantic accuracy
  • read command docstring updated to document poll cycle behavior and examples

🐛 Fixed

  • Infinite wait issue in read command when threshold is too high and no events arrive
  • Code duplication in response display logic across multiple CLI commands

Is It Safe to Upgrade?

Backward Compatible: Yes, with one semantic change ✓

Important Change:

  • The --count option in the read command now means "poll cycles" instead of "events"
  • Users expecting event-based counting should be aware of this behavior change
  • No API breaking changes to the Python library (Command class)

Details:

  • event_timeout is optional with a sensible default (5.0 seconds)
  • Existing read commands without --count will run infinite cycles as before (same behavior)
  • Existing read commands with --count N will now run N poll cycles instead of reading N events
  • All other CLI commands remain unchanged and fully backward compatible

Tests Passed

  • ✅ Ruff linting checks pass
  • ✅ CLI help shows event-timeout option for read command
  • ✅ Event timeout option accepted by read command
  • ✅ Poll cycle logic works correctly with nested while loops
  • ✅ Response display unified across all CLI commands (query, status, threshold, reset, read)
  • ✅ Internal functions (_display_response, _poll_cycle, _read_events) work as expected
  • ✅ Mock device integration works with event timeout
  • ✅ Backward compatibility maintained for all commands except --count semantics in read

Release Details

  • Date: 2025-12-13
  • Version: v0.1.33
  • Files Changed: 3
  • src/kazunoko/options.py - Added event_timeout() method
  • src/kazunoko/constants.py - Added DEFAULT_EVENT_TIMEOUT and DEFAULT_TIMEOUT_RETRIES
  • src/kazunoko/cli.py - Added timeout logic, refactored with internal functions
  • Commits:
  • bee087b - feat: add event timeout to read command
  • f57d984 - fix: implement proper poll cycle timeout logic for read command
  • db71922 - refactor: extract read command logic into internal functions
  • 0f53605 - refactor: use _display_event() across all CLI commands
  • 9733ef0 - refactor: rename _display_event to _display_response

Next Steps

  • Monitor user feedback on poll cycle semantics in read command
  • Consider adding adaptive timeout based on detection rate
  • Potential integration of internal functions into testable units
  • Explore async support for high-frequency data streams