v1.9.7 - Sampler Package Modularization (2025-12-29)

v1.9.7 - Sampler Package Modularization (2025-12-29)#

What Changed?#

This release refactors the monolithic sampler.py (1,591 lines) into a modular package structure. All functionality is preserved through re-exports in __init__.py, ensuring zero breaking changes. This foundation enables future decomposition into specialized modules (Reader, Writer, Iterators) while maintaining full backward compatibility.

What’s New#

Sampler Module Refactoring#

What it does: The large src/haniwers/v1/daq/sampler.py file (59KB, 1,591 lines) has been reorganized into a modular package structure:

src/haniwers/v1/daq/sampler/
├── __init__.py           # Re-exports for backward compatibility
└── _base.py              # Complete Sampler class (1,591 lines)

Migration strategy: This is Phase 1 of a multi-phase decomposition plan:

  • Phase 1 (v1.9.7): Package structure created ✓

    • Original sampler.py moved to sampler/_base.py

    • __init__.py provides re-exports for full backward compatibility

  • Phase 2 (v1.9.8 planned): Logical decomposition

    • Split into: _reader.py, _writer.py, _iterators.py, _helpers.py

    • Each module handles a single responsibility (SRP)

    • All internal; public API unchanged

  • Phase 3 (v1.10.0 planned): Further optimization

    • Potential extraction of common patterns

    • Performance improvements if applicable

Benefits:

  • Foundation for decomposition: Enables future modularization without breaking changes

  • Improved maintainability: Clear structure for code organization

  • Better IDE support: Easier to navigate modular structure

  • Future flexibility: Easy to add new modules or refactor internals

  • Backward Compatible: Existing code continues to work unchanged

Installation#

Quick Start#

# Get the release
git checkout v1.9.7

# Setup
task env:setup

# Run CLI
haniwers-v1 --help

What’s Different from the Last Version?#

✅ Added#

  • Modular daq/sampler/ package structure with separate __init__.py and _base.py

  • Foundation for Phase 2 decomposition (Reader, Writer, Iterators modules)

🔧 Changed#

  • Reorganized src/haniwers/v1/daq/sampler.py → src/haniwers/v1/daq/sampler/_base.py

  • No changes to public API or functionality

🐛 Fixed#

  • No bug fixes in this release

Is It Safe to Upgrade?#

Backward Compatible: ✅ Yes

All existing imports continue to work without modification:

# This still works:
from haniwers.v1.daq.sampler import Sampler

# Same usage as before:
sampler = Sampler(device, config, output_dir)
sampler.acquire_by_count(Path("data.csv"), 1000)

No breaking changes to the Sampler API, config, or CLI interface.

Tests Passed#

  • ✅ Builds without errors

  • ✅ All 133 unit tests passing (DAQ module)

  • ✅ Sampler functionality tests passing (18 tests)

  • ✅ MAC address tests passing (3 tests)

  • ✅ Module re-exports verified

  • ✅ Import compatibility verified

  • ✅ Pre-commit hooks passing (ruff format, YAML, etc.)

Release Details#

  • Date: 2025-12-29

  • Version: v1.9.7

  • Files Changed: 2 (created __init__.py, renamed sampler.py → _base.py)

  • Commits:

    • 7c36df7: refactor(daq/sampler): convert monolithic file into modular package

    • 5dfdbb3: bump: version 1.9.6 → 1.9.7

Next Steps#

Phase 2 (v1.9.8 planned): Logical Module Decomposition#

src/haniwers/v1/daq/sampler/
├── __init__.py           # Re-exports all classes
├── _base.py              # Sampler base class (initialization, coordination)
├── _reader.py            # EventReader (read_event, stream_events, collect_events)
├── _writer.py            # EventWriter (save_events, acquire_by_count, acquire_by_time)
├── _iterators.py         # Iterators (count_based_iterator, time_based_iterator)
└── _helpers.py           # Static helpers (sanitize, tqdm_wrapper)

Benefits of Phase 2:

  • Single Responsibility Principle (SRP) fully applied

  • Each module ~300-400 lines instead of 1,591 lines

  • Improved testability and code organization

  • Clearer relationships between components

Phase 3 (v1.10.0 planned): Technical Debt Resolution#

  • Complete removal of deprecated DaqConfig and ScanConfig models

  • Removal of TODO comments with implementations

  • Integration test stabilization

  • Performance optimization if needed

v1 → v2 Transition#

This refactoring prepares v1 for stable maintenance mode while providing:

  • Clean codebase for v2 migration

  • Reusable helper modules for v2

  • Clear architectural patterns to follow

Architecture Decision#

This modularization follows the Single Responsibility Principle (SRP):

  • Each module has one reason to change

  • Dependencies flow downward (high-level → utilities)

  • Public API remains unchanged

This pattern will be applied to other large modules in future releases:

  • config/model.py (1,184 lines) → Phase 2.2

  • Other ~700+ line files as needed

See project constitution for more details on architectural principles.

目次