Skip to content

v0.1.17 - Architecture Improvement: Public Flatten API (2025-12-07)

What Changed?

This release refactors the flatten functionality from the CLI layer to the parser layer, making it available as a public library API. Library users can now import and use the flatten() function directly: from kazunoko import flatten. This improves code organization, enables better testing, and aligns with the parser layer's responsibility for data transformation.

What's New

Main Feature: Public Flatten Function in Parser Layer

What it does: Moves the flatten() function from internal CLI helper to the public parser module. Library users can now flatten Response objects or any nested dict/list structure into single-level dictionaries with underscore-separated keys.

How to use it:

Library users: 

from kazunoko import flatten, Command, connect

with connect("/dev/ttyUSB0") as device:
    cmd = Command(device)
    response = cmd.status()
    response_dict = response.model_dump()
    flat_dict = flatten(response_dict)
    print(flat_dict)

CLI users (unchanged): 

kazunoko status --flatten
kazunoko read --format csv

Installation

Quick Start

# Get the release
git checkout v0.1.17

# Setup
uv sync

# Run CLI
uv run kazunoko --help
uv run kazunoko status --mock --flatten

# Library usage
python3 -c "from kazunoko import flatten; print(flatten({'a': {'b': 1}}))"

What's Different from the Last Version?

✅ Added

  • flatten() function available as public library API in kazunoko.parser
  • flatten exported in __init__.py for easy import: from kazunoko import flatten
  • Comprehensive docstrings with usage examples for library developers

🔧 Changed

  • Moved _flatten() from internal CLI helper (cli.py) to public parser module (parser.py)
  • cli.py now imports flatten from parser instead of defining it locally
  • Parser layer now handles all Response data transformation operations

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • CLI functionality unchanged: status --flatten and read --format csv|ssv work identically
  • Internal function move has zero impact on CLI users
  • Library users gain new public API without affecting existing code

Tests Passed

  • ✅ Builds without errors
  • ✅ kazunoko status --mock (table format - default)
  • ✅ kazunoko status --mock --flatten (flattened JSON output)
  • ✅ kazunoko read --format csv (CSV export)
  • ✅ kazunoko read --format ssv (space-separated values export)
  • ✅ Library import: from kazunoko import flatten
  • ✅ Pre-commit hooks (linting, commitizen)

Release Details

  • Date: 2025-12-07
  • Version: v0.1.17
  • Branch: main
  • Files Changed: 3 (parser.py, cli.py, __init__.py)
  • Commits:
  • 87636e6: refactor: move flatten function from cli to parser module

Next Steps

  • Add unit tests for flatten() function in parser layer
  • Consider adding --flatten option to other commands (query, threshold, etc.)
  • User Story 3 (P2): Field filtering/selection in flattened output (future enhancement)