Skip to content

v0.1.50 - Streamer Base Class & Event Streaming API (2025-12-14)

What Changed?

This release introduces a new Streamer base class that provides a unified streaming interface for both count-based and time-based event collection. Both Reader and Measure classes now inherit from Streamer, enabling flexible memory-efficient and batch-based event reading patterns through generators and convenience methods.

What's New

Main Feature: Streamer Base Class with Generator-Based Streaming

What it does: - Introduces Streamer base class with 4 new methods for flexible event collection - Provides generator-based streaming (stream_by_count, stream_by_time) for memory-efficient processing - Provides list-based convenience methods (read_by_count, read_by_time) for batch collection - Both Reader and Measure classes inherit streaming capabilities automatically

How to use it:

Reader - Simple streaming without initialization: 

from kazunoko import connect, Reader

with connect() as device:
    reader = Reader(device, event_timeout=5.0)

    # Generator-based: memory-efficient for large datasets
    for event in reader.stream_by_count(1000000):
        process(event)  # Process one at a time

    # List-based: convenient batch collection
    events = reader.read_by_count(100)
    events = reader.read_by_time(60.0)  # Collect for 60 seconds

Measure - Threshold measurement with streaming: 

from kazunoko import connect, Measure, MeasureConfig

config = MeasureConfig(thresholds={1: 300, 2: 300, 3: 300})

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

    # Generator-based streaming with metadata merged
    for event in measure.stream_by_count(1000):
        process(event)  # Each event has threshold1, threshold2, threshold3, mac_address, etc.

    # List-based convenience
    events = measure.read_by_count(100)
    events = measure.read_by_time(60.0)

Installation

Quick Start

# Get the release
git checkout v0.1.50

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • Streamer base class with generator-based and list-based event streaming methods
  • stream_by_count() - Generator for memory-efficient count-based streaming
  • stream_by_time() - Generator for memory-efficient time-based streaming
  • read_by_count() - Convenience method for batch count-based collection
  • read_by_time() - Convenience method for batch time-based collection
  • Streaming interface now available on both Reader and Measure classes through inheritance

🔧 Changed

  • Reader and Measure now inherit from Streamer base class
  • Measure.stream_by_count() and Measure.stream_by_time() now enforce initialize() call
  • Architecture refactored for better code reuse and separation of concerns

🐛 Fixed

  • None in this release

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All existing Reader and Measure methods remain unchanged
  • New streaming methods are additions that don't affect existing code
  • Existing users can continue using read_event() as before
  • New streaming capabilities are optional and discoverable

Tests Passed

  • ✅ Builds without errors
  • ✅ Type checking passes (mypy)
  • ✅ Linting passes (ruff)
  • ✅ Existing Reader/Measure functionality preserved
  • ✅ New Streamer base class methods available on both classes

Release Details

  • Date: 2025-12-14
  • Version: v0.1.50
  • Files Changed: src/kazunoko/measure.py, src/kazunoko/cli.py
  • Commits:
  • dd17d9a feat: add streaming and measuring methods to Measure class
  • bb3735d refactor: introduce Streamer base class for event streaming
  • 871472e feat: add measure-by-count and measure-by-time CLI commands
  • fef5d1c refactor: consolidate measure commands via --use-event/--use-duration option

CLI Enhancements

Unified Event Collection Interface

Both read and measure commands now support flexible collection modes via --use-event/--use-duration option toggle, providing a consistent and intuitive API across all event collection workflows.

Extended read command

The read command now supports both count-based and time-based event collection via the --use-event/--use-duration option:

Count-based collection (default):

# Read exactly 10 events
kazunoko read 10

# Read 100 events with custom event timeout
kazunoko read 100 --event-timeout 3.0

# Read 50 events in CSV format
kazunoko read 50 --format csv > events.csv

Time-based collection:

# Read for 60 seconds
kazunoko read 60 --use-duration

# Read for 30 seconds with verbose output
kazunoko read 30 --use-duration -v

# Read for 120 seconds with custom serial timeout
kazunoko read 120 --use-duration --timeout 0.5

Supported options:

  • --use-event (default): Count-based collection (read exactly N events)
  • --use-duration: Time-based collection (read for N seconds)
  • --format: Output format (jsonl, table, json, csv, ssv, tsv, ltsv)
  • --use-flat: Use flattened structure for compact output
  • --event-timeout: Timeout for event collection (default: 5.0s)
  • --timeout: Serial communication timeout (default: 0.1s)

Extended measure command

The measure command supports both count-based and time-based event collection via the --use-event/--use-duration option:

Count-based collection (default):

# Measure 1000 events at 300 ADC on all channels
kazunoko measure "1:300;2:300;3:300" 1000

# Different channels with different thresholds
kazunoko measure "1:500;2:300;3:300" 500 --port /dev/ttyUSB0

# Use verbose output
kazunoko measure "1:300;2:300;3:300" 1000 -v

Time-based collection:

# Measure for 60 seconds at 300 ADC on all channels
kazunoko measure "1:300;2:300;3:300" 60 --use-duration

# Collect for 30 seconds with different thresholds
kazunoko measure "1:500;2:300;3:300" 30 --use-duration --port /dev/ttyUSB0

# Use verbose output
kazunoko measure "1:300;2:300;3:300" 60 --use-duration -v

Supported options:

  • --use-event (default): Count-based collection (collect exactly N events)
  • --use-duration: Time-based collection (collect for N seconds)
  • --format: Output format (jsonl, table, json, csv, ssv, tsv, ltsv)
  • --use-flat: Use flattened structure for compact output
  • --event-timeout: Timeout for event collection (default: 5.0s)
  • --poll-count: Events per poll cycle (range: 1-65535)
  • --timeout: Serial communication timeout (default: 0.1s)

Next Steps

  • Add comprehensive integration tests for streaming methods
  • Consider adding streaming support to other data readers
  • Explore streaming optimizations for very large datasets