assertpy2 2.10.0__tar.gz → 2.11.0__tar.gz

{assertpy2-2.10.0 → assertpy2-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.10.0
+Version: 2.11.0
 Summary: Fluent assertion library for Python with composable matchers, structural matching, and full type safety
 Project-URL: Homepage, https://github.com/Solganis/assertpy2
 Project-URL: Repository, https://github.com/Solganis/assertpy2
@@ -31,9 +31,19 @@ Provides-Extra: allure
 Requires-Dist: allure-pytest>=2.13; extra == 'allure'
 Provides-Extra: behave
 Requires-Dist: behave>=1.2.6; extra == 'behave'
+Provides-Extra: data
+Requires-Dist: numpy>=1.26; extra == 'data'
+Requires-Dist: pandas>=2.0; extra == 'data'
+Requires-Dist: polars>=1.0; extra == 'data'
 Provides-Extra: json
 Requires-Dist: jsonpath-ng>=1.8; extra == 'json'
 Requires-Dist: jsonschema>=4.0; extra == 'json'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.26; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars>=1.0; extra == 'polars'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -68,7 +78,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-## [Quick start](https://solganis.github.io/assertpy2/getting-started/)
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/">Quick start</a></h2>
 
 ```bash
 pip install assertpy2  # drop-in replacement for assertpy, just change the import
@@ -88,7 +98,7 @@ def test_user():
 
 Browse the [full documentation](https://solganis.github.io/assertpy2/) for every assertion, matcher, and integration.
 
-## [Why fluent assertions?](https://solganis.github.io/assertpy2/comparison/)
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/comparison/">Why fluent assertions?</a></h2>
 
 A fluent chain reads as one intent and replaces several bare asserts - and your IDE
 offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/type-safety/):
@@ -121,7 +131,9 @@ assertpy2 reports the [exact path to every difference](https://solganis.github.i
 assert_that(response).is_equal_to(expected)
 ```
 
-<img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: user.role shown with its path, removal in red and addition in green">
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: user.role shown with its path, removal in red and addition in green">
+</p>
 
 Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
 For responses with dynamic fields (IDs, timestamps), validate a subset with
@@ -129,9 +141,11 @@ For responses with dynamic fields (IDs, timestamps), validate a subset with
 
 The same path-level treatment for dicts, lists, sets, and matcher predicates:
 
-<img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
+</p>
 
-## [Type-aware autocomplete](https://solganis.github.io/assertpy2/type-safety/)
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/type-safety/">Type-aware autocomplete</a></h2>
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
 Your IDE shows only methods relevant to the value you're testing, not all 100+:
@@ -148,7 +162,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 ---
 
-## Features
+<h2 align="center">Features</h2>
 
 **Fluent API**
 
@@ -162,7 +176,6 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 - [Strings](https://solganis.github.io/assertpy2/assertions/#strings), [numbers](https://solganis.github.io/assertpy2/assertions/#numbers), [lists](https://solganis.github.io/assertpy2/assertions/#lists), [tuples](https://solganis.github.io/assertpy2/assertions/#tuples), [sets](https://solganis.github.io/assertpy2/assertions/#sets), [dicts](https://solganis.github.io/assertpy2/assertions/#dicts), [dates](https://solganis.github.io/assertpy2/assertions/#dates), [booleans](https://solganis.github.io/assertpy2/assertions/#booleans), [objects](https://solganis.github.io/assertpy2/assertions/#objects), [bytes](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray), [files](https://solganis.github.io/assertpy2/assertions/#files), [exceptions](https://solganis.github.io/assertpy2/errors/#expected-exceptions).
 - [**Bytes assertions**](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
-- [**JSON assertions**](https://solganis.github.io/assertpy2/data/#json-path--schema): JSONPath navigation and JSON Schema validation. `pip install assertpy2[json]`.
 - [**Dynamic assertions**](https://solganis.github.io/assertpy2/assertions/#dynamic-assertions-on-objects): `has_<name>()` for any attribute, property, or zero-argument method.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects).
 - [**Extracting**](https://solganis.github.io/assertpy2/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
@@ -178,7 +191,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 **Type safety**
 
-- [**Type-aware autocomplete**](#type-aware-autocomplete): 9 Protocols, IDE shows only relevant methods per type.
+- [**Type-aware autocomplete**](https://solganis.github.io/assertpy2/type-safety/): 9 Protocols, IDE shows only relevant methods per type.
 - **py.typed**: `Self` return types, PEP 561 compliant ([PEP 561](https://peps.python.org/pep-0561/)).
 
 **Extensibility**
@@ -187,64 +200,19 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Regex group extraction**](https://solganis.github.io/assertpy2/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 - [**Extensions**](https://solganis.github.io/assertpy2/extending/): `add_extension()` for custom assertion methods.
 
-**Integrations**
-
-- [**Allure**](https://solganis.github.io/assertpy2/integrations/#allure): auto-attach structured diff and actual/expected data to reports. `pip install assertpy2[allure]`.
-- [**Behave**](https://solganis.github.io/assertpy2/integrations/#behave): ready-made parameter types for step definitions. `pip install assertpy2[behave]`.
-
 See the [full documentation](https://solganis.github.io/assertpy2/) for all assertion methods, examples, and advanced features.
 
 ---
 
-## [Integrations](https://solganis.github.io/assertpy2/integrations/)
-
-### Allure
-
-When `allure-pytest` is installed, the pytest plugin auto-attaches structured failure data to Allure reports as JSON attachments.
-
-```bash
-pip install assertpy2[allure]
-```
-
-Three modes controlled via `pytest.ini` (or `pyproject.toml`):
-
-| Mode | What is attached |
-|---|---|
-| `diff` (default) | Structured Diff JSON (path-level breakdown) |
-| `full` | Structured Diff + actual/expected JSON |
-| `off` | Nothing |
-
-```toml
-# pyproject.toml
-[tool.pytest.ini_options]
-assertpy2_allure = "full"
-```
-
-### Behave
-
-Ready-made parameter types for Behave step definitions:
-
-```bash
-pip install assertpy2[behave]
-```
-
-```py
-# in environment.py or steps/conftest.py
-from assertpy2.behave_matchers import register_assertpy_types
-register_assertpy_types()
-```
-
-Then use in step definitions:
-
-```py
-@given('a user aged {age:PositiveInt}')
-def step_impl(context, age):
-    context.age = age  # already validated as int > 0
-```
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/integrations/">Integrations</a></h2>
 
-Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
+Optional adapters, each its own extra; full configuration and examples are in the
+[Integrations guide](https://solganis.github.io/assertpy2/integrations/).
 
-See the [Integrations guide](https://solganis.github.io/assertpy2/integrations/) for attachment modes, configuration, and full examples.
+- [**Allure**](https://solganis.github.io/assertpy2/integrations/#allure) (`pip install assertpy2[allure]`): the pytest plugin auto-attaches structured diff and actual/expected data to Allure reports, in three configurable modes.
+- [**Behave**](https://solganis.github.io/assertpy2/integrations/#behave) (`pip install assertpy2[behave]`): ready-made parameter types (`PositiveInt`, `NonEmptyString`, ...) for step definitions like `{age:PositiveInt}`.
+- [**JSON**](https://solganis.github.io/assertpy2/data/#json-path--schema) (`pip install assertpy2[json]`): JSONPath navigation (`at_json_path()`, `has_json_path()`) and JSON Schema validation (`matches_json_schema()`).
+- [**Data frames**](https://solganis.github.io/assertpy2/integrations/#data-frames-and-arrays) (`pip install assertpy2[pandas]` / `[polars]` / `[numpy]`): fluent equality for pandas/polars frames and numpy arrays, carrying each library's own diff.
 
 ---
 

{assertpy2-2.10.0 → assertpy2-2.11.0}/README.md

@@ -30,7 +30,7 @@
 
 ---
 
-## [Quick start](https://solganis.github.io/assertpy2/getting-started/)
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/">Quick start</a></h2>
 
 ```bash
 pip install assertpy2  # drop-in replacement for assertpy, just change the import
@@ -50,7 +50,7 @@ def test_user():
 
 Browse the [full documentation](https://solganis.github.io/assertpy2/) for every assertion, matcher, and integration.
 
-## [Why fluent assertions?](https://solganis.github.io/assertpy2/comparison/)
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/comparison/">Why fluent assertions?</a></h2>
 
 A fluent chain reads as one intent and replaces several bare asserts - and your IDE
 offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/type-safety/):
@@ -83,7 +83,9 @@ assertpy2 reports the [exact path to every difference](https://solganis.github.i
 assert_that(response).is_equal_to(expected)
 ```
 
-<img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: user.role shown with its path, removal in red and addition in green">
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: user.role shown with its path, removal in red and addition in green">
+</p>
 
 Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
 For responses with dynamic fields (IDs, timestamps), validate a subset with
@@ -91,9 +93,11 @@ For responses with dynamic fields (IDs, timestamps), validate a subset with
 
 The same path-level treatment for dicts, lists, sets, and matcher predicates:
 
-<img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
+</p>
 
-## [Type-aware autocomplete](https://solganis.github.io/assertpy2/type-safety/)
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/type-safety/">Type-aware autocomplete</a></h2>
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
 Your IDE shows only methods relevant to the value you're testing, not all 100+:
@@ -110,7 +114,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 ---
 
-## Features
+<h2 align="center">Features</h2>
 
 **Fluent API**
 
@@ -124,7 +128,6 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 - [Strings](https://solganis.github.io/assertpy2/assertions/#strings), [numbers](https://solganis.github.io/assertpy2/assertions/#numbers), [lists](https://solganis.github.io/assertpy2/assertions/#lists), [tuples](https://solganis.github.io/assertpy2/assertions/#tuples), [sets](https://solganis.github.io/assertpy2/assertions/#sets), [dicts](https://solganis.github.io/assertpy2/assertions/#dicts), [dates](https://solganis.github.io/assertpy2/assertions/#dates), [booleans](https://solganis.github.io/assertpy2/assertions/#booleans), [objects](https://solganis.github.io/assertpy2/assertions/#objects), [bytes](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray), [files](https://solganis.github.io/assertpy2/assertions/#files), [exceptions](https://solganis.github.io/assertpy2/errors/#expected-exceptions).
 - [**Bytes assertions**](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
-- [**JSON assertions**](https://solganis.github.io/assertpy2/data/#json-path--schema): JSONPath navigation and JSON Schema validation. `pip install assertpy2[json]`.
 - [**Dynamic assertions**](https://solganis.github.io/assertpy2/assertions/#dynamic-assertions-on-objects): `has_<name>()` for any attribute, property, or zero-argument method.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects).
 - [**Extracting**](https://solganis.github.io/assertpy2/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
@@ -140,7 +143,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 **Type safety**
 
-- [**Type-aware autocomplete**](#type-aware-autocomplete): 9 Protocols, IDE shows only relevant methods per type.
+- [**Type-aware autocomplete**](https://solganis.github.io/assertpy2/type-safety/): 9 Protocols, IDE shows only relevant methods per type.
 - **py.typed**: `Self` return types, PEP 561 compliant ([PEP 561](https://peps.python.org/pep-0561/)).
 
 **Extensibility**
@@ -149,64 +152,19 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Regex group extraction**](https://solganis.github.io/assertpy2/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 - [**Extensions**](https://solganis.github.io/assertpy2/extending/): `add_extension()` for custom assertion methods.
 
-**Integrations**
-
-- [**Allure**](https://solganis.github.io/assertpy2/integrations/#allure): auto-attach structured diff and actual/expected data to reports. `pip install assertpy2[allure]`.
-- [**Behave**](https://solganis.github.io/assertpy2/integrations/#behave): ready-made parameter types for step definitions. `pip install assertpy2[behave]`.
-
 See the [full documentation](https://solganis.github.io/assertpy2/) for all assertion methods, examples, and advanced features.
 
 ---
 
-## [Integrations](https://solganis.github.io/assertpy2/integrations/)
-
-### Allure
-
-When `allure-pytest` is installed, the pytest plugin auto-attaches structured failure data to Allure reports as JSON attachments.
-
-```bash
-pip install assertpy2[allure]
-```
-
-Three modes controlled via `pytest.ini` (or `pyproject.toml`):
-
-| Mode | What is attached |
-|---|---|
-| `diff` (default) | Structured Diff JSON (path-level breakdown) |
-| `full` | Structured Diff + actual/expected JSON |
-| `off` | Nothing |
-
-```toml
-# pyproject.toml
-[tool.pytest.ini_options]
-assertpy2_allure = "full"
-```
-
-### Behave
-
-Ready-made parameter types for Behave step definitions:
-
-```bash
-pip install assertpy2[behave]
-```
-
-```py
-# in environment.py or steps/conftest.py
-from assertpy2.behave_matchers import register_assertpy_types
-register_assertpy_types()
-```
-
-Then use in step definitions:
-
-```py
-@given('a user aged {age:PositiveInt}')
-def step_impl(context, age):
-    context.age = age  # already validated as int > 0
-```
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/integrations/">Integrations</a></h2>
 
-Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
+Optional adapters, each its own extra; full configuration and examples are in the
+[Integrations guide](https://solganis.github.io/assertpy2/integrations/).
 
-See the [Integrations guide](https://solganis.github.io/assertpy2/integrations/) for attachment modes, configuration, and full examples.
+- [**Allure**](https://solganis.github.io/assertpy2/integrations/#allure) (`pip install assertpy2[allure]`): the pytest plugin auto-attaches structured diff and actual/expected data to Allure reports, in three configurable modes.
+- [**Behave**](https://solganis.github.io/assertpy2/integrations/#behave) (`pip install assertpy2[behave]`): ready-made parameter types (`PositiveInt`, `NonEmptyString`, ...) for step definitions like `{age:PositiveInt}`.
+- [**JSON**](https://solganis.github.io/assertpy2/data/#json-path--schema) (`pip install assertpy2[json]`): JSONPath navigation (`at_json_path()`, `has_json_path()`) and JSON Schema validation (`matches_json_schema()`).
+- [**Data frames**](https://solganis.github.io/assertpy2/integrations/#data-frames-and-arrays) (`pip install assertpy2[pandas]` / `[polars]` / `[numpy]`): fluent equality for pandas/polars frames and numpy arrays, carrying each library's own diff.
 
 ---
 

{assertpy2-2.10.0 → assertpy2-2.11.0}/assertpy2/_mixin_base.py

@@ -6,7 +6,7 @@ if TYPE_CHECKING:
     import logging
 
     from ._compat import Self
-    from .errors import DiffResult
+    from .errors import DiffEntry, DiffResult
 
 
 class _MixinBase:
@@ -96,6 +96,11 @@ class _MixinBase:
         @staticmethod
         def _to_comparable_dict(obj: object) -> dict[str, object] | None: ...
 
+        @staticmethod
+        def _sub_diff_entries(
+            actual: object, expected: object, prefix: str, *, _seen: set[int] | None = ...
+        ) -> list[DiffEntry] | None: ...
+
         # NumericMixin class attrs used by HelpersMixin._validate_between_args
         _NUMERIC_COMPAREABLE: frozenset[type]
         _NUMERIC_NON_COMPAREABLE: frozenset[type]

{assertpy2-2.10.0 → assertpy2-2.11.0}/assertpy2/assertpy.py

@@ -34,6 +34,7 @@ from .base import BaseMixin
 from .bytes_mixin import BytesMixin
 from .collection import CollectionMixin
 from .contains import ContainsMixin
+from .dataframe import DataFrameMixin
 from .date import DateMixin
 from .dict import DictMixin
 from .dynamic import DynamicMixin
@@ -48,7 +49,7 @@ from .snapshot import SnapshotMixin
 from .string import StringMixin
 from .warning import WarningMixin
 
-__version__ = "2.10.0"
+__version__ = "2.11.0"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
@@ -548,6 +549,7 @@ class AssertionBuilder(
     ContainsMixin,
     CollectionMixin,
     BytesMixin,
+    DataFrameMixin,
     BaseMixin,
 ):
     """The main assertion class.  Never call the constructor directly, always use the

{assertpy2-2.10.0 → assertpy2-2.11.0}/assertpy2/base.py

@@ -4,7 +4,7 @@ import collections.abc
 import dataclasses
 from typing import TYPE_CHECKING, Any, Final
 
-from ._introspection import is_model_dump_object, is_namedtuple
+from ._introspection import is_mapping_like, is_model_dump_object, is_namedtuple
 from ._mixin_base import _MixinBase
 from .errors import DiffEntry, DiffResult
 from .matchers import Matcher, StructureMatcher
@@ -17,6 +17,34 @@ __tracebackhide__ = True
 _SENTINEL: Final = object()
 
 
+def _ambiguous_array_operand(value: object, other: object) -> object | None:
+    """Return the array/frame-like operand whose ``==`` has no single truth value, else ``None``.
+
+    numpy/pandas/polars containers expose ``__array__`` and compare element-wise, so ``bool(a == b)``
+    raises rather than yielding one bool (and a ``DataFrame`` also quacks dict-like, which would otherwise
+    mis-dispatch the comparison).  The ``__array__`` gate keeps the extra comparison off the hot path; the
+    truth test is actually attempted, so 0-d / scalar array values (which *are* truth-testable) pass
+    through unchanged.
+    """
+    for candidate, counterpart in ((value, other), (other, value)):
+        if hasattr(candidate, "__array__"):
+            try:
+                bool(candidate == counterpart)
+            except (ValueError, TypeError):
+                return candidate
+    return None
+
+
+def _array_equality_error(method: str, operand: object) -> TypeError:
+    """Build the actionable error raised when ``method`` is given an element-wise array/frame-like."""
+    return TypeError(
+        f"{method}() cannot directly compare <{type(operand).__name__}>: its '==' is element-wise and has"
+        " no single truth value. Compare the value's own equality (e.g."
+        " assert_that(actual.equals(expected)).is_true()), assert on extracted scalars (columns, shape,"
+        " length), or use satisfies(...) with an explicit predicate."
+    )
+
+
 class BaseMixin(_MixinBase):
     """Base mixin."""
 
@@ -115,7 +143,9 @@ class BaseMixin(_MixinBase):
         Raises:
             AssertionError: if actual is **not** equal to expected
             TypeError: if ``ignore``/``include`` is a one-shot or otherwise unsupported iterable, or is
-                used on a value that is neither dict-like nor has introspectable fields
+                used on a value that is neither dict-like nor has introspectable fields; or if val or
+                other is an element-wise array/frame-like (numpy/pandas/polars) whose ``==`` has no single
+                truth value (compare the value's own equality, e.g. ``actual.equals(expected)``, instead)
 
         Tip:
             Using :meth:`is_equal_to` with a ``float`` val is just asking for trouble. Instead, you'll
@@ -128,6 +158,10 @@ class BaseMixin(_MixinBase):
         ignore = kwargs.get("ignore")
         include = kwargs.get("include")
 
+        operand = _ambiguous_array_operand(self.val, other)
+        if operand is not None:
+            raise _array_equality_error("is_equal_to", operand)
+
         if self._is_dict_like(self.val, check_values=False) and self._is_dict_like(other, check_values=False):
             if self._dict_not_equal(self.val, other, ignore=ignore, include=include):
                 self._dict_err(self.val, other, ignore=ignore, include=include)
@@ -335,26 +369,36 @@ class BaseMixin(_MixinBase):
     def _sub_diff_entries(
         actual: object, expected: object, prefix: str, *, _seen: set[int] | None = None
     ) -> list[DiffEntry] | None:
+        """Canonical recursive diff for a value, returning path-level entries (or ``None`` for a leaf).
+
+        Recurses into mappings, dataclasses, namedtuples, model-dump objects and sequences; returns
+        ``None`` for anything else so the caller renders a single leaf entry.  This is the single nested
+        engine shared by the top-level paths: :meth:`_build_equality_diff` (lists, dataclasses, ...) and
+        the dict path (:meth:`HelpersMixin._dict_err`), which calls it with an empty ``prefix`` so the
+        top-level dict keys render bare (``b``) and nested keys render dotted (``u.b``).
+        """
         if _seen is None:
             _seen = set()
         if id(actual) in _seen or id(expected) in _seen:
             return [DiffEntry(path=prefix, actual="<circular ref>", expected="<circular ref>")]
 
-        if isinstance(actual, dict) and isinstance(expected, dict):
+        if is_mapping_like(actual) and is_mapping_like(expected):
             child_seen = _seen | {id(actual), id(expected)}
             entries: list[DiffEntry] = []
-            for key in sorted(set(actual) | set(expected), key=repr):
-                path = f"{prefix}.{key}"
-                if key not in expected:
-                    entries.append(DiffEntry(path=path, actual=actual[key], expected=None))  # ty: ignore[invalid-argument-type]
-                elif key not in actual:
-                    entries.append(DiffEntry(path=path, actual=None, expected=expected[key]))  # ty: ignore[invalid-argument-type]
-                elif actual[key] != expected[key]:  # ty: ignore[invalid-argument-type]
-                    sub_entries = BaseMixin._sub_diff_entries(actual[key], expected[key], path, _seen=child_seen)  # ty: ignore[invalid-argument-type]
+            actual_keys = set(actual)
+            expected_keys = set(expected)
+            for key in sorted(actual_keys | expected_keys, key=repr):
+                path = f"{prefix}.{key}" if prefix else str(key)
+                if key not in expected_keys:
+                    entries.append(DiffEntry(path=path, actual=actual[key], expected=None))
+                elif key not in actual_keys:
+                    entries.append(DiffEntry(path=path, actual=None, expected=expected[key]))
+                elif actual[key] != expected[key]:
+                    sub_entries = BaseMixin._sub_diff_entries(actual[key], expected[key], path, _seen=child_seen)
                     if sub_entries is not None:
                         entries.extend(sub_entries)
                     else:
-                        entries.append(DiffEntry(path=path, actual=actual[key], expected=expected[key]))  # ty: ignore[invalid-argument-type]
+                        entries.append(DiffEntry(path=path, actual=actual[key], expected=expected[key]))
             return entries or None
         if (
             dataclasses.is_dataclass(actual)
@@ -715,7 +759,13 @@ class BaseMixin(_MixinBase):
 
         Raises:
             AssertionError: if actual **is** equal to expected
+            TypeError: if val or other is an element-wise array/frame-like (numpy/pandas/polars) whose
+                ``==`` has no single truth value; compare the value's own equality instead
         """
+        operand = _ambiguous_array_operand(self.val, other)
+        if operand is not None:
+            raise _array_equality_error("is_not_equal_to", operand)
+
         if self.val == other:
             return self.error(f"Expected <{self.val}> to be not equal to <{other}>, but was.")
         return self

assertpy2-2.11.0/assertpy2/dataframe.py

@@ -0,0 +1,153 @@
+"""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 assertpy2[pandas]`` / ``[polars]`` / ``[numpy]``, or ``[data]`` for all
+three), imported lazily by name, so the core stays free of runtime dependencies.  Comparison
+**semantics** are delegated entirely to each library's own testing
+utilities (``assert_frame_equal`` / ``assert_series_equal`` / ``assert_array_equal`` / ``assert_allclose``),
+so dtype, tolerance and NaN handling match the library exactly.  This layer only adds the fluent entry
+point and routes failures through the standard assertpy2 error model.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from ._mixin_base import _MixinBase
+
+if TYPE_CHECKING:
+    from ._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 assertpy2[{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)."""
+
+    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.
+
+        Args:
+            expected: the expected frame/series (same library 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``
+            ImportError: if the owning library is not installed
+        """
+        actual = self.val
+        root = type(actual).__module__.split(".", 1)[0]
+        if root not in _FRAME_ROOTS:
+            raise TypeError(
+                f"is_frame_equal() expects a pandas or polars DataFrame/Series, but was <{type(actual).__name__}>."
+            )
+        library, testing = _load(root)
+        if isinstance(actual, library.Series):
+            assert_equal, label = testing.assert_series_equal, "Series"
+        else:
+            assert_equal, label = testing.assert_frame_equal, "DataFrame"
+        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}")
+        return self
+
+    def is_array_equal(self, expected: object) -> 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, ...); shape and every
+        element must match exactly (with ``NaN`` treated as equal, per numpy).
+
+        Args:
+            expected: the expected array-like
+
+        Examples:
+            Usage::
+
+                import numpy as np
+
+                assert_that(np.array([1, 2, 3])).is_array_equal(np.array([1, 2, 3]))
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if the arrays are not equal (carrying numpy's own diff message)
+            ImportError: if numpy is not installed
+        """
+        _, testing = _load("numpy")
+        try:
+            testing.assert_array_equal(self.val, expected)
+        except AssertionError as exc:
+            return self.error(f"Expected the arrays to be equal, but they differ:\n{exc}")
+        return self
+
+    def is_array_close_to(
+        self, expected: object, *, rtol: float = 1e-05, atol: float = 1e-08, equal_nan: bool = False
+    ) -> Self:
+        """Asserts that val is element-wise close to *expected*, via numpy's ``assert_allclose``.
+
+        The float-tolerant counterpart to :meth:`is_array_equal`, for comparing computed arrays.
+
+        Args:
+            expected: the expected array-like
+            rtol: relative tolerance (numpy default ``1e-05``)
+            atol: absolute tolerance (numpy default ``1e-08``)
+            equal_nan: whether ``NaN`` in the same position compares equal
+
+        Examples:
+            Usage::
+
+                import numpy as np
+
+                assert_that(np.array([1.0, 2.0])).is_array_close_to(np.array([1.0, 2.0000001]))
+
+        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)
+        except AssertionError as exc:
+            return self.error(f"Expected the arrays to be close, but they differ:\n{exc}")
+        return self