Skip to content

v0.1.18 - CommandResponse Wrapper for Flexible Data Access (2025-12-07)

What Changed?

This release introduces CommandResponse, a new wrapper class that provides both raw (nested) and flattened JSON structures for all Command methods. Users can now easily access device responses in the format that best suits their needs—either the original nested structure for developers or a flat structure for data export. This improves the user experience for beginners while maintaining full access to detailed information.

What's New

Main Feature: CommandResponse Wrapper

What it does: All Command methods now return a CommandResponse object with two attributes:

  • raw: The original nested JSON structure from the device
  • flat: An automatically generated flattened JSON structure with underscore-separated keys

How to use it:

from kazunoko import connect, Command

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

    # Access nested data (developer-friendly)
    print(result.raw.version)
    print(result.raw.status)

    # Access flattened data (export-friendly)
    result.flat.model_dump()  # {"type": "...", "status": "...", ...}

Code example:

# Before (v0.1.17):
response = cmd.status()
# User had to use flatten() manually for export

# After (v0.1.18):
response = cmd.status()
response.flat.model_dump()  # Ready for JSON/CSV export
response.raw.model_dump()   # Full nested structure for analysis

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

  • CommandResponse dataclass with raw and flat attributes
  • CommandResponse._flatten() static method for automatic JSON flattening
  • New public API: CommandResponse in __init__.py

🔧 Changed

  • All Command methods now return CommandResponse instead of Response
  • Affected methods: help(), status(), version(), poll_count(), deadtime(), uptime(), reset(), mac_address(), queue_stats(), led(), threshold(), thresholds(), rtc_time(), read()
  • CLI updated to use response.flat.model_dump() for flattened output
  • flatten() function removed from public API (moved to internal use)

🐛 Fixed

  • None

Is It Safe to Upgrade?

Backward Compatible: No (Breaking Change)

  • Breaking Change: All Command methods now return CommandResponse instead of Response
  • Existing code using cmd.status() directly will need to access .raw or .flat attributes
  • The flatten() function has been removed from the public API (internal use only)
  • Migration Path: Change response.field to response.raw.field or use response.flat.model_dump() for exports

Tests Passed

  • ✅ Builds without errors
  • ✅ Linting passes (ruff check)
  • ✅ All Command methods return CommandResponse
  • ✅ Flattening works correctly for nested and flat JSON
  • ✅ CLI works with flattened responses

Release Details

  • Date: 2025-12-07
  • Version: v0.1.18
  • Files Changed: 4 (command.py, cli.py, init.py, parser.py)
  • Commits: 4
  • e7afda8 feat: Add CommandResponse wrapper for flexible data access
  • 5e64fe7 refactor: Export CommandResponse from public API
  • 6046305 refactor: Update CLI to use CommandResponse attributes
  • 47a9b03 refactor: Unify all Command methods to return CommandResponse

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