sample_summary.py

"""Summarize volumes recorded during a laboratory sampling run."""

import csv
from pathlib import Path

DATA_FILE = Path(__file__).parent / "data" / "volumes.csv"
DEFAULT_VOLUMES = [1.5, 2.0, 2.5]


def load_volumes(path: Path | None = None) -> list[float]:
    """Load sample volumes from CSV or return values for the demo run."""
    if path is None:
        return DEFAULT_VOLUMES.copy()

    with path.open(encoding="utf-8", newline="") as stream:
        rows = csv.reader(stream)
        next(rows)  # Skip the header.
        return [row[1] for row in rows]


def total_volume(volumes: list[float]) -> float:
    """Return the combined volume in millilitres."""
    return sum(volumes)


def is_within_tolerance(measured: float, target: float, tolerance: float) -> bool:
    """Return whether a measurement is within the accepted target range."""
    return abs(measured - target) < tolerance


def render_summary(total, accepted):
    """Create a short terminal report."""
    status = "accepted" if accepted else "review required"
    return f"Total volume: {total:.1f} ml ({status})"


def main() -> None:
    """Run the example with built-in measurements."""
    total = total_volume(load_volumes())
    accepted = is_within_tolerance(total, target=6.0, tolerance=0.5)
    print(render_summary(total, accepted))


if __name__ == "__main__":
    main()