Skip to content

v0.1.49 - Reader Class and Architecture Refactoring (2025-12-14)

What Changed?

This release refactors the event reading architecture by moving domain logic from the CLI layer to the measure module. A new lightweight Reader class handles simple event streaming, while shared timeout retry logic eliminates duplication between Reader and Measure. The refactoring improves code organization while maintaining full backward compatibility.

What's New

Domain Layer: Reader Class

What it does: The new Reader class provides lightweight event reading without initialization overhead. It handles simple event streaming with automatic timeout retry logic, making it the appropriate layer for CLI operations that don't require threshold configuration or metadata collection.

How to use it:

from kazunoko import connect, Reader

with connect() as device:
    reader = Reader(device, event_timeout=5.0)
    reader.set_rtc_time()  # Optional: sync device RTC
    event = reader.read_event()
    print(event.channel)  # Detection channel

Architecture improvement:

  • Domain logic moved to measure.py module
  • Shared _read_event() helper function eliminates duplication
  • Clear separation: domain logic vs. presentation layer

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

  • Reader class in measure.py for lightweight event streaming
  • _read_event() shared helper function for event reading with timeout retry logic
  • Reader exported in public API (__init__.py)

🔧 Changed

  • Measure.read_event() now uses shared _read_event() helper function
  • cli.read() command now uses Reader class instead of helper functions
  • Method naming aligned with Command.rtc_time(): set_device_time() → set_rtc_time()
  • Helper function renamed: _read_event_with_timeout() → _read_event()
  • Refactored event reading to separate domain logic (measure.py) from presentation (cli.py)

🐛 Fixed

  • Eliminated code duplication between event reading implementations
  • Improved separation of concerns following SRP principle
  • Removed unused _device attribute from Reader and Measure classes

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All existing CLI commands (read, measure, etc.) work unchanged
  • New Reader class is optional and only needed for library users
  • No breaking changes to public APIs or command-line interfaces

Tests Passed

  • ✅ Builds without errors
  • ✅ kazunoko read command works with real device
  • ✅ kazunoko measure command works with real device
  • ✅ Ruff linting passes (no new issues)
  • ✅ Type checking passes

Release Details

  • Date: 2025-12-14
  • Version: v0.1.49
  • Files Changed: 8 (measure.py, cli.py, init.py, README.md, CLAUDE.md, docs/api/design.md, docs/releases/v0.1.49.md)
  • Commits: a2556ff, 8a25650, b7097e3, 0146a3f, 6335106, d9122cf, f8cf336, b28a9d7, 96ccdc1, 2da3d85
  • Net Code Change: +214 insertions, -189 deletions (cleaner architecture)

Next Steps

Future releases may expand the Reader API with optional features like batch event reading, automatic format conversion, or event filtering while maintaining the lightweight design principles.