Skip to content

v0.1.21 - ResponseFormatter and Output Formatting (2025-12-07)

What Changed?

This release introduces a comprehensive response formatting system (ResponseFormatter) that simplifies output handling across the CLI. Users can now easily convert device responses into multiple formats (table, JSONL, CSV, JSON) with fine-grained control over data structure representation (flattened vs. nested). The CLI has been refactored to use this unified formatter, reducing code duplication and improving maintainability.

What's New

Main Feature: ResponseFormatter Class

What it does: ResponseFormatter is a unified output formatting class that converts CommandResponse and DeviceResponse objects into multiple output formats (Rich table, JSONL, CSV, pretty-printed JSON). It supports flexible control over data representation through the use_flat parameter, allowing users to choose between flattened (single-level) or raw nested structures.

How to use it: 

from kazunoko import Command, ResponseFormatter, connect

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

    # Display as table (default)
    fmt = ResponseFormatter(resp)
    fmt.display()

    # Display as JSONL (single-line JSON)
    fmt.display(format="jsonl")

    # Display as pretty-printed JSON
    fmt.display(format="json")

    # Get formatted strings
    jsonl_str = fmt.to_jsonl()
    csv_str = fmt.to_csv()

Code example:

# Using raw nested structure instead of flattened
fmt = ResponseFormatter(resp, use_flat=False)
fmt.display(format="json")  # Shows nested JSON 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

  • ResponseFormatter class for unified response formatting
  • Support for multiple output formats: table, JSONL, CSV, pretty-printed JSON
  • use_flat parameter to control data structure representation (flattened vs. raw nested)
  • --flatten option to query command for JSONL output
  • format parameter to display() method for explicit format selection
  • to_csv_with_header() method for CSV output with column headers

🔧 Changed

  • CLI commands now use ResponseFormatter for consistent output handling
  • Removed redundant formatting logic from individual CLI commands
  • Renamed internal parameter from as_format to format in display() method
  • Status command now uses flattened structure by default for better readability

🐛 Fixed

  • Code duplication in CLI output formatting
  • Inconsistent JSON output formatting across different commands

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All existing CLI commands continue to work as before
  • Default behavior unchanged: table display for query without --flatten
  • New ResponseFormatter class is available but optional
  • Existing scripts using CLI will continue to work without modification

Tests Passed

  • ✅ Builds without errors (uv sync)
  • ✅ Type checking passes (uvx mypy src/)
  • ✅ Linting passes (uvx ruff check src/)
  • ✅ All CLI commands functional with mock device
  • ✅ ResponseFormatter output formats working (table, jsonl, json, csv)

Release Details

  • Date: 2025-12-07
  • Version: v0.1.21
  • Files Changed: 3 (formatter.py, cli.py, __init__.py)
  • Commits:
  • 0f5af0b feat: add use_flat parameter to ResponseFormatter
  • 26dbd51 refactor: rename as_format parameter to format in ResponseFormatter
  • 00e3006 feat: add --flatten option to query command
  • 477d727 feat: integrate ResponseFormatter into CLI commands
  • 9f56d81 feat: add ResponseFormatter class for flexible output formatting

Next Steps

  • Add comprehensive test suite for ResponseFormatter
  • Extend ResponseFormatter to support additional output formats (XML, HTML table export)
  • Add output streaming for large response datasets
  • Consider async support for long-running queries
  • User feedback collection on new formatting features