Skip to content

v0.6.0 - Unified Logging API (2025-12-26)

What Changed?

This release unifies the logging configuration API by renaming the verbosity parameter to log_level across all modules. The default logging behavior is now quieter (error instead of info), and type safety has been improved with Literal type annotations. This is a breaking change that requires updating code using setup_logger().

What's New

Main Feature: Unified Logging Parameter

What it does: Standardizes the logging configuration parameter name from verbosity to log_level for clarity and consistency across the entire codebase. Adds support for five explicit log levels with type-safe annotations.

How to use it:

from kazunoko.log import setup_logger

# Default: ERROR level only (quiet by default)
setup_logger()

# INFO level: progress messages
setup_logger(log_level="info")

# DEBUG level: detailed troubleshooting
setup_logger(log_level="debug")

# SUCCESS level: completion messages only
setup_logger(log_level="success")

# WARNING level: issues only
setup_logger(log_level="warning")

CLI usage:

# Default: error level only
kazunoko status

# Info level: show progress
kazunoko --level info read 100

# Debug level: detailed logging
kazunoko --level debug measure "1:300;2:320;3:310" 100

Installation

Quick Start

# Get the release
git checkout v0.6.0

# Setup
task env:setup

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

🔧 Changed

  • BREAKING: setup_logger(verbosity=...) → setup_logger(log_level=...)
  • Default log level changed from "info" to "error" (quieter by default)
  • Expanded supported levels to 5: debug, info, success, warning, error
  • Added Literal type annotations for type safety in log.py, cli.py, and options.py
  • Updated all example scripts (get_events.py, get_thresholds.py, fit_thresholds.py, get_runs.py, monitor.py)

✅ Added

  • Literal type import in options.py for type-safe parameter definitions
  • Type-safe Options.log_level() method with Literal return type
  • IDE autocomplete support for valid log level values

Is It Safe to Upgrade?

Backward Compatible: No ⚠️

Migration Required

Old API:

setup_logger(verbosity="info")

New API:

setup_logger(log_level="info")

Impact on existing users

  • Any code calling setup_logger(verbosity=...) will break
  • Update all setup_logger() calls to use log_level= parameter
  • Default behavior is quieter (ERROR only) - use log_level="info" for previous behavior
  • CLI global option remains --level (unchanged)

Tests Passed

  • ✅ Builds without errors
  • ✅ All linting checks pass (ruff check)
  • ✅ Type checking passes (mypy with known existing issues)
  • ✅ CLI help displays all 5 log levels correctly
  • ✅ All example scripts updated and verified
  • ✅ Pre-commit hooks pass for all commits

Release Details

  • Date: 2025-12-26
  • Version: v0.6.0
  • Files Changed: 9 (log.py, cli.py, options.py, 5 examples/, CHANGELOG.md)
  • Commits: 10 commits (9 feature commits + 1 version bump)
  • 2f74246: refactor: rename setup_logger parameter verbosity to log_level
  • ec4bb18: refactor: update cli.py to use log_level with Literal type
  • 945a4ed: docs: update Options.log_level() docstring and help text
  • ce8aa62: refactor: update get_events.py to use new log_level parameter
  • d2ec4b0: refactor: update get_thresholds.py to use new log_level parameter
  • bc7ec7d: refactor: update fit_thresholds.py to use new log_level parameter
  • 189a3d6: fix: update get_runs.py setup_logger call to use log_level parameter
  • 3d55bb1: fix: update monitor.py setup_logger call to use log_level parameter
  • efdae2e: refactor: add Literal type annotation to Options.log_level()
  • 1577753: bump: version 0.5.0 → 0.6.0

Next Steps

Future improvements planned:

  • Consider adding TRACE level for even more detailed logging
  • Explore structured logging output formats beyond JSON
  • Add log filtering by module/component for targeted debugging