# 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:

```text
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

```bash
# 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:

```python
# 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

```text
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](/.specify/memory/constitution.md) for more details on architectural principles.