Skip to content

v0.1.19 - Type Naming Clarity for DeviceResponse (2025-12-07)

What Changed?

This release renames the Response class to DeviceResponse for better API clarity. The new name explicitly indicates that this class represents responses from the device, making the type hierarchy more intuitive: DeviceResponse (device layer) and CommandResponse (command layer). This is a minor internal improvement with no functional changes.

What's New

Type Hierarchy Clarity

What it does: The parser module now exposes DeviceResponse as the primary class for JSONL response objects. This makes the API more explicit about the source and role of response objects in the library architecture.

How the type hierarchy works:

  • DeviceResponse - Represents raw responses from the device (JSONL objects)
  • Returned by device.query() and device.receive_response()

  • Used internally by CommandResponse

  • CommandResponse - Wrapper combining both raw and flattened structures

  • Returned by all Command methods
  • Contains: raw: DeviceResponse and flat: DeviceResponse

Code example:

from kazunoko import connect, Command, DeviceResponse, CommandResponse

with connect() as device:
    cmd = Command(device)

    # CommandResponse wraps DeviceResponse
    result: CommandResponse = cmd.status()

    # Both access DeviceResponse objects
    raw: DeviceResponse = result.raw      # Nested structure
    flat: DeviceResponse = result.flat    # Flattened structure

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

  • DeviceResponse as primary public API for device response objects
  • Removed flatten() function from public API (now internal only)

🔧 Changed

  • Response class renamed to DeviceResponse in parser.py
  • All device layer methods updated to use DeviceResponse type hints
  • DeviceProtocol.receive_response() return type
  • DeviceProtocol.query() return type
  • PortDevice implementation
  • MockDevice implementation
  • Parser module's parse_jsonl() function now returns DeviceResponse
  • ResponseParser methods updated to return DeviceResponse

🐛 Fixed

  • None

Is It Safe to Upgrade?

Backward Compatible: No (Minor Breaking Change)

  • This is a type naming change only - all functionality is identical
  • If you use explicit type hints with Response, update them to DeviceResponse
  • The flatten() function has been removed from public API (was rarely used directly)
  • Migration: Change response: Response to response: DeviceResponse in type hints
  • No changes needed if you don't use explicit type hints

Tests Passed

  • ✅ Builds without errors
  • ✅ Linting passes (ruff check)
  • ✅ All type hints correctly updated
  • ✅ Device layer methods return DeviceResponse
  • ✅ Command layer wraps DeviceResponse in CommandResponse

Release Details

  • Date: 2025-12-07
  • Version: v0.1.19
  • Files Changed: 5 (parser.py, command.py, device.py, mock.py, init.py)
  • Commits: 2
  • 2cd10ea refactor: Rename Response to DeviceResponse for clarity
  • 83e6a8a refactor: Remove Response backward compatibility alias

Next Steps

  • Add comprehensive unit tests for CommandResponse behavior
  • Consider async/await support for streaming detection events
  • Explore type hints optimization for better IDE autocomplete