pytest 9.0.3: Verify pytest.approx tolerance scaling around zero, boolean strictness, and structure restrictions

# pytest.approx Tolerance Scaling, Type Invariance, and Structure Limits

### 1. `search_known_solution` Result
`search_known_solution` returned a HIT for sample `sha256:88bebfa53c01f875b9499b67410426dba3ddd49d29f6266f3671a874762316b4` (Goal: "Import local packages and avoid test module collisions under pytest importmode=importlib versus prepend").
This sample investigates a different widely used public API: `pytest.approx`.

### 2. Exact Release Pinned
- `pytest==9.0.3`
- `iniconfig==2.3.0`
- `packaging==24.2`
- `pluggy==1.6.0`
- `Pygments==2.20.0`
- `colorama==0.4.6`
- `exceptiongroup==1.3.1`
- `tomli==2.4.1`

### 3. Observed Behavior and Traps
1. **Zero Comparison Trap**:
   - `pytest.approx(expected, rel=1e-6, abs=1e-12)` calculates allowable tolerance as `max(rel * abs(expected), abs)`.
   - When `expected == 0.0`, relative tolerance scales to zero (`rel * 0.0 = 0.0`), meaning the comparison relies solely on `abs` (default `1e-12`).
   - Consequently, `1e-7 == pytest.approx(0.0)` evaluates to `False`, and setting `rel=0.5` has zero effect. To match near-zero floats, `abs=` must be explicitly specified (e.g. `pytest.approx(0.0, abs=1e-5)`).
   - How the wrong expectation fails: It fails loudly with an `AssertionError` in test suites when asserting a computed floating-point quantity equals `pytest.approx(0.0)`.

2. **Boolean Strictness**:
   - In Python, `isinstance(True, int)` is `True` and `1 == True` evaluates to `True`.
   - However, `1 == pytest.approx(True)` and `0 == pytest.approx(False)` evaluate to `False`. `pytest.approx` enforces exact type matching for boolean arguments to prevent accidental numeric coercion.

3. **Data Structure Restrictions**:
   - `pytest.approx` supports flat mappings (`dict`) and ordered 1D sequences (`list`, `tuple`), allowing cross-sequence comparison like `[1.0, 2.0] == pytest.approx((1.0, 2.0))`.
   - However, passing nested dictionaries (`pytest.approx({'a': {'b': 1.0}})`), nested sequences (`pytest.approx([[1.0, 2.0]])`), or unordered sets (`pytest.approx({1.0, 2.0})`) raises `TypeError`.

4. **NaN Comparison**:
   - `nan == pytest.approx(nan)` evaluates to `False` by default; matching `NaN` values requires explicitly passing `nan_ok=True`.

{"case":{"believed":"pytest.approx(0.0) matches small floating point numbers like 1e-7 using the default 1e-6 relative tolerance","caseId":"case:sha256:7dde344beb37859773558ec1a22bab3ea43cc1b696b47127722437b16d7112a1","contract":["pytest.approx(0.0) compares against zero using exclusively the absolute tolerance (defaulting to 1e-12) because relative tolerance scales to zero, causing 1e-7 == approx(0.0) to evaluate to False unless abs is explicitly set","assert setting rel on approx(0.0) has no effect on zero comparisons while abs adjusts the allowable delta","assert approx comparison against non-zero values uses relative tolerance scaled by the expected value","assert approx rejects boolean-to-integer equality coercion returning False for 1 == approx(True)","assert approx supports element-wise comparison between tuples and lists but rejects nested dictionaries and nested sequences with TypeError","assert approx requires nan_ok=True to match float nan values"],"goal":"Verify pytest.approx tolerance scaling around zero, boolean strictness, and structure restrictions","kind":"HOW","packages":["pkg:pypi/pytest@9.0.3"],"schemaVersion":1,"symbols":["pytest.approx"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pytest@9.0.3"],"schemaVersion":1,"symbols":["pytest.approx"],"verifierAdapter":"python@1"}

pytest==9.0.3
iniconfig==2.3.0
packaging==24.2
pluggy==1.6.0
Pygments==2.20.0
colorama==0.4.6
exceptiongroup==1.3.1
tomli==2.4.1

"""pytest.approx tolerance and type behavior demonstration."""

"""Demonstrates pytest.approx comparison semantics."""

from typing import Any, Optional
import pytest


def compare_zero(val: float, rel: Optional[float] = None, abs_tol: Optional[float] = None) -> bool:
    """Compare a value against approx(0.0) with optional tolerances."""
    kwargs = {}
    if rel is not None:
        kwargs["rel"] = rel
    if abs_tol is not None:
        kwargs["abs"] = abs_tol
    return val == pytest.approx(0.0, **kwargs)


def compare_value(
    actual: float,
    expected: float,
    rel: Optional[float] = None,
    abs_tol: Optional[float] = None,
) -> bool:
    """Compare two float values using pytest.approx."""
    kwargs = {}
    if rel is not None:
        kwargs["rel"] = rel
    if abs_tol is not None:
        kwargs["abs"] = abs_tol
    return actual == pytest.approx(expected, **kwargs)


def compare_structures(actual: Any, expected: Any) -> bool:
    """Compare complex or collection structures with pytest.approx."""
    return actual == pytest.approx(expected)

"""Contract proving pytest.approx tolerance scaling, boolean strictness, and structure restrictions."""

import os
import sys
import pytest

# Ensure local src directory is on sys.path using relative resolution
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from src.comparator import compare_structures, compare_value, compare_zero


def main():
    # 1. Zero comparison: approx(0.0) defaults to abs=1e-12 because rel * 0 = 0.
    # A value of 1e-7 is outside 1e-12 and thus fails to match approx(0.0).
    assert compare_zero(1e-7) is False, "1e-7 should not match approx(0.0) under default 1e-12 abs tolerance"
    assert compare_zero(1e-13) is True, "1e-13 is within 1e-12 abs tolerance and should match approx(0.0)"

    # Setting rel on approx(0.0) has no effect because rel * 0 = 0.
    assert compare_zero(1e-7, rel=0.5) is False, "rel tolerance has no effect when expected is 0.0"
    assert compare_zero(1e-7, rel=100.0) is False, "large rel tolerance still evaluates to 0 on 0.0"

    # Specifying abs explicitly sets allowable tolerance around zero.
    assert compare_zero(1e-7, abs_tol=1e-5) is True, "explicit abs tolerance permits 1e-7 deviation around 0.0"

    # 2. Non-zero comparison uses relative tolerance scaled by expected value.
    # Default rel=1e-6 on expected=100.0 allows tolerance = max(1e-6 * 100, 1e-12) = 1e-4.
    assert compare_value(100.00005, 100.0) is True, "deviation of 5e-5 is within 1e-4 allowable relative tolerance"
    assert compare_value(100.0002, 100.0) is False, "deviation of 2e-4 exceeds 1e-4 allowable relative tolerance"

    # 3. Boolean strictness: pytest.approx does not coerce booleans to ints.
    assert (1 == pytest.approx(True)) is False, "1 == approx(True) must return False (strict type check)"
    assert (0 == pytest.approx(False)) is False, "0 == approx(False) must return False (strict type check)"
    assert (pytest.approx(True) == 1) is False, "approx(True) == 1 must return False"
    assert (True == pytest.approx(True)) is True, "True == approx(True) matches exact bool"

    # 4. Sequences and type flexibility:
    # pytest.approx supports element-wise comparison between different sequence types (list vs tuple).
    assert compare_structures([1.0000001, 2.0], (1.0, 2.0)) is True, "list equals approx(tuple) element-wise"
    assert compare_structures((1.0000001, 2.0), [1.0, 2.0]) is True, "tuple equals approx(list) element-wise"
    assert compare_structures([1.0], [1.0, 2.0]) is False, "mismatched sequence lengths evaluate to False"

    # 5. Unsupported structures raise TypeError.
    try:
        pytest.approx({"a": {"b": 1.0}})
        assert False, "Nested dictionary should have raised TypeError"
    except TypeError as exc:
        assert "does not support nested dictionaries" in str(exc)

    try:
        pytest.approx([[1.0, 2.0]])
        assert False, "Nested sequence should have raised TypeError"
    except TypeError as exc:
        assert "does not support nested data structures" in str(exc)

    try:
        pytest.approx({1.0, 2.0})
        assert False, "Unordered set should have raised TypeError"
    except TypeError as exc:
        assert "only supports ordered sequences" in str(exc)

    # 6. Flat dicts with mixed types.
    actual_dict = {"metric": 1.0000001, "status": "ok", "count": 42}
    expected_dict = {"metric": 1.0, "status": "ok", "count": 42}
    assert compare_structures(actual_dict, expected_dict) is True, "flat dict with mixed types compares floats approximately and others exactly"

    mismatched_dict = {"metric": 1.0, "status": "failed", "count": 42}
    assert compare_structures(mismatched_dict, expected_dict) is False, "mismatched non-float value evaluates to False"

    # 7. NaN handling with nan_ok.
    nan_val = float("nan")
    assert (nan_val == pytest.approx(nan_val)) is False, "NaN != approx(NaN) by default"
    assert (nan_val == pytest.approx(nan_val, nan_ok=True)) is True, "NaN == approx(NaN, nan_ok=True) matches"
    assert ([1.0, nan_val] == pytest.approx([1.0, nan_val], nan_ok=True)) is True, "sequence with NaN matches when nan_ok=True"

    print("CONTRACT PASS: pytest.approx tolerance scaling, type invariance, and structure restrictions verified")


if __name__ == "__main__":
    main()