Skip to content

v0.8.0 - Graceful Error Handling for Malformed Responses (2025-12-27)

What Changed?

This release improves robustness when the detector sends corrupted or incomplete JSON responses. Previously, a single malformed packet would crash the entire data collection process. Now, malformed data is gracefully skipped with a warning, and data collection continues seamlessly. This ensures real-world detector use with temporary communication glitches no longer results in total data loss.

What's New

Malformed Response Error Handling

What it does: The Streamer class now catches and gracefully handles ProtocolError and ResponseError exceptions that occur during JSON parsing. When malformed data is encountered, it is skipped with a warning message, and the streaming loop continues to collect the next event. This applies to both count-based (stream_by_count()) and time-based (stream_by_time()) event collection.

How to use it: No changes needed! All existing code automatically benefits from this improvement. Whether you use get_runs.py, kazunoko measure, kazunoko read, or the library API, malformed responses will now be handled gracefully.

Code example(if relevant):

from kazunoko import Measure, MeasureConfig, connect

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

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

    # Malformed packets are now silently skipped with warnings
    for event in measure.stream_by_count(1000):
        print(event.model_dump_json())
        # If a malformed packet is received:
        # - Warning logged: "Malformed event data, skipping: Invalid JSON: ..."
        # - User sees: "⚠ Malformed event data, skipping: ..."
        # - Collection continues to next event

Installation

Quick Start

# Get the release
git checkout v0.8.0

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • Graceful error handling for malformed JSON responses in Streamer.stream_by_count() and Streamer.stream_by_time()
  • ProtocolError and ResponseError exception handling to skip corrupted packets
  • Structured logging for skipped malformed events with context metadata
  • User-facing warning messages (yellow) when data is skipped

🔧 Changed

  • stream_by_count() now catches parsing errors and continues instead of raising
  • stream_by_time() now catches parsing errors and continues instead of raising

🐛 Fixed

  • Data collection no longer stops when detector sends corrupted JSON (e.g., "Invalid JSON: Expecting ':' delimiter")
  • Temporary communication glitches no longer result in total data loss

Is It Safe to Upgrade?

Backward Compatible: Yes

  • No API changes; all existing code works unchanged
  • Error handling is more lenient (catches errors that previously caused crashes)
  • New behavior is transparent; users see optional yellow warnings in stderr
  • All examples and CLI commands continue to work as before

Tests Passed

  • ✅ Builds without errors
  • ✅ Linting passes (ruff check)
  • ✅ Type checking compatible with mypy
  • ✅ Exception handling verified (ProtocolError, ResponseError caught correctly)

Release Details

  • Date: 2025-12-27
  • Version: v0.8.0
  • Files Changed: 1 (src/kazunoko/measure.py)
  • Commits: 96b7535 (feat: add graceful error handling), f4188a8 (bump: version 0.7.0 → 0.8.0)

Next Steps

  • Monitor field testing for additional edge cases with malformed responses
  • Consider adding metrics/counters for skipped malformed events
  • Potential future enhancement: automatic retry logic for transient failures
  • Continued improvements to error recovery and robustness