Skip to content

v0.6.1 - Enhanced Type Safety for CLI Arguments (2025-12-26)

What Changed?

This patch release improves type safety and runtime validation for the log_level parameter across all example scripts. Typer now automatically validates log level values at runtime, rejecting invalid inputs with clear error messages. This ensures consistency between the main CLI and example scripts.

What's New

Enhancement: Literal Type Validation for log_level

What it does: Adds Literal type annotations to log_level parameters in all example scripts, enabling Typer's built-in runtime validation. Invalid log level values are now rejected with clear, user-friendly error messages.

How to use it:

# Valid log levels
uv run examples/get_events.py "1:300;2:320;3:310" 100 --log-level info
uv run examples/get_events.py "1:300;2:320;3:310" 100 --log-level debug

# Invalid log level (now rejected with clear error)
uv run examples/get_events.py "1:300;2:320;3:310" 100 --log-level invalid
# Error: Invalid value for '--log-level': 'invalid' is not one of 'debug', 'info', 'success', 'warning', 'error'.

Code example:

Before:

log_level: str = Options.log_level()  # Typer doesn't validate

After:

from typing import Literal

log_level: Literal["debug", "info", "success", "warning", "error"] = Options.log_level()  # Typer validates ✅

Installation

Quick Start

# Get the release
git checkout v0.6.1

# Setup
task env:setup

# Run example with validation
uv run examples/get_events.py "1:300;2:320;3:310" 100 --log-level info

What's Different from the Last Version?

🔧 Changed

  • Enhanced type safety: All example scripts now use Literal type for log_level parameters
  • Runtime validation: Typer now validates log level values in all scripts, matching CLI behavior
  • Consistent error messages: Invalid values rejected with clear, actionable error messages

✅ Improved

  • Type consistency between CLI and example scripts
  • IDE autocomplete support for log level values across all scripts
  • Runtime error handling for invalid log level inputs

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

This is a patch release with no breaking changes. All existing valid code continues to work as before. The only difference is that previously-invalid inputs (like --log-level invalid) now produce clear error messages instead of failing silently at runtime.

What's different

  • More strict input validation: Invalid --log-level values are now caught earlier
  • Clearer error messages: Users see exactly which values are valid
  • No API changes: All valid code works exactly the same

Tests Passed

  • ✅ Builds without errors
  • ✅ All linting checks pass (ruff check)
  • ✅ Type checking passes (mypy with known existing issues)
  • ✅ Invalid log levels rejected with clear error messages
  • ✅ Valid log levels accepted in all example scripts
  • ✅ Pre-commit hooks pass for all commits

Release Details

  • Date: 2025-12-26
  • Version: v0.6.1
  • Type: Patch (bug fixes & improvements)
  • Files Changed: 4 (examples/)
  • Commits: 5 commits (4 feature commits + 1 version bump)
  • b2b5186: refactor: add Literal type to log_level parameter in get_events.py
  • e950bf7: refactor: add Literal type to log_level parameter in get_thresholds.py
  • 4d81eb2: refactor: add Literal type to log_level parameter in fit_thresholds.py
  • 55a9945: refactor: add Literal type to log_level parameter in get_runs.py
  • 001b8cf: bump: version 0.6.0 → 0.6.1

Key Points

Type Safety Improvements

This release brings type safety to the example scripts that matches the main CLI:

Component Before After
CLI ✅ Literal type validates ✅ Literal type validates
Examples ❌ str type no validate ✅ Literal type validates

Error Messages

Before (hidden error at runtime):

setup_logger() received invalid value 'invalid' → error in loguru

After (clear validation error):

Invalid value for '--log-level': 'invalid' is not one of 'debug', 'info', 'success', 'warning', 'error'.

Migration Notes

No migration needed - this is a fully backward-compatible patch release. All existing valid code continues to work identically.

If your code was using invalid log level values (which would have failed anyway), you'll now see clear error messages guiding you to valid options.

Next Steps

Future improvements planned:

  • Continue improving type safety across the codebase
  • 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