Skip to content

v0.1.12 - Enhanced API with read() Method and Type-Safe Port Parameter (2025-12-03)

What Changed?

This release introduces the read() method to the Command class for streaming detection events directly from the detector. The library also gains improved type safety with Literal["auto"] for port parameters. CLI has been simplified with unified auto-detection defaults across all commands, and the version command now displays both library and device versions.

What's New

Main Feature 1: Command.read() Method

What it does: Reads and returns a single detection event from the device. Allows streaming detection data programmatically without CLI.

How to use it:

from kazunoko import connect, Command

with connect() as device:
    cmd = Command(device)
    event = cmd.read()
    print(event.model_dump())

Main Feature 2: Type-Safe Port Parameter with Literal["auto"]

What it does: The connect() function now uses port: Literal["auto"] | str = "auto" for better type safety and IDE autocomplete support.

Code example:

# Type-safe with IDE support
device = connect()              # Auto-detect (default)
device = connect("auto")        # Explicit auto-detection
device = connect("/dev/ttyUSB0")  # Specific port

Enhancement 3: Simplified CLI with Unified Defaults

What it does: All CLI commands now use port="auto" as default, removing redundant conversion logic and improving consistency.

How to use it:

kazunoko query STATUS           # Auto-detect port
kazunoko query STATUS -p /dev/ttyUSB0  # Specific port
kazunoko version                # Shows library and device versions

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

  • Command.read() method for streaming detection events programmatically
  • Literal["auto"] type annotation for connect() port parameter with IDE autocomplete support
  • Device version display in version command (kurikintons {version})
  • Enhanced Python API documentation with event loop example

🔧 Changed

  • connect() signature: port: str | None = None → port: Literal["auto"] | str = "auto"
  • CLI --port option: All commands now use port="auto" as default for consistency
  • version command output: Simplified from JSON to simple version strings
  • Removed redundant None-to-"auto" conversion logic in CLI functions

🐛 Fixed

  • Port parameter type safety improved with Literal["auto"]

Is It Safe to Upgrade?

Backward Compatible: Yes (with minor API changes)

  • Existing code using connect(port) with string paths continues to work
  • Code using connect() with None needs update: use connect("auto") or connect() instead
  • CLI behavior unchanged (auto-detection still default when no port specified)
  • All existing features remain functional

Tests Passed

  • ✅ Builds without errors
  • ✅ Type checking with mypy passes
  • ✅ CLI version command displays both library and device versions
  • ✅ connect() signature with Literal["auto"] type safe

Release Details

  • Date: 2025-12-03
  • Version: v0.1.12
  • Files Changed: 3 (device.py, cli.py, command.py documentation)
  • Commits:
  • 583bd96 - feat: update version command to display both library and device versions
  • c0b33b6 - refactor: simplify CLI by using port="auto" default for all commands
  • ae8a5ed - refactor: use Literal["auto"] for connect() port parameter
  • f22e956 - docs: enhance Python API example with event loop demonstration
  • 951aea1 - docs: update documentation to reflect read() method addition

Next Steps

  • Async support for connection and command handling
  • Additional device commands and protocol extensions
  • Performance optimizations for high-speed data streaming