Skip to content

v0.1.51 - Measurement Configuration Validation and setup() Rename (2025-12-14)

What Changed?

This release adds comprehensive validation to MeasureConfig dataclass, ensures that detector thresholds, poll counts, and event timeouts are within valid device ranges. Additionally, the Measure.initialize() method has been renamed to setup() to better reflect the physical experiment workflow. Both MeasureConfig and MeasureMetadata are now implemented as Pydantic dataclasses for better type safety and validation support. The setup() rename improves semantic clarity for measurement workflows.

What's New

Feature 1: Pydantic Validation for Measurement Configuration

What it does: MeasureConfig now automatically validates threshold values (0-1023), poll counts (1-65535), and event timeouts (> 0 seconds) using Pydantic field validators. Invalid configurations are caught immediately when the object is created, preventing runtime errors during measurement sessions.

How to use it: Create a MeasureConfig exactly as before. Invalid values now raise a ValidationError with helpful messages:

from kazunoko import Measure, MeasureConfig

# Valid configuration - works as before
config = MeasureConfig(
    thresholds={1: 300, 2: 300, 3: 300},
    poll_count=25000,
    event_timeout=5.0,
)

# Invalid threshold value - raises ValidationError immediately
try:
    config = MeasureConfig(thresholds={1: 2000})  # Above max of 1023
except ValidationError as e:
    print(f"Configuration error: {e}")

# Invalid channel - raises ValidationError immediately
try:
    config = MeasureConfig(thresholds={4: 300})  # Channel must be 1-3
except ValidationError as e:
    print(f"Configuration error: {e}")

Validation Rules:

  • Thresholds: Channels 1-3 only, values 0-1023
  • Poll Count: Range 1-65535
  • Event Timeout: Must be positive (> 0 seconds)

Feature 2: Measure.initialize() Renamed to setup()

What it does: The Measure.initialize() method is now called setup() to better reflect the physical experiment workflow. "Setup" is the standard term in experimental physics for device preparation and calibration before measurements.

Migration: Simply rename the method call:

# Before (v0.1.50)
measure.initialize()

# After (v0.1.51)
measure.setup()

Both stream_by_count() and stream_by_time() now properly enforce that setup() must be called before streaming.

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

  • Pydantic field validators for MeasureConfig thresholds, poll_count, and event_timeout
  • Comprehensive validation rules enforced at object creation time
  • Detailed error messages for invalid configuration values
  • Field descriptions for IDE autocomplete and documentation generation

🔧 Changed

  • MeasureConfig now uses pydantic.dataclasses.dataclass instead of standard dataclasses.dataclass
  • MeasureMetadata now uses pydantic.dataclasses.dataclass for consistency
  • Both classes now use Field() for better type hints and documentation
  • Measure.initialize() renamed to Measure.setup() for better semantic clarity
  • Error messages updated to reference setup() instead of initialize()

🐛 Fixed

  • Invalid threshold configurations are now caught immediately instead of failing at device communication time
  • Measurement workflow terminology now aligns with experimental physics conventions

Is It Safe to Upgrade?

Backward Compatible: Mostly ✅ (Minor Breaking Change)

  • Breaking Change: Measure.initialize() renamed to setup() — Update method calls
  • Safe: Existing valid MeasureConfig code continues to work without any changes
  • Safe: Only invalid configurations (those that would have failed at runtime anyway) now fail at creation time
  • Safe: All other method signatures and behavior remain unchanged
  • Migration: Simple find-replace: initialize() → setup()

Tests Passed

  • ✅ Builds without errors
  • ✅ All validation rules tested (10 test cases)
  • ✅ Linting passed (ruff)
  • ✅ Valid configurations accepted
  • ✅ Invalid channels (4+) rejected
  • ✅ Invalid threshold values (0-1023 enforced) rejected
  • ✅ Invalid poll_count values (1-65535 enforced) rejected
  • ✅ Invalid event_timeout values (>0 enforced) rejected
  • ✅ Empty thresholds rejected
  • ✅ MeasureMetadata creation works correctly

Release Details

  • Date: 2025-12-14
  • Version: v0.1.51
  • Files Changed: 8 total
  • Source: src/kazunoko/measure.py, src/kazunoko/cli.py
  • Docs: docs/releases/v0.1.51.md, docs/api/design.md, docs/releases/v0.1.50.md
  • README: README.md
  • Project: CLAUDE.md
  • Key Changes:
  • Converted MeasureConfig and MeasureMetadata to Pydantic dataclasses
  • Added comprehensive validation with 5 validation rules
  • Renamed Measure.initialize() → Measure.setup()
  • Updated all documentation and examples
  • Enhanced type safety with Field() descriptors

Next Steps

  • Consider adding similar validation to other configuration classes if needed
  • Monitor user feedback on validation error messages
  • Future enhancement: Add configuration saving/loading with validation