Skip to content

v0.1.28 - ResponseView Pattern for Dual Response Perspectives (2025-12-07)

What Changed?

This release introduces the ResponseView class that provides seamless access to both raw (nested) and flattened representations of device responses. The refactoring improves developer experience by making it easy to choose between perspectives before formatting, while simplifying the ResponseFormatter API to accept only typed DeviceResponse objects. All CLI commands have been updated to use the new pattern.

What's New

Main Feature: ResponseView - Dual Response Perspectives

What it does: ResponseView is a new dataclass that wraps a DeviceResponse and automatically provides both raw (original nested structure) and flat (flattened with underscore-separated keys) perspectives. This enables developers to work with responses in the format that best suits their needs without complex parameter handling.

How to use it:

from kazunoko import Command, ResponseView, ResponseFormatter, connect

with connect() as device:
    cmd = Command(device)
    response = cmd.status()

    # Wrap in ResponseView to get both perspectives
    rv = ResponseView(raw=response)

    # Access raw nested structure (original DeviceResponse)
    raw_data = rv.raw

    # Access flattened structure (type-safe DeviceResponse with flat keys)
    flat_data = rv.flat

    # Format and display the perspective you want
    fmt = ResponseFormatter(rv.flat)  # Use flat for simpler structures
    fmt.display(format="table")

Code example:

Before (v0.1.27):

cmd = Command(device)
resp = cmd.status()
fmt = ResponseFormatter(resp, use_flat=True)  # Implicit perspective selection
fmt.display()

After (v0.1.28):

cmd = Command(device)
resp = cmd.status()
rv = ResponseView(raw=resp)  # Explicit perspective wrapping
fmt = ResponseFormatter(rv.flat)  # Explicit perspective selection
fmt.display()

Installation

Quick Start

# Get the release
git checkout v0.1.28

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • ResponseView dataclass: Provides raw and flat perspectives of device responses
  • ResponseView._flatten() staticmethod: Recursively flattens nested structures with underscore-separated keys
  • Comprehensive documentation with dual perspective examples in docstrings

🔧 Changed

  • Breaking Change: ResponseFormatter now accepts only DeviceResponse parameter (removed use_flat parameter)
  • ResponseView.flat is now type-safe (DeviceResponse) instead of dict[str, Any]
  • All CLI commands updated to use explicit ResponseView pattern:
  • query command
  • read command
  • status command
  • threshold command
  • reset command
  • Updated all docstrings and examples to show the new pattern

🐛 Fixed

  • Simplified ResponseFormatter initialization by removing implicit perspective selection logic
  • Eliminated parameter confusion in formatter API through explicit perspective selection

Is It Safe to Upgrade?

Backward Compatible: No (Breaking changes to public API)

Migration Guide:

If you use ResponseFormatter directly:

# Old (v0.1.27)
fmt = ResponseFormatter(response, use_flat=True)
fmt.display()

# New (v0.1.28)
rv = ResponseView(raw=response)
fmt = ResponseFormatter(rv.flat)
fmt.display()

Impact on existing users:

  • Library users need to wrap responses with ResponseView before formatting
  • CLI users see no functional change (commands work the same way)
  • All command responses are still DeviceResponse objects; only the perspective wrapping pattern is new

Tests Passed

  • ✅ Builds without errors (Ruff lint: 100% pass)
  • ✅ Type checking compatible (mypy - external stubs only)
  • ✅ Mock device integration tests pass
  • ✅ ResponseView flattening logic verified with nested and flat structures
  • ✅ All CLI commands work with both raw and flat perspectives

Code Changes Summary

Files Modified: 3

  • src/kazunoko/formatter.py - Added ResponseView class, simplified ResponseFormatter API
  • src/kazunoko/__init__.py - Added ResponseView to exports
  • src/kazunoko/cli.py - Updated 5 commands (query, read, status, threshold, reset) to use ResponseView pattern

Lines Changed: 187 added, 78 removed (109 net addition)

Release Details

  • Date: 2025-12-07
  • Version: v0.1.28
  • Files Changed: 3
  • Commits:
  • 587ff9c - feat: introduce ResponseView wrapper for dual response perspectives
  • c42275a - refactor: make ResponseView.flat type-safe with DeviceResponse
  • 193b61a - refactor: simplify ResponseFormatter to accept only DeviceResponse
  • 9ba7f83 - refactor(cli): update status command to use ResponseView
  • a98c97f - refactor(cli): update query command to use ResponseView
  • 41133cd - refactor(cli): update read command to use ResponseView
  • e61c11f - refactor(cli): update threshold and reset commands to use ResponseView

Next Steps

Future improvements to consider:

  • Add comprehensive test suite for ResponseView perspective handling
  • Consider adding perspective parameter hints to ResponseFormatter for IDE discovery
  • Document common use cases for raw vs flat perspectives in user guide
  • Gather user feedback on the dual perspective pattern