assertpy 2.35.0__py3-none-any.whl

assertpy/dataframe.py

@@ -0,0 +1,200 @@
+"""Optional fluent assertions for data-science containers (pandas / polars / numpy).
+
+This is an *integration* layer in the same spirit as the Allure and Behave adapters: each library is its
+own optional extra (``pip install assertpy[pandas]`` / ``[polars]`` / ``[numpy]``, or ``[data]`` for all
+three), imported lazily by name, so the core stays free of runtime dependencies.  Comparison
+**semantics** are delegated to each library's own testing utilities (``assert_frame_equal`` /
+``assert_series_equal`` / ``assert_array_equal`` / ``assert_allclose``), so dtype, tolerance and NaN
+handling are the library's, with the exceptions this layer adds: ``is_array_equal`` compares the shapes
+before numpy does, and ``is_array_close_to`` defaults its tolerances to those of ``numpy.isclose`` and
+takes no ``NaN`` as equal unless asked.  Otherwise this layer adds the fluent entry point and routes
+failures through the standard assertpy error model.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from ._engine._mixin_base import _MixinBase
+from ._engine._require import refuse
+
+if TYPE_CHECKING:
+    from ._engine._compat import Self
+
+__tracebackhide__ = True
+
+_FRAME_ROOTS = ("pandas", "polars")
+
+
+def _ensure_module(name: str) -> Any:
+    """Import optional library *name* by string, or raise a clear ImportError pointing at its extra."""
+    try:
+        return importlib.import_module(name)
+    except ImportError:
+        raise ImportError(
+            f"{name} is required for these assertions. Install it with: pip install assertpy[{name}]"
+        ) from None
+
+
+def _load(root: str) -> tuple[Any, Any]:
+    """Return ``(library, library.testing)`` for *root* (``pandas``/``polars``/``numpy``)."""
+    library = _ensure_module(root)
+    return library, importlib.import_module(f"{root}.testing")
+
+
+class DataFrameMixin(_MixinBase):
+    """Fluent assertions for pandas/polars frames and numpy arrays (optional ``[data]`` extra).
+
+    Each hands the comparison to the owning library's testing utilities and reports a failure through the
+    standard error model, so soft assertions, ``check()``, ``described_as()`` and warn mode all apply.
+    """
+
+    def is_frame_equal(self, expected: object, **options: Any) -> Self:
+        """Asserts that a pandas/polars ``DataFrame`` or ``Series`` equals *expected*.
+
+        Delegates to the owning library's own ``assert_frame_equal`` / ``assert_series_equal``, so all
+        comparison semantics (dtype strictness, row/column order, tolerance, categoricals, ...) are the
+        library's.  Any keyword options are passed straight through.  *expected* has to be of the same
+        library and kind: a polars frame against a pandas one, or a ``DataFrame`` against a ``Series``, fails
+        with the library's own message about the type.
+
+        Args:
+            expected: the expected frame/series (same library and kind as val)
+            **options: keyword options forwarded to the library's ``assert_frame_equal`` /
+                ``assert_series_equal`` (e.g. ``check_dtype=False``, ``check_exact=False``, ``rtol=1e-3``)
+
+        Examples:
+            Usage:
+
+                import pandas as pd
+
+                assert_that(pd.DataFrame({"a": [1, 2]})).is_frame_equal(pd.DataFrame({"a": [1, 2]}))
+                assert_that(actual).is_frame_equal(expected, check_dtype=False)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if the frames/series are not equal (carrying the library's own diff message)
+            TypeError: if val is not a pandas or polars ``DataFrame``/``Series`` (an ``Index`` is refused too)
+            ImportError: if the owning library is not installed
+        """
+        actual = self.val
+        # walk the MRO so a user subclass resolves to the owning library through its base
+        root = next(
+            (
+                base.__module__.split(".", 1)[0]
+                for base in type(actual).__mro__
+                if base.__module__.split(".", 1)[0] in _FRAME_ROOTS
+            ),
+            type(actual).__module__.split(".", 1)[0],
+        )
+        if root not in _FRAME_ROOTS:
+            refuse(actual, "a pandas or polars DataFrame/Series")
+        library, testing = _load(root)
+        class_name = type(actual).__name__
+        # isinstance handles real subclasses, the name check handles duck-typed frames a test may inject
+        if isinstance(actual, library.Series) or class_name == "Series":
+            assert_equal, label = testing.assert_series_equal, "Series"
+        elif isinstance(actual, library.DataFrame) or class_name == "DataFrame":
+            assert_equal, label = testing.assert_frame_equal, "DataFrame"
+        else:
+            # a pandas/polars object that is neither a DataFrame nor a Series (Index, Categorical, ...)
+            refuse(actual, "a pandas or polars DataFrame/Series")
+        try:
+            assert_equal(actual, expected, **options)
+        except AssertionError as exc:
+            return self.error(
+                f"Expected the {label} to equal the expected one, but they differ:\n{exc}",
+                suppress_context=True,
+                expected=expected,
+            )
+        return self
+
+    def is_array_equal(self, expected: object, **options: Any) -> Self:
+        """Asserts that val equals *expected* element-wise, via numpy's ``assert_array_equal``.
+
+        Works on any array-likes numpy can coerce (``ndarray``, nested lists, ...).  The shapes are compared
+        before numpy is asked, so a scalar is never broadcast over an array.  Then every element must match
+        exactly, a ``NaN`` equal to a ``NaN`` in the same position, as numpy has it.
+
+        Args:
+            expected: the expected array-like
+            **options: keyword options forwarded to numpy's ``assert_array_equal``
+                (e.g. ``strict=True``, which compares the dtypes too, or ``err_msg="..."``)
+
+        Examples:
+            Usage:
+
+                import numpy as np
+
+                assert_that(np.array([1, 2, 3])).is_array_equal(np.array([1, 2, 3]))
+                assert_that(np.array([1, 2, 3])).is_array_equal(np.array([1, 2, 3]), strict=True)
+                assert_that(np.array([1, 2, 3])).is_array_equal([1, 2, 3])
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if the shapes differ, or the arrays are not equal (carrying numpy's own diff message)
+            ImportError: if numpy is not installed
+        """
+        numpy, testing = _load("numpy")
+        # shape first: left to numpy a scalar broadcasts, so an empty array "equals" 5, against the shape
+        # the docstring promises.  numpy's own `strict` is about dtype and is passed through untouched
+        actual_shape, expected_shape = numpy.shape(self.val), numpy.shape(expected)
+        if actual_shape != expected_shape:
+            return self.error(
+                f"Expected an array of shape <{expected_shape}>, but was of shape <{actual_shape}>.",
+                expected=expected,
+            )
+        try:
+            testing.assert_array_equal(self.val, expected, **options)
+        except AssertionError as exc:
+            return self.error(
+                f"Expected the arrays to be equal, but they differ:\n{exc}", suppress_context=True, expected=expected
+            )
+        return self
+
+    def is_array_close_to(
+        self, expected: object, *, rtol: float = 1e-05, atol: float = 1e-08, equal_nan: bool = False, **options: Any
+    ) -> Self:
+        """Asserts that val is element-wise close to *expected*, via numpy's ``assert_allclose``.
+
+        The float-tolerant counterpart to [`is_array_equal()`][assertpy.dataframe.DataFrameMixin.is_array_equal],
+        for comparing computed arrays.  The shapes are numpy's to compare, so a scalar broadcasts over an
+        array unless ``strict=True`` is passed, which numpy 2 accepts.  ``equal_nan`` defaults to ``False``,
+        where numpy's own default is ``True``, so a ``NaN`` fails unless asked for.
+
+        Args:
+            expected: the expected array-like
+            rtol: relative tolerance (``1e-05``, as ``numpy.isclose`` has it, where ``assert_allclose`` has ``1e-07``)
+            atol: absolute tolerance (``1e-08``, as ``numpy.isclose`` has it, where ``assert_allclose`` has ``0``)
+            equal_nan: whether ``NaN`` in the same position compares equal (``False`` here, ``True`` in numpy)
+            **options: further keyword options forwarded to numpy's ``assert_allclose``
+                (e.g. ``err_msg="..."``, ``strict=True``)
+
+        Examples:
+            Usage:
+
+                import numpy as np
+
+                assert_that(np.array([1.0, 2.0])).is_array_close_to(np.array([1.0, 2.0000001]))
+                assert_that(np.array([np.nan])).is_array_close_to(np.array([np.nan]), equal_nan=True)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if the arrays are not close (carrying numpy's own diff message)
+            ImportError: if numpy is not installed
+        """
+        _, testing = _load("numpy")
+        try:
+            testing.assert_allclose(self.val, expected, rtol=rtol, atol=atol, equal_nan=equal_nan, **options)
+        except AssertionError as exc:
+            return self.error(
+                f"Expected the arrays to be close, but they differ:\n{exc}", suppress_context=True, expected=expected
+            )
+        return self

assertpy/date.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, cast
+
+from ._engine._mixin_base import _MixinBase
+from ._engine._require import argument, require_type
+from ._hints import out_of_order, under
+from .errors import _capped, _capped_format
+
+if TYPE_CHECKING:
+    from ._engine._compat import Self
+
+__tracebackhide__ = True
+
+
+def _require_datetime(value: object, label: str) -> None:
+    """Raise ``TypeError`` unless *value* is exactly a `datetime.datetime`."""
+    require_type(value, datetime.datetime, "a datetime", subject=label)
+
+
+def _read_in_the_zone_of(value: datetime.datetime, reference: datetime.datetime) -> datetime.datetime:
+    """*value* as the same instant reads on *reference*'s clock, so wall-clock fields compare like with like.
+
+    The guide says making both sides aware is what makes these comparisons well defined.  Compared field
+    by field they were not: two instants five hours apart in different zones read equal to the second.
+    Both sides are aware or both naive by then, and a naive pair has no zone to be read in.  One wall time
+    of a zone's repeated hour is two moments an hour apart, so the caller asks whether the two are one reading
+    too (`_one_reading`) where the value was read on another clock.  Two on one zone object are left to their
+    wall clocks, as `==` is.
+    """
+    return value.astimezone(reference.tzinfo) if reference.tzinfo is not None else value
+
+
+def _one_reading(value: datetime.datetime, instant: datetime.datetime, other: datetime.datetime) -> bool:
+    """Whether two that read alike on one clock are the same reading of it, where a clock reads a time twice.
+
+    The offsets tell.  Equal ones are one reading.  Two readings of one time have the later moment at the
+    smaller offset, since the clock went back between them, and the later moment at the larger one is a clock
+    that went forward inside the unit, which reads it once.  Asked of the `fold` instead, a clock that goes
+    back by less than the unit read two visits to one minute as one.
+    """
+    # both are aware here: a naive pair has no zone to be read in and is never asked
+    held, read = cast("datetime.timedelta", value.utcoffset()), cast("datetime.timedelta", instant.utcoffset())
+    return held == read or (held < read) is (value < other)
+
+
+def _written_to(form: str, value: datetime.datetime, instant: datetime.datetime) -> tuple[str, str]:
+    """The two in *form*, with their offsets where they read alike: a wall time of a repeated hour is two moments."""
+    first, second = value.strftime(form), instant.strftime(form)
+    if first != second:
+        return first, second
+    return first + _offset_of(value), second + _offset_of(instant)
+
+
+def _offset_of(value: datetime.datetime) -> str:
+    written = value.strftime("%z")
+    return f"{written[:3]}:{written[3:]}"
+
+
+def _require_comparable_datetimes(first: datetime.datetime, second: datetime.datetime) -> None:
+    """Reject a naive-vs-aware pair with a clear message.
+
+    The relational assertions would otherwise leak the raw ``TypeError`` from ``<``/``>``.  The
+    ``ignoring_*`` ones compare wall-clock fields, which silently answers a different question: two
+    instants hours apart read equal.  Both operands are already validated as `datetime.datetime`.
+    """
+    if (first.utcoffset() is None) != (second.utcoffset() is None):
+        raise TypeError(
+            "cannot compare a timezone-naive datetime with a timezone-aware one. Make both aware or both naive first"
+        )
+
+
+class DateMixin(_MixinBase):
+    """Date and time assertions mixin."""
+
+    def is_before(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is before other date.
+
+        Args:
+            other (object): the other date, expected to be after val
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                today = datetime.datetime.now()
+                yesterday = today - datetime.timedelta(days=1)
+
+                assert_that(yesterday).is_before(today)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** before the given date
+
+        See Also:
+            [`is_less_than()`][assertpy.numeric.NumericMixin.is_less_than] - numeric assertion, but
+                also works with datetime
+            [`is_less_than_or_equal_to()`][assertpy.numeric.NumericMixin.is_less_than_or_equal_to] -
+                also works with datetime
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        if self.val >= other:
+            return self.error(
+                f"Expected <{_capped(self.val)}> to be before <{_capped_format(other)}>, but was not."
+                f"{under(out_of_order(self.val, other, before=True, strict=True))}",
+                expected=other,
+            )
+        return self
+
+    def is_after(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is after other date.
+
+        Args:
+            other (object): the other date, expected to be before val
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                today = datetime.datetime.now()
+                yesterday = today - datetime.timedelta(days=1)
+
+                assert_that(today).is_after(yesterday)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** after the given date
+
+        See Also:
+            [`is_greater_than()`][assertpy.numeric.NumericMixin.is_greater_than] - numeric assertion,
+                but also works with datetime
+            [`is_greater_than_or_equal_to()`][assertpy.numeric.NumericMixin.is_greater_than_or_equal_to] -
+                also works with datetime
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        if self.val <= other:
+            return self.error(
+                f"Expected <{_capped(self.val)}> to be after <{_capped_format(other)}>, but was not."
+                f"{under(out_of_order(self.val, other, before=False, strict=True))}",
+                expected=other,
+            )
+        return self
+
+    def is_before_or_equal_to(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is before or equal to other date.
+
+        Args:
+            other (object): the other date, expected to be after or equal to val
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                today = datetime.datetime.now()
+                yesterday = today - datetime.timedelta(days=1)
+
+                assert_that(yesterday).is_before_or_equal_to(today)
+                assert_that(today).is_before_or_equal_to(today)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** before or equal to the given date
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        if self.val > other:
+            return self.error(
+                f"Expected <{_capped(self.val)}> to be before or equal to <{_capped_format(other)}>, but was not."
+                f"{under(out_of_order(self.val, other, before=True, strict=False))}",
+                expected=other,
+            )
+        return self
+
+    def is_after_or_equal_to(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is after or equal to other date.
+
+        Args:
+            other (object): the other date, expected to be before or equal to val
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                today = datetime.datetime.now()
+                yesterday = today - datetime.timedelta(days=1)
+
+                assert_that(today).is_after_or_equal_to(yesterday)
+                assert_that(today).is_after_or_equal_to(today)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** after or equal to the given date
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        if self.val < other:
+            return self.error(
+                f"Expected <{_capped(self.val)}> to be after or equal to <{_capped_format(other)}>, but was not."
+                f"{under(out_of_order(self.val, other, before=False, strict=False))}",
+                expected=other,
+            )
+        return self
+
+    def is_equal_to_ignoring_milliseconds(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is equal to other date to the second.
+
+        Args:
+            other (object): the other date, expected to be equal to the second
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                d1 = datetime.datetime(2020, 1, 2, 3, 4, 5, 6)       # 2020-01-02 03:04:05.000006
+                d2 = datetime.datetime(2020, 1, 2, 3, 4, 5, 777777)  # 2020-01-02 03:04:05.777777
+
+                assert_that(d1).is_equal_to_ignoring_milliseconds(d2)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** equal to the given date to the second
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        instant = _read_in_the_zone_of(other, self.val)
+        if (
+            self.val.date() == instant.date()
+            and self.val.hour == instant.hour
+            and self.val.minute == instant.minute
+            and self.val.second == instant.second
+            and (instant is other or _one_reading(self.val, instant, other))
+        ):
+            return self
+        read, wanted = _written_to("%Y-%m-%d %H:%M:%S", self.val, instant)
+        return self.error(f"Expected <{read}> to be equal to <{wanted}>, but was not.", expected=other)
+
+    def is_equal_to_ignoring_seconds(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is equal to other date to the minute.
+
+        Args:
+            other (object): the other date, expected to be equal to the minute
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                d1 = datetime.datetime(2020, 1, 2, 3, 4, 5)   # 2020-01-02 03:04:05
+                d2 = datetime.datetime(2020, 1, 2, 3, 4, 55)  # 2020-01-02 03:04:55
+
+                assert_that(d1).is_equal_to_ignoring_seconds(d2)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** equal to the given date to the minute
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        instant = _read_in_the_zone_of(other, self.val)
+        if (
+            self.val.date() == instant.date()
+            and self.val.hour == instant.hour
+            and self.val.minute == instant.minute
+            and (instant is other or _one_reading(self.val, instant, other))
+        ):
+            return self
+        read, wanted = _written_to("%Y-%m-%d %H:%M", self.val, instant)
+        return self.error(f"Expected <{read}> to be equal to <{wanted}>, but was not.", expected=other)
+
+    def is_equal_to_ignoring_time(self, other: datetime.datetime) -> Self:
+        """Asserts that val is a date and is equal to other date ignoring time.
+
+        Args:
+            other (object): the other date, expected to be equal ignoring time
+
+        Examples:
+            Usage:
+
+                import datetime
+
+                d1 = datetime.datetime(2020, 1, 2, 3, 4, 5)     # 2020-01-02 03:04:05
+                d2 = datetime.datetime(2020, 1, 2, 13, 44, 55)  # 2020-01-02 13:44:55
+
+                assert_that(d1).is_equal_to_ignoring_time(d2)
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val is **not** equal to the given date ignoring time
+        """
+        _require_datetime(self.val, "val")
+        _require_datetime(other, argument("other"))
+        _require_comparable_datetimes(self.val, other)
+        instant = _read_in_the_zone_of(other, self.val)
+        if self.val.date() == instant.date():
+            return self
+        return self.error(
+            f"Expected <{self.val.strftime('%Y-%m-%d')}> to be equal to <{instant.strftime('%Y-%m-%d')}>, but was not.",
+            expected=other,
+        )