"""Human-readable float assertions for tests.

Replaces the cryptic ``assert abs(actual - expected) <= 1e-9`` idiom with a
named helper that says what it checks and prints a useful message on failure.
"""

from __future__ import annotations

from typing import Optional


def assert_float_matches(
    actual: float,
    expected: float,
    *,
    tol: float = 1e-9,
    msg: Optional[str] = None,
) -> None:
    """Assert ``actual`` equals ``expected`` within an absolute tolerance.

    ``tol`` defaults to ``1e-9`` for exact-arithmetic checks; pass a looser
    value (e.g. ``tol=1e-4``) where the comparison is physically approximate.
    """
    diff = abs(actual - expected)
    detail = f"\n{msg}" if msg else ""
    assert diff <= tol, (
        f"expected {expected!r} but got {actual!r} "
        f"(|diff| {diff:g} > tol {tol:g}){detail}"
    )