1143 lines
43 KiB
Python
1143 lines
43 KiB
Python
"""The implementation of pytest.approx()."""
|
|
|
|
# mypy: allow-untyped-defs
|
|
from __future__ import annotations
|
|
|
|
import abc
|
|
import builtins
|
|
from collections.abc import Collection
|
|
from collections.abc import Mapping
|
|
from collections.abc import Sequence
|
|
from collections.abc import Sized
|
|
from datetime import datetime
|
|
from datetime import timedelta
|
|
from decimal import Decimal
|
|
from decimal import FloatOperation
|
|
import math
|
|
from numbers import Complex
|
|
import pprint
|
|
import sys
|
|
from typing import Any
|
|
from typing import Generic
|
|
from typing import SupportsAbs
|
|
from typing import TYPE_CHECKING
|
|
from typing import TypeGuard
|
|
from typing import TypeVar
|
|
import warnings
|
|
|
|
from _pytest.warning_types import PytestApproxDecimalToleranceWarning
|
|
|
|
|
|
if TYPE_CHECKING:
|
|
from numpy import ndarray
|
|
else:
|
|
ndarray = object
|
|
|
|
|
|
def _max_diff(current: Any, candidate: Any) -> Any:
|
|
"""Track a running maximum without seeding it with a value of another type.
|
|
|
|
Seeding with ``-math.inf`` compares a float against whatever is being
|
|
accumulated. For Decimal that comparison is exact, but it signals
|
|
``decimal.FloatOperation`` when that trap is set, and the sequence variant
|
|
used to swallow the signal (``decimal.FloatOperation`` is a ``TypeError``
|
|
subclass) and report ``-inf`` as the difference.
|
|
"""
|
|
return candidate if current is None else max(current, candidate)
|
|
|
|
|
|
def _vetted_diffs(
|
|
max_abs_diff: Any, max_rel_diff: Any, rel_diff_is_infinite: bool
|
|
) -> tuple[Any, Any]:
|
|
"""Turn the accumulators into the values shown in the failure message.
|
|
|
|
``-math.inf`` means "no difference could be computed at all", which happens
|
|
when every mismatched element is a non-number (#13012).
|
|
"""
|
|
if rel_diff_is_infinite:
|
|
max_rel_diff = math.inf
|
|
return (
|
|
-math.inf if max_abs_diff is None else max_abs_diff,
|
|
-math.inf if max_rel_diff is None else max_rel_diff,
|
|
)
|
|
|
|
|
|
def _compare_approx(
|
|
full_object: object,
|
|
message_data: Sequence[tuple[str, str, str]],
|
|
number_of_elements: int,
|
|
different_ids: Sequence[object],
|
|
max_abs_diff: float,
|
|
max_rel_diff: float,
|
|
) -> list[str]:
|
|
message_list = list(message_data)
|
|
message_list.insert(0, ("Index", "Obtained", "Expected"))
|
|
max_sizes = [0, 0, 0]
|
|
for index, obtained, expected in message_list:
|
|
max_sizes[0] = max(max_sizes[0], len(index))
|
|
max_sizes[1] = max(max_sizes[1], len(obtained))
|
|
max_sizes[2] = max(max_sizes[2], len(expected))
|
|
explanation = [
|
|
f"comparison failed. Mismatched elements: {len(different_ids)} / {number_of_elements}:",
|
|
f"Max absolute difference: {max_abs_diff}",
|
|
f"Max relative difference: {max_rel_diff}",
|
|
] + [
|
|
f"{indexes:<{max_sizes[0]}} | {obtained:<{max_sizes[1]}} | {expected:<{max_sizes[2]}}"
|
|
for indexes, obtained, expected in message_list
|
|
]
|
|
return explanation
|
|
|
|
|
|
T = TypeVar("T")
|
|
ExpectedT = TypeVar("ExpectedT", covariant=True)
|
|
|
|
|
|
class Approx(abc.ABC, Generic[ExpectedT]):
|
|
"""The return type of :func:`pytest.approx`.
|
|
|
|
``Approx`` objects support (approximate) equality comparisons and ``repr``,
|
|
and can also be used with ``isinstance(..., pytest.Approx)``.
|
|
|
|
.. versionadded:: 9.2
|
|
"""
|
|
|
|
__module__ = "pytest"
|
|
|
|
# Tell numpy to use our `__eq__` operator instead of its.
|
|
__array_ufunc__ = None
|
|
__array_priority__ = 100
|
|
|
|
def __init__(
|
|
self,
|
|
expected: ExpectedT,
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
nan_ok: bool,
|
|
) -> None:
|
|
#: The expected value passed.
|
|
self.expected = expected
|
|
#: The relative tolerance.
|
|
self.rel = rel
|
|
#: The absolute tolerance.
|
|
self.abs = abs
|
|
#: Whether NaNs compare equal to NaN.
|
|
self.nan_ok = nan_ok
|
|
|
|
@abc.abstractmethod
|
|
def __repr__(self) -> str:
|
|
raise NotImplementedError
|
|
|
|
def _repr_compare(self, other_side) -> list[str]:
|
|
return [
|
|
"comparison failed",
|
|
f"Obtained: {other_side}",
|
|
f"Expected: {self}",
|
|
]
|
|
|
|
def __eq__(self, actual) -> bool:
|
|
return all(
|
|
a == self._approx_scalar(x) for a, x in self._yield_comparisons(actual)
|
|
)
|
|
|
|
def __bool__(self):
|
|
__tracebackhide__ = True
|
|
raise AssertionError(
|
|
"approx() is not supported in a boolean context.\nDid you mean: `assert a == approx(b)`?"
|
|
)
|
|
|
|
# Ignore type because of https://github.com/python/mypy/issues/4266.
|
|
__hash__ = None # type: ignore
|
|
|
|
def _approx_scalar(self, x) -> ApproxScalar[Any] | ApproxTimedelta:
|
|
if isinstance(x, Decimal):
|
|
return ApproxDecimal(x, rel=self.rel, abs=self.abs, nan_ok=self.nan_ok)
|
|
if isinstance(x, (datetime, timedelta)):
|
|
return ApproxTimedelta(x, rel=self.rel, abs=self.abs, nan_ok=self.nan_ok)
|
|
return ApproxScalar(x, rel=self.rel, abs=self.abs, nan_ok=self.nan_ok)
|
|
|
|
def _yield_comparisons(self, actual: object):
|
|
"""Yield all the pairs of numbers to be compared.
|
|
|
|
This is used to implement the `__eq__` method.
|
|
"""
|
|
raise NotImplementedError
|
|
|
|
|
|
def _recursive_sequence_map(f, x):
|
|
"""Recursively map a function over a sequence of arbitrary depth"""
|
|
if isinstance(x, list | tuple):
|
|
seq_type = type(x)
|
|
return seq_type(_recursive_sequence_map(f, xi) for xi in x)
|
|
elif _is_sequence_like(x):
|
|
return [_recursive_sequence_map(f, xi) for xi in x]
|
|
else:
|
|
return f(x)
|
|
|
|
|
|
class ApproxNumpy(Approx[ndarray]):
|
|
"""Perform approximate comparisons where the expected value is numpy array."""
|
|
|
|
def __repr__(self) -> str:
|
|
list_scalars = _recursive_sequence_map(
|
|
self._approx_scalar, self.expected.tolist()
|
|
)
|
|
return f"approx({list_scalars!r})"
|
|
|
|
def _repr_compare(self, other_side: ndarray | list[Any]) -> list[str]:
|
|
import itertools
|
|
|
|
def get_value_from_nested_list(
|
|
nested_list: list[Any], nd_index: tuple[Any, ...]
|
|
) -> Any:
|
|
"""
|
|
Helper function to get the value out of a nested list, given an n-dimensional index.
|
|
This mimics numpy's indexing, but for raw nested python lists.
|
|
"""
|
|
value: Any = nested_list
|
|
for i in nd_index:
|
|
value = value[i]
|
|
return value
|
|
|
|
np_array_shape = self.expected.shape
|
|
approx_side_as_seq = _recursive_sequence_map(
|
|
self._approx_scalar, self.expected.tolist()
|
|
)
|
|
|
|
# convert other_side to numpy array to ensure shape attribute is available
|
|
other_side_as_array = _as_numpy_array(other_side)
|
|
assert other_side_as_array is not None
|
|
|
|
if np_array_shape != other_side_as_array.shape:
|
|
return [
|
|
"Impossible to compare arrays with different shapes.",
|
|
f"Shapes: {np_array_shape} and {other_side_as_array.shape}",
|
|
]
|
|
|
|
number_of_elements = self.expected.size
|
|
max_abs_diff: Any = None
|
|
max_rel_diff: Any = None
|
|
rel_diff_is_infinite = False
|
|
different_ids = []
|
|
for index in itertools.product(*(range(i) for i in np_array_shape)):
|
|
approx_value = get_value_from_nested_list(approx_side_as_seq, index)
|
|
other_value = get_value_from_nested_list(other_side_as_array, index)
|
|
if approx_value != other_value:
|
|
abs_diff = abs(approx_value.expected - other_value)
|
|
max_abs_diff = _max_diff(max_abs_diff, abs_diff)
|
|
if other_value == 0:
|
|
rel_diff_is_infinite = True
|
|
else:
|
|
max_rel_diff = _max_diff(max_rel_diff, abs_diff / abs(other_value))
|
|
different_ids.append(index)
|
|
|
|
max_abs_diff, max_rel_diff = _vetted_diffs(
|
|
max_abs_diff, max_rel_diff, rel_diff_is_infinite
|
|
)
|
|
|
|
message_data = [
|
|
(
|
|
str(index),
|
|
str(get_value_from_nested_list(other_side_as_array, index)),
|
|
str(get_value_from_nested_list(approx_side_as_seq, index)),
|
|
)
|
|
for index in different_ids
|
|
]
|
|
return _compare_approx(
|
|
self.expected,
|
|
message_data,
|
|
number_of_elements,
|
|
different_ids,
|
|
max_abs_diff,
|
|
max_rel_diff,
|
|
)
|
|
|
|
def __eq__(self, actual) -> bool:
|
|
import numpy as np
|
|
|
|
# self.expected is supposed to always be an array here.
|
|
|
|
if not np.isscalar(actual):
|
|
try:
|
|
actual = np.asarray(actual)
|
|
except Exception as e:
|
|
raise TypeError(f"cannot compare '{actual}' to numpy.ndarray") from e
|
|
|
|
if not np.isscalar(actual) and actual.shape != self.expected.shape:
|
|
return False
|
|
|
|
return super().__eq__(actual)
|
|
|
|
def _yield_comparisons(self, actual):
|
|
import numpy as np
|
|
|
|
# `actual` can either be a numpy array or a scalar, it is treated in
|
|
# `__eq__` before being passed to `ApproxBase.__eq__`, which is the
|
|
# only method that calls this one.
|
|
|
|
if np.isscalar(actual):
|
|
for i in np.ndindex(self.expected.shape):
|
|
yield actual, _unbox_numpy_scalar(self.expected[i])
|
|
else:
|
|
for i in np.ndindex(self.expected.shape):
|
|
yield (
|
|
_unbox_numpy_scalar(actual[i]),
|
|
_unbox_numpy_scalar(self.expected[i]),
|
|
)
|
|
|
|
|
|
class ApproxMapping(Approx[Mapping[Any, Any]]):
|
|
"""Perform approximate comparisons where the expected value is a mapping
|
|
with numeric values (the keys can be anything)."""
|
|
|
|
def __init__(
|
|
self,
|
|
expected: Mapping[Any, Any],
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
nan_ok: bool,
|
|
) -> None:
|
|
__tracebackhide__ = True
|
|
|
|
for key, value in expected.items():
|
|
if _is_nested_container(value):
|
|
msg = "pytest.approx() does not support nested dictionaries: key={!r} value={!r}\n full mapping={}"
|
|
raise TypeError(msg.format(key, value, pprint.pformat(expected)))
|
|
|
|
super().__init__(expected, rel=rel, abs=abs, nan_ok=nan_ok)
|
|
|
|
def __repr__(self) -> str:
|
|
return f"approx({ ({k: self._approx_scalar(v) for k, v in self.expected.items()})!r})"
|
|
|
|
def _repr_compare(self, other_side: Mapping[object, float]) -> list[str]:
|
|
|
|
if len(self.expected) != len(other_side):
|
|
return [
|
|
"Impossible to compare mappings with different sizes.",
|
|
f"Lengths: {len(self.expected)} and {len(other_side)}",
|
|
]
|
|
|
|
if self.expected.keys() != other_side.keys():
|
|
return [
|
|
"comparison failed.",
|
|
f"Mappings has different keys: expected {self.expected.keys()} but got {other_side.keys()}",
|
|
]
|
|
|
|
approx_side_as_map = {
|
|
k: self._approx_scalar(v) for k, v in self.expected.items()
|
|
}
|
|
|
|
number_of_elements = len(approx_side_as_map)
|
|
max_abs_diff: Any = None
|
|
max_rel_diff: Any = None
|
|
rel_diff_is_infinite = False
|
|
different_ids = []
|
|
for approx_key, approx_value in approx_side_as_map.items():
|
|
other_value = other_side[approx_key]
|
|
if approx_value != other_value:
|
|
if approx_value.expected is not None and other_value is not None:
|
|
try:
|
|
max_abs_diff = _max_diff(
|
|
max_abs_diff,
|
|
# TODO: The type error here seems correct.
|
|
abs(approx_value.expected - other_value), # type: ignore[operator]
|
|
)
|
|
if approx_value.expected == 0:
|
|
rel_diff_is_infinite = True
|
|
else:
|
|
max_rel_diff = _max_diff(
|
|
max_rel_diff,
|
|
abs(
|
|
# TODO: The type error here seems correct.
|
|
(approx_value.expected - other_value) # type: ignore[operator]
|
|
/ approx_value.expected
|
|
),
|
|
)
|
|
except ZeroDivisionError:
|
|
pass
|
|
different_ids.append(approx_key)
|
|
|
|
max_abs_diff, max_rel_diff = _vetted_diffs(
|
|
max_abs_diff, max_rel_diff, rel_diff_is_infinite
|
|
)
|
|
|
|
message_data = [
|
|
(str(key), str(other_side[key]), str(approx_side_as_map[key]))
|
|
for key in different_ids
|
|
]
|
|
|
|
return _compare_approx(
|
|
self.expected,
|
|
message_data,
|
|
number_of_elements,
|
|
different_ids,
|
|
max_abs_diff,
|
|
max_rel_diff,
|
|
)
|
|
|
|
def __eq__(self, actual) -> bool:
|
|
try:
|
|
if set(actual.keys()) != set(self.expected.keys()):
|
|
return False
|
|
except AttributeError:
|
|
return False
|
|
|
|
return super().__eq__(actual)
|
|
|
|
def _yield_comparisons(self, actual):
|
|
for k in self.expected:
|
|
yield actual[k], self.expected[k]
|
|
|
|
|
|
class ApproxSequenceLike(Approx[Sequence[Any]]):
|
|
"""Perform approximate comparisons where the expected value is a sequence of numbers."""
|
|
|
|
def __init__(
|
|
self,
|
|
expected: Sequence[Any],
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
nan_ok: bool,
|
|
) -> None:
|
|
__tracebackhide__ = True
|
|
|
|
for index, x in enumerate(expected):
|
|
if _is_nested_container(x):
|
|
msg = "pytest.approx() does not support nested data structures: {!r} at index {}\n full sequence: {}"
|
|
raise TypeError(msg.format(x, index, pprint.pformat(expected)))
|
|
|
|
super().__init__(expected, rel=rel, abs=abs, nan_ok=nan_ok)
|
|
|
|
def __repr__(self) -> str:
|
|
seq_type = type(self.expected)
|
|
if seq_type not in (tuple, list):
|
|
seq_type = list
|
|
return f"approx({seq_type(self._approx_scalar(x) for x in self.expected)!r})"
|
|
|
|
def _repr_compare(self, other_side: Sequence[float]) -> list[str]:
|
|
|
|
if len(self.expected) != len(other_side):
|
|
return [
|
|
"Impossible to compare lists with different sizes.",
|
|
f"Lengths: {len(self.expected)} and {len(other_side)}",
|
|
]
|
|
|
|
approx_side_as_map = _recursive_sequence_map(self._approx_scalar, self.expected)
|
|
|
|
number_of_elements = len(approx_side_as_map)
|
|
max_abs_diff: Any = None
|
|
max_rel_diff: Any = None
|
|
rel_diff_is_infinite = False
|
|
different_ids = []
|
|
for i, (approx_value, other_value) in enumerate(
|
|
zip(approx_side_as_map, other_side, strict=True)
|
|
):
|
|
if approx_value != other_value:
|
|
try:
|
|
abs_diff = abs(approx_value.expected - other_value)
|
|
max_abs_diff = _max_diff(max_abs_diff, abs_diff)
|
|
# decimal.FloatOperation subclasses TypeError, so it would be
|
|
# caught below and reported as a missing difference.
|
|
except FloatOperation:
|
|
raise
|
|
# Ignore non-numbers for the diff calculations (#13012).
|
|
except TypeError:
|
|
pass
|
|
else:
|
|
if other_value == 0:
|
|
rel_diff_is_infinite = True
|
|
else:
|
|
max_rel_diff = _max_diff(
|
|
max_rel_diff, abs_diff / abs(other_value)
|
|
)
|
|
different_ids.append(i)
|
|
|
|
max_abs_diff, max_rel_diff = _vetted_diffs(
|
|
max_abs_diff, max_rel_diff, rel_diff_is_infinite
|
|
)
|
|
message_data = [
|
|
(str(i), str(other_side[i]), str(approx_side_as_map[i]))
|
|
for i in different_ids
|
|
]
|
|
|
|
return _compare_approx(
|
|
self.expected,
|
|
message_data,
|
|
number_of_elements,
|
|
different_ids,
|
|
max_abs_diff,
|
|
max_rel_diff,
|
|
)
|
|
|
|
def __eq__(self, actual) -> bool:
|
|
try:
|
|
if len(actual) != len(self.expected):
|
|
return False
|
|
except TypeError:
|
|
return False
|
|
return super().__eq__(actual)
|
|
|
|
def _yield_comparisons(self, actual):
|
|
return zip(actual, self.expected, strict=True)
|
|
|
|
|
|
class ApproxScalar(Approx[ExpectedT]):
|
|
"""Perform approximate comparisons where the expected value is a single number."""
|
|
|
|
# Using Real should be better than this Union, but not possible yet:
|
|
# https://github.com/python/typeshed/pull/3108
|
|
DEFAULT_ABSOLUTE_TOLERANCE: float | Decimal = 1e-12
|
|
DEFAULT_RELATIVE_TOLERANCE: float | Decimal = 1e-6
|
|
rel: float | Decimal | None
|
|
abs: float | Decimal | None
|
|
|
|
def __init__(
|
|
self,
|
|
expected: ExpectedT,
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
nan_ok: bool,
|
|
) -> None:
|
|
__tracebackhide__ = True
|
|
if rel is not None:
|
|
if not isinstance(rel, (int, float, Decimal)):
|
|
raise TypeError(
|
|
f"relative tolerance for a scalar value must be an int, float or Decimal, "
|
|
f"got {type(rel).__name__}"
|
|
)
|
|
if not isinstance(expected, SupportsAbs):
|
|
raise TypeError(
|
|
f"expected value must support abs(...) when relative tolerance is used, "
|
|
f"got {type(expected).__name__}"
|
|
)
|
|
if abs is not None and not isinstance(abs, (int, float, Decimal)):
|
|
raise TypeError(
|
|
f"absolute tolerance for a scalar value must be an int, float or Decimal, "
|
|
f"got {type(abs).__name__}"
|
|
)
|
|
super().__init__(expected, rel=rel, abs=abs, nan_ok=nan_ok)
|
|
|
|
def __repr__(self) -> str:
|
|
"""Return a string communicating both the expected value and the
|
|
tolerance for the comparison being made.
|
|
|
|
For example, ``1.0 ± 1e-6``, ``(3+4j) ± 5e-6 ∠ ±180°``.
|
|
"""
|
|
# Don't show a tolerance for values that aren't compared using
|
|
# tolerances, i.e. non-numerics and infinities. Need to call abs to
|
|
# handle complex numbers, e.g. (inf + 1j).
|
|
if (
|
|
_is_bool(self.expected)
|
|
or (not isinstance(self.expected, Complex | Decimal))
|
|
or _is_inf(abs(self.expected))
|
|
):
|
|
return str(self.expected)
|
|
|
|
# If a sensible tolerance can't be calculated, self.tolerance will
|
|
# raise a ValueError. In this case, display '???'.
|
|
try:
|
|
if isinstance(self.tolerance, Decimal):
|
|
# Never let a Decimal meet a float literal: comparing against
|
|
# 1e-3/1e3 signals decimal.FloatOperation when that trap is set
|
|
# (#13530). Scientific notation is also the only readable choice
|
|
# here, because a tolerance derived from a float carries its
|
|
# full exact binary expansion (dozens of digits).
|
|
vetted_tolerance = f"{self.tolerance:.1e}"
|
|
elif 1e-3 <= self.tolerance < 1e3:
|
|
vetted_tolerance = f"{self.tolerance:n}"
|
|
else:
|
|
vetted_tolerance = f"{self.tolerance:.1e}"
|
|
|
|
if (
|
|
isinstance(self.expected, Complex)
|
|
and self.expected.imag
|
|
and not _is_inf(self.tolerance)
|
|
):
|
|
vetted_tolerance += " ∠ ±180°"
|
|
except ValueError:
|
|
vetted_tolerance = "???"
|
|
|
|
return f"{self.expected} ± {vetted_tolerance}"
|
|
|
|
def __eq__(self, actual) -> bool:
|
|
"""Return whether the given value is equal to the expected value
|
|
within the pre-specified tolerance."""
|
|
asarray = _as_numpy_array(actual)
|
|
if asarray is not None:
|
|
# Call ``__eq__()`` manually to prevent infinite-recursion with
|
|
# numpy<1.13. See #3748.
|
|
return all(self.__eq__(a) for a in asarray.flat)
|
|
|
|
# Short-circuit exact equality, except for bool and np.bool_
|
|
if _is_bool(self.expected) and not _is_bool(actual):
|
|
return False
|
|
elif actual == self.expected:
|
|
return True
|
|
|
|
# If either type is non-numeric, fall back to strict equality.
|
|
# NB: we need Complex, rather than just Number, to ensure that __abs__,
|
|
# __sub__, and __float__ are defined. Also, consider bool to be
|
|
# non-numeric, even though it has the required arithmetic.
|
|
if _is_bool(self.expected) or not (
|
|
isinstance(self.expected, Complex | Decimal)
|
|
and isinstance(actual, Complex | Decimal)
|
|
):
|
|
return False
|
|
|
|
# Allow the user to control whether NaNs are considered equal to each
|
|
# other or not. The abs() calls are for compatibility with complex
|
|
# numbers.
|
|
if _is_nan(abs(self.expected)):
|
|
return self.nan_ok and _is_nan(abs(actual))
|
|
|
|
# Infinity shouldn't be approximately equal to anything but itself, but
|
|
# if there's a relative tolerance, it will be infinite and infinity
|
|
# will seem approximately equal to everything. The equal-to-itself
|
|
# case would have been short circuited above, so here we can just
|
|
# return false if the expected value is infinite. The abs() call is
|
|
# for compatibility with complex numbers.
|
|
if _is_inf(abs(self.expected)):
|
|
return False
|
|
|
|
# Return true if the two numbers are within the tolerance.
|
|
result: bool = abs(self.expected - actual) <= self.tolerance
|
|
return result
|
|
|
|
__hash__ = None
|
|
|
|
@property
|
|
def tolerance(self):
|
|
"""Return the tolerance for the comparison.
|
|
|
|
This could be either an absolute tolerance or a relative tolerance,
|
|
depending on what the user specified or which would be larger.
|
|
"""
|
|
# Figure out what the absolute tolerance should be. ``self.abs`` is
|
|
# either None or a value specified by the user.
|
|
absolute_tolerance = (
|
|
self.abs if self.abs is not None else self.DEFAULT_ABSOLUTE_TOLERANCE
|
|
)
|
|
|
|
if _is_nan(absolute_tolerance):
|
|
raise ValueError("absolute tolerance can't be NaN.")
|
|
if absolute_tolerance < 0:
|
|
raise ValueError(
|
|
f"absolute tolerance can't be negative: {absolute_tolerance}"
|
|
)
|
|
|
|
# If the user specified an absolute tolerance but not a relative one,
|
|
# just return the absolute tolerance.
|
|
if self.rel is None:
|
|
if self.abs is not None:
|
|
return absolute_tolerance
|
|
|
|
# Figure out what the relative tolerance should be. ``self.rel`` is
|
|
# either None or a value specified by the user. This is done after
|
|
# we've made sure the user didn't ask for an absolute tolerance only,
|
|
# because we don't want to raise errors about the relative tolerance if
|
|
# we aren't even going to use it.
|
|
rel = self.rel if self.rel is not None else self.DEFAULT_RELATIVE_TOLERANCE
|
|
# expected is SupportAbs, checked in __init__.
|
|
# The typing here is not exact...
|
|
abs_expected: ExpectedT = abs(self.expected) # type: ignore[arg-type]
|
|
relative_tolerance: float | Decimal = rel * abs_expected # type: ignore[operator]
|
|
|
|
if _is_nan(relative_tolerance):
|
|
raise ValueError("relative tolerance can't be NaN.")
|
|
if relative_tolerance < 0:
|
|
raise ValueError(
|
|
f"relative tolerance can't be negative: {relative_tolerance}"
|
|
)
|
|
|
|
# Return the larger of the relative and absolute tolerances.
|
|
return max(relative_tolerance, absolute_tolerance)
|
|
|
|
|
|
class ApproxDecimal(ApproxScalar[Decimal]):
|
|
"""Perform approximate comparisons where the expected value is a Decimal."""
|
|
|
|
DEFAULT_ABSOLUTE_TOLERANCE = Decimal("1e-12")
|
|
DEFAULT_RELATIVE_TOLERANCE = Decimal("1e-6")
|
|
rel: Decimal | None
|
|
abs: Decimal | None
|
|
|
|
def __init__(
|
|
self,
|
|
expected: Decimal,
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
nan_ok: bool,
|
|
) -> None:
|
|
if isinstance(rel, (float, int)):
|
|
rel_: Decimal | timedelta | None = Decimal.from_float(rel)
|
|
else:
|
|
rel_ = rel
|
|
if isinstance(abs, (float, int)):
|
|
abs_: Decimal | timedelta | None = Decimal.from_float(abs)
|
|
else:
|
|
abs_ = abs
|
|
super().__init__(expected, rel_, abs_, nan_ok)
|
|
|
|
|
|
class ApproxTimedelta(Approx[datetime | timedelta]):
|
|
"""Perform approximate comparisons where the expected value is a
|
|
datetime or timedelta.
|
|
|
|
Requires an explicit tolerance as a timedelta for abs, or a float for rel.
|
|
Relative tolerance is not supported for datetime comparisons.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
expected: datetime | timedelta,
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
nan_ok: bool,
|
|
) -> None:
|
|
__tracebackhide__ = True
|
|
if isinstance(expected, datetime) and rel is not None:
|
|
raise TypeError(
|
|
"pytest.approx() does not support relative tolerance for "
|
|
"datetime comparisons. Use abs=timedelta(...) instead."
|
|
)
|
|
if nan_ok:
|
|
raise TypeError(
|
|
"pytest.approx() does not support nan_ok for "
|
|
"datetime/timedelta comparisons."
|
|
)
|
|
if abs is None and rel is None:
|
|
raise TypeError(
|
|
"pytest.approx() requires an explicit tolerance for "
|
|
"datetime/timedelta comparisons: "
|
|
"e.g. approx(expected, abs=timedelta(seconds=1)) "
|
|
"or approx(expected, rel=0.01)"
|
|
)
|
|
if abs is not None and not isinstance(abs, timedelta):
|
|
raise TypeError(
|
|
f"absolute tolerance for datetime/timedelta must be a "
|
|
f"timedelta, got {type(abs).__name__}"
|
|
)
|
|
if abs is not None and abs < timedelta(0):
|
|
raise ValueError(f"absolute tolerance can't be negative: {abs}")
|
|
if rel is not None:
|
|
if not isinstance(rel, (int, float)):
|
|
raise TypeError(
|
|
f"relative tolerance for timedelta must be a "
|
|
f"number, got {type(rel).__name__}"
|
|
)
|
|
if rel < 0:
|
|
raise ValueError(f"relative tolerance can't be negative: {rel}")
|
|
if math.isnan(rel):
|
|
raise ValueError("relative tolerance can't be NaN.")
|
|
if math.isinf(rel):
|
|
raise ValueError("relative tolerance can't be infinite.")
|
|
# Compute the effective tolerance. abs_tolerance is a timedelta, rel * expected
|
|
# gives a timedelta (timedelta * float works in Python).
|
|
abs_tolerance = abs
|
|
if rel is None:
|
|
rel_tolerance = None
|
|
else:
|
|
# Checked above.
|
|
assert not isinstance(expected, datetime)
|
|
rel_tolerance = rel * builtins.abs(expected)
|
|
if abs_tolerance is not None and rel_tolerance is not None:
|
|
tolerance: timedelta | None = max(abs_tolerance, rel_tolerance)
|
|
else:
|
|
tolerance = abs_tolerance if abs_tolerance is not None else rel_tolerance
|
|
super().__init__(expected, rel=rel, abs=tolerance, nan_ok=False)
|
|
|
|
def __repr__(self) -> str:
|
|
return f"{self.expected} ± {self.abs}"
|
|
|
|
def __eq__(self, actual) -> bool:
|
|
try:
|
|
return bool(builtins.abs(self.expected - actual) <= self.abs)
|
|
except (TypeError, OverflowError):
|
|
return False
|
|
|
|
def _yield_comparisons(self, actual: object):
|
|
yield actual, self.expected
|
|
|
|
def _repr_compare(self, other_side: Any) -> list[str]:
|
|
try:
|
|
abs_diff = builtins.abs(self.expected - other_side)
|
|
except (TypeError, OverflowError):
|
|
abs_diff = "N/A"
|
|
return [
|
|
"comparison failed",
|
|
f"Obtained: {other_side}",
|
|
f"Expected: {self.expected} ± {self.abs}",
|
|
f"Absolute difference: {abs_diff}",
|
|
f"Tolerance: {self.abs}",
|
|
]
|
|
|
|
|
|
def approx(
|
|
expected: T,
|
|
rel: float | Decimal | timedelta | None = None,
|
|
abs: float | Decimal | timedelta | None = None,
|
|
nan_ok: bool = False,
|
|
) -> Approx[T]:
|
|
"""Assert that two numbers (or two ordered sequences of numbers) are equal to each other
|
|
within some tolerance.
|
|
|
|
Due to the :doc:`python:tutorial/floatingpoint`, numbers that we
|
|
would intuitively expect to be equal are not always so::
|
|
|
|
>>> 0.1 + 0.2 == 0.3
|
|
False
|
|
|
|
This problem is commonly encountered when writing tests, e.g. when making
|
|
sure that floating-point values are what you expect them to be. One way to
|
|
deal with this problem is to assert that two floating-point numbers are
|
|
equal to within some appropriate tolerance::
|
|
|
|
>>> abs((0.1 + 0.2) - 0.3) < 1e-6
|
|
True
|
|
|
|
However, comparisons like this are tedious to write and difficult to
|
|
understand. Furthermore, absolute comparisons like the one above are
|
|
usually discouraged because there's no tolerance that works well for all
|
|
situations. ``1e-6`` is good for numbers around ``1``, but too small for
|
|
very big numbers and too big for very small ones. It's better to express
|
|
the tolerance as a fraction of the expected value, but relative comparisons
|
|
like that are even more difficult to write correctly and concisely.
|
|
|
|
The ``approx`` class performs floating-point comparisons using a syntax
|
|
that's as intuitive as possible::
|
|
|
|
>>> from pytest import approx
|
|
>>> 0.1 + 0.2 == approx(0.3)
|
|
True
|
|
|
|
The same syntax also works for ordered sequences of numbers::
|
|
|
|
>>> (0.1 + 0.2, 0.2 + 0.4) == approx((0.3, 0.6))
|
|
True
|
|
|
|
``numpy`` arrays::
|
|
|
|
>>> import numpy as np # doctest: +SKIP
|
|
>>> np.array([0.1, 0.2]) + np.array([0.2, 0.4]) == approx(np.array([0.3, 0.6])) # doctest: +SKIP
|
|
True
|
|
|
|
And for a ``numpy`` array against a scalar::
|
|
|
|
>>> import numpy as np # doctest: +SKIP
|
|
>>> np.array([0.1, 0.2]) + np.array([0.2, 0.1]) == approx(0.3) # doctest: +SKIP
|
|
True
|
|
|
|
Only ordered sequences are supported, because ``approx`` needs
|
|
to infer the relative position of the sequences without ambiguity. This means
|
|
``sets`` and other unordered sequences are not supported.
|
|
|
|
Finally, dictionary *values* can also be compared::
|
|
|
|
>>> {'a': 0.1 + 0.2, 'b': 0.2 + 0.4} == approx({'a': 0.3, 'b': 0.6})
|
|
True
|
|
|
|
The comparison will be true if both mappings have the same keys and their
|
|
respective values match the expected tolerances.
|
|
|
|
**Tolerances**
|
|
|
|
By default, ``approx`` considers numbers within a relative tolerance of
|
|
``1e-6`` (i.e. one part in a million) of its expected value to be equal.
|
|
This treatment would lead to surprising results if the expected value was
|
|
``0.0``, because nothing but ``0.0`` itself is relatively close to ``0.0``.
|
|
To handle this case less surprisingly, ``approx`` also considers numbers
|
|
within an absolute tolerance of ``1e-12`` of its expected value to be
|
|
equal. Infinity and NaN are special cases. Infinity is only considered
|
|
equal to itself, regardless of the relative tolerance. NaN is not
|
|
considered equal to anything by default, but you can make it be equal to
|
|
itself by setting the ``nan_ok`` argument to True. (This is meant to
|
|
facilitate comparing arrays that use NaN to mean "no data".)
|
|
|
|
Both the relative and absolute tolerances can be changed by passing
|
|
arguments to the ``approx`` constructor::
|
|
|
|
>>> 1.0001 == approx(1)
|
|
False
|
|
>>> 1.0001 == approx(1, rel=1e-3)
|
|
True
|
|
>>> 1.0001 == approx(1, abs=1e-3)
|
|
True
|
|
|
|
If you specify ``abs`` but not ``rel``, the comparison will not consider
|
|
the relative tolerance at all. In other words, two numbers that are within
|
|
the default relative tolerance of ``1e-6`` will still be considered unequal
|
|
if they exceed the specified absolute tolerance. If you specify both
|
|
``abs`` and ``rel``, the numbers will be considered equal if either
|
|
tolerance is met::
|
|
|
|
>>> 1 + 1e-8 == approx(1)
|
|
True
|
|
>>> 1 + 1e-8 == approx(1, abs=1e-12)
|
|
False
|
|
>>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)
|
|
True
|
|
|
|
**Non-numeric types**
|
|
|
|
You can also use ``approx`` to compare non-numeric types, or dicts and
|
|
sequences containing non-numeric types, in which case it falls back to
|
|
strict equality. This can be useful for comparing dicts and sequences that
|
|
can contain optional values::
|
|
|
|
>>> {"required": 1.0000005, "optional": None} == approx({"required": 1, "optional": None})
|
|
True
|
|
>>> [None, 1.0000005] == approx([None,1])
|
|
True
|
|
>>> ["foo", 1.0000005] == approx([None,1])
|
|
False
|
|
|
|
**datetime and timedelta**
|
|
|
|
You can also use ``approx`` to compare :class:`~datetime.datetime` and
|
|
:class:`~datetime.timedelta` objects by specifying an absolute tolerance
|
|
as a :class:`~datetime.timedelta`::
|
|
|
|
>>> from datetime import datetime, timedelta
|
|
>>> dt1 = datetime(2024, 1, 1, 12, 0, 0)
|
|
>>> dt2 = datetime(2024, 1, 1, 12, 0, 0, 500000)
|
|
>>> dt1 == approx(dt2, abs=timedelta(seconds=1))
|
|
True
|
|
|
|
Note that ``rel`` is not supported for datetime comparisons.
|
|
For timedelta comparisons, ``rel`` is a number (not a timedelta) that
|
|
represents a relative tolerance -- a fraction of the expected value.
|
|
``abs`` must be a ``timedelta`` object in both cases.
|
|
|
|
.. versionadded:: 8.4
|
|
|
|
If you're thinking about using ``approx``, then you might want to know how
|
|
it compares to other good ways of comparing floating-point numbers. All of
|
|
these algorithms are based on relative and absolute tolerances and should
|
|
agree for the most part, but they do have meaningful differences:
|
|
|
|
- ``math.isclose(a, b, rel_tol=1e-9, abs_tol=0.0)``: True if the relative
|
|
tolerance is met w.r.t. either ``a`` or ``b`` or if the absolute
|
|
tolerance is met. Because the relative tolerance is calculated w.r.t.
|
|
both ``a`` and ``b``, this test is symmetric (i.e. neither ``a`` nor
|
|
``b`` is a "reference value"). You have to specify an absolute tolerance
|
|
if you want to compare to ``0.0`` because there is no tolerance by
|
|
default. More information: :py:func:`math.isclose`.
|
|
|
|
- ``numpy.isclose(a, b, rtol=1e-5, atol=1e-8)``: True if the difference
|
|
between ``a`` and ``b`` is less that the sum of the relative tolerance
|
|
w.r.t. ``b`` and the absolute tolerance. Because the relative tolerance
|
|
is only calculated w.r.t. ``b``, this test is asymmetric and you can
|
|
think of ``b`` as the reference value. Support for comparing sequences
|
|
is provided by :py:func:`numpy.allclose`. More information:
|
|
:std:doc:`numpy:reference/generated/numpy.isclose`.
|
|
|
|
- ``unittest.TestCase.assertAlmostEqual(a, b)``: True if ``a`` and ``b``
|
|
are within an absolute tolerance of ``1e-7``. No relative tolerance is
|
|
considered , so this function is not appropriate for very large or very
|
|
small numbers. Also, it's only available in subclasses of ``unittest.TestCase``
|
|
and it's ugly because it doesn't follow PEP8. More information:
|
|
:py:meth:`unittest.TestCase.assertAlmostEqual`.
|
|
|
|
- ``a == pytest.approx(b, rel=1e-6, abs=1e-12)``: True if the relative
|
|
tolerance is met w.r.t. ``b`` or if the absolute tolerance is met.
|
|
Because the relative tolerance is only calculated w.r.t. ``b``, this test
|
|
is asymmetric and you can think of ``b`` as the reference value. In the
|
|
special case that you explicitly specify an absolute tolerance but not a
|
|
relative tolerance, only the absolute tolerance is considered.
|
|
|
|
.. note::
|
|
|
|
``approx`` can handle numpy arrays, but we recommend the
|
|
specialised test helpers in :std:doc:`numpy:reference/routines.testing`
|
|
if you need support for comparisons, NaNs, or ULP-based tolerances.
|
|
|
|
To match strings using regex, you can use
|
|
`Matches <https://github.com/asottile/re-assert#re_assertmatchespattern-str-args-kwargs>`_
|
|
from the
|
|
`re_assert package <https://github.com/asottile/re-assert>`_.
|
|
|
|
|
|
.. note::
|
|
|
|
Unlike built-in equality, this function considers
|
|
booleans unequal to numeric zero or one. For example::
|
|
|
|
>>> 1 == approx(True)
|
|
False
|
|
|
|
.. warning::
|
|
|
|
.. versionchanged:: 3.2
|
|
|
|
In order to avoid inconsistent behavior, :py:exc:`TypeError` is
|
|
raised for ``>``, ``>=``, ``<`` and ``<=`` comparisons.
|
|
The example below illustrates the problem::
|
|
|
|
assert approx(0.1) > 0.1 + 1e-10 # calls approx(0.1).__gt__(0.1 + 1e-10)
|
|
assert 0.1 + 1e-10 > approx(0.1) # calls approx(0.1).__lt__(0.1 + 1e-10)
|
|
|
|
In the second example one expects ``approx(0.1).__le__(0.1 + 1e-10)``
|
|
to be called. But instead, ``approx(0.1).__lt__(0.1 + 1e-10)`` is used to
|
|
comparison. This is because the call hierarchy of rich comparisons
|
|
follows a fixed behavior. More information: :py:meth:`object.__ge__`
|
|
|
|
.. versionchanged:: 3.7.1
|
|
``approx`` raises ``TypeError`` when it encounters a dict value or
|
|
sequence element of non-numeric type.
|
|
|
|
.. versionchanged:: 6.1.0
|
|
``approx`` falls back to strict equality for non-numeric types instead
|
|
of raising ``TypeError``.
|
|
"""
|
|
# Delegate the comparison to a class that knows how to deal with the type
|
|
# of the expected value (e.g. int, float, list, dict, numpy.array, etc).
|
|
#
|
|
# The primary responsibility of these classes is to implement ``__eq__()``
|
|
# and ``__repr__()``. The former is used to actually check if some
|
|
# "actual" value is equivalent to the given expected value within the
|
|
# allowed tolerance. The latter is used to show the user the expected
|
|
# value and tolerance, in the case that a test failed.
|
|
#
|
|
# The actual logic for making approximate comparisons can be found in
|
|
# ApproxScalar, which is used to compare individual numbers. All of the
|
|
# other Approx classes eventually delegate to this class. The ApproxBase
|
|
# class provides some convenient methods and overloads, but isn't really
|
|
# essential.
|
|
|
|
__tracebackhide__ = True
|
|
|
|
_warn_on_inexact_decimal_tolerance(expected, rel, abs)
|
|
|
|
if isinstance(expected, Decimal):
|
|
return ApproxDecimal(expected, rel=rel, abs=abs, nan_ok=nan_ok) # type: ignore[return-value]
|
|
elif isinstance(expected, Mapping):
|
|
return ApproxMapping(expected, rel=rel, abs=abs, nan_ok=nan_ok) # type: ignore[return-value]
|
|
elif (np_array := _as_numpy_array(expected)) is not None:
|
|
return ApproxNumpy(np_array, rel=rel, abs=abs, nan_ok=nan_ok)
|
|
elif _is_sequence_like(expected):
|
|
return ApproxSequenceLike(expected, rel=rel, abs=abs, nan_ok=nan_ok) # type: ignore[return-value]
|
|
elif isinstance(expected, Collection) and not isinstance(expected, str | bytes):
|
|
msg = f"pytest.approx() only supports ordered sequences, but got: {expected!r}"
|
|
raise TypeError(msg)
|
|
elif isinstance(expected, (datetime, timedelta)):
|
|
return ApproxTimedelta(expected, rel=rel, abs=abs, nan_ok=nan_ok) # type: ignore[return-value]
|
|
else:
|
|
return ApproxScalar(expected, rel=rel, abs=abs, nan_ok=nan_ok)
|
|
|
|
|
|
def _contains_decimal(expected: object) -> bool:
|
|
"""Whether a comparison against ``expected`` will use Decimal arithmetic."""
|
|
if isinstance(expected, Decimal):
|
|
return True
|
|
if isinstance(expected, Mapping):
|
|
return any(isinstance(value, Decimal) for value in expected.values())
|
|
if _is_sequence_like(expected):
|
|
# ``.flat`` also makes a 0-d numpy array iterable, which it is not
|
|
# otherwise, despite being sized and subscriptable.
|
|
values = getattr(expected, "flat", expected)
|
|
return any(isinstance(value, Decimal) for value in values)
|
|
return False
|
|
|
|
|
|
def _warn_on_inexact_decimal_tolerance(
|
|
expected: object,
|
|
rel: float | Decimal | timedelta | None,
|
|
abs: float | Decimal | timedelta | None,
|
|
) -> None:
|
|
"""Warn when a float tolerance is used for a Decimal comparison.
|
|
|
|
A float tolerance is converted with ``Decimal.from_float()``, which is
|
|
exact and therefore keeps the float's full binary expansion: ``rel=0.01``
|
|
really means a tolerance of ``0.010000000000000000208...``. That is wider
|
|
than the ``0.01`` that was written, which defeats the point of comparing
|
|
Decimals in the first place.
|
|
|
|
Only floats that cannot be represented exactly are worth warning about;
|
|
``0.5`` and friends survive the conversion unchanged, as do ints.
|
|
"""
|
|
inexact = [
|
|
(name, value)
|
|
for name, value in (("rel", rel), ("abs", abs))
|
|
if type(value) is float and Decimal.from_float(value) != Decimal(repr(value))
|
|
]
|
|
if not inexact or not _contains_decimal(expected):
|
|
return
|
|
for name, value in inexact:
|
|
warnings.warn(
|
|
PytestApproxDecimalToleranceWarning(
|
|
f"{name}={value!r} cannot be represented exactly as a Decimal "
|
|
f"and was widened to {Decimal.from_float(value)}.\n"
|
|
f"Pass {name}=Decimal({str(value)!r}) to compare against the "
|
|
f"tolerance you wrote."
|
|
),
|
|
stacklevel=3,
|
|
)
|
|
|
|
|
|
def _is_sequence_like(expected: object) -> TypeGuard[Sequence[Any]]:
|
|
return (
|
|
hasattr(expected, "__getitem__")
|
|
and isinstance(expected, Sized)
|
|
and not isinstance(expected, str | bytes)
|
|
)
|
|
|
|
|
|
def _is_nested_container(value: object) -> bool:
|
|
"""Whether ``value`` is a container ``approx`` cannot descend into.
|
|
|
|
``str``, ``bytes`` and ``bytearray`` are collections as well, but they
|
|
compare exactly and are handled as leaves, so they are not nesting.
|
|
"""
|
|
return isinstance(value, Collection) and not isinstance(
|
|
value, str | bytes | bytearray
|
|
)
|
|
|
|
|
|
def _as_numpy_array(obj: object) -> ndarray | None:
|
|
"""
|
|
Return an ndarray if the given object is implicitly convertible to ndarray,
|
|
and numpy is already imported, otherwise None.
|
|
"""
|
|
np: Any = sys.modules.get("numpy")
|
|
if np is not None:
|
|
# avoid infinite recursion on numpy scalars, which have __array__
|
|
if np.isscalar(obj):
|
|
return None
|
|
elif isinstance(obj, np.ndarray):
|
|
return obj
|
|
elif hasattr(obj, "__array__") or hasattr(obj, "__array_interface__"):
|
|
return np.asarray(obj)
|
|
return None
|
|
|
|
|
|
def _unbox_numpy_scalar(value: Any) -> Any:
|
|
"""Return the Python object behind a numpy scalar.
|
|
|
|
Indexing an object-dtype array yields the stored Python object, which has
|
|
no ``item()`` of its own -- only numpy's own scalar types need unboxing.
|
|
"""
|
|
item = getattr(value, "item", None)
|
|
return value if item is None else item()
|
|
|
|
|
|
def _is_bool(val: Any) -> bool:
|
|
# Check if `val` is a native bool or numpy bool.
|
|
if isinstance(val, bool):
|
|
return True
|
|
if np := sys.modules.get("numpy"):
|
|
return isinstance(val, np.bool_)
|
|
return False
|
|
|
|
|
|
def _is_nan(val: Any) -> bool:
|
|
# Decimal must not go through float(), which loses exactness and turns
|
|
# out-of-float-range values into infinities (see #15005).
|
|
if isinstance(val, Decimal):
|
|
return val.is_nan()
|
|
return math.isnan(val)
|
|
|
|
|
|
def _is_inf(val: Any) -> bool:
|
|
if isinstance(val, Decimal):
|
|
return val.is_infinite()
|
|
return math.isinf(val)
|