assertpy2 2.9.1__tar.gz → 2.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.9.1
+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,13 +131,21 @@ 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: status and user.role shown with their paths, removals in red and additions 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
 [`matches_structure()`](https://solganis.github.io/assertpy2/matchers/#structural-matching) instead of exact equality.
 
-## [Type-aware autocomplete](https://solganis.github.io/assertpy2/type-safety/)
+The same path-level treatment for dicts, lists, sets, and matcher predicates:
+
+<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>
+
+<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+:
@@ -144,7 +162,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 ---
 
-## Features
+<h2 align="center">Features</h2>
 
 **Fluent API**
 
@@ -158,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.
@@ -174,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**
@@ -183,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.9.1 → 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,13 +83,21 @@ 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: status and user.role shown with their paths, removals in red and additions 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
 [`matches_structure()`](https://solganis.github.io/assertpy2/matchers/#structural-matching) instead of exact equality.
 
-## [Type-aware autocomplete](https://solganis.github.io/assertpy2/type-safety/)
+The same path-level treatment for dicts, lists, sets, and matcher predicates:
+
+<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>
+
+<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+:
@@ -106,7 +114,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 ---
 
-## Features
+<h2 align="center">Features</h2>
 
 **Fluent API**
 
@@ -120,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.
@@ -136,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**
@@ -145,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.9.1 → 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.9.1 → 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.9.1"
+__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.9.1 → 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)
@@ -187,6 +221,58 @@ class BaseMixin(_MixinBase):
                     expected=expected_item,
                 )
 
+    @staticmethod
+    def _sequence_diff_entries(actual, expected, prefix, seen) -> list[DiffEntry]:
+        """Diff two sequences element-by-element, recursing into nested containers.
+
+        ``seen`` must already include the ids of ``actual``/``expected`` so a self-referential element
+        is caught.  Shared by the top-level (:meth:`_build_equality_diff`) and nested
+        (:meth:`_sub_diff_entries`) paths so both decompose sequences identically.
+        """
+        entries: list[DiffEntry] = []
+        max_len = max(len(actual), len(expected))
+        for i in range(max_len):
+            path = f"{prefix}[{i}]" if prefix else f"[{i}]"
+            if i >= len(actual):
+                entries.append(DiffEntry(path=path, actual=None, expected=expected[i]))
+            elif i >= len(expected):
+                entries.append(DiffEntry(path=path, actual=actual[i], expected=None))
+            elif actual[i] != expected[i]:
+                sub_entries = BaseMixin._sub_diff_entries(actual[i], expected[i], path, _seen=seen)
+                if sub_entries:
+                    entries.extend(sub_entries)
+                else:
+                    entries.append(DiffEntry(path=path, actual=actual[i], expected=expected[i]))
+        return entries
+
+    @staticmethod
+    def _dataclass_diff_entries(actual, expected, prefix, seen) -> list[DiffEntry]:
+        """Diff two dataclasses over the sorted union of field names, both directions, recursing.
+
+        Reports fields present on only one side, and recurses into nested containers.  ``seen`` must
+        already include the ids of ``actual``/``expected``.  Shared by the top-level and nested paths
+        so both report dataclass fields identically.
+        """
+        entries: list[DiffEntry] = []
+        actual_names = {field.name for field in dataclasses.fields(actual)}
+        expected_names = {field.name for field in dataclasses.fields(expected)}
+        for field in sorted(actual_names | expected_names):
+            path = f"{prefix}.{field}"
+            if field not in expected_names:
+                entries.append(DiffEntry(path=path, actual=getattr(actual, field), expected=None))
+            elif field not in actual_names:
+                entries.append(DiffEntry(path=path, actual=None, expected=getattr(expected, field)))
+            else:
+                actual_value = getattr(actual, field)
+                expected_value = getattr(expected, field)
+                if actual_value != expected_value:
+                    sub_entries = BaseMixin._sub_diff_entries(actual_value, expected_value, path, _seen=seen)
+                    if sub_entries is not None:
+                        entries.extend(sub_entries)
+                    else:
+                        entries.append(DiffEntry(path=path, actual=actual_value, expected=expected_value))
+        return entries
+
     @staticmethod
     def _build_equality_diff(
         actual: object, expected: object, *, _prefix: str = "", _seen: set[int] | None = None
@@ -229,21 +315,10 @@ class BaseMixin(_MixinBase):
             and dataclasses.is_dataclass(expected)
             and not isinstance(expected, type)
         ):
-            entries = []
-            actual_names = {field.name for field in dataclasses.fields(actual)}
-            expected_names = {field.name for field in dataclasses.fields(expected)}
-            for field in sorted(actual_names | expected_names):
-                path = f"{_prefix}.{field}"
-                if field not in expected_names:
-                    entries.append(DiffEntry(path=path, actual=getattr(actual, field), expected=None))
-                elif field not in actual_names:
-                    entries.append(DiffEntry(path=path, actual=None, expected=getattr(expected, field)))
-                else:
-                    actual_value = getattr(actual, field)
-                    expected_value = getattr(expected, field)
-                    if actual_value != expected_value:
-                        entries.extend(_field_entries(actual_value, expected_value, path))
-            return DiffResult(kind="dataclass", entries=entries)
+            return DiffResult(
+                kind="dataclass",
+                entries=BaseMixin._dataclass_diff_entries(actual, expected, _prefix, _seen),
+            )
         if is_model_dump_object(actual) and is_model_dump_object(expected):
             actual_dict = actual.model_dump()
             expected_dict = expected.model_dump()
@@ -262,21 +337,10 @@ class BaseMixin(_MixinBase):
                         entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=expected_dict[key]))
             return DiffResult(kind="model", entries=entries)
         if isinstance(actual, (list, tuple)) and isinstance(expected, (list, tuple)):
-            entries = []
-            max_len = max(len(actual), len(expected))
-            for i in range(max_len):
-                path = f"{_prefix}[{i}]" if _prefix else f"[{i}]"
-                if i >= len(actual):
-                    entries.append(DiffEntry(path=path, actual=None, expected=expected[i]))
-                elif i >= len(expected):
-                    entries.append(DiffEntry(path=path, actual=actual[i], expected=None))
-                elif actual[i] != expected[i]:
-                    sub_entries = BaseMixin._sub_diff_entries(actual[i], expected[i], path, _seen=_seen)
-                    if sub_entries:
-                        entries.extend(sub_entries)
-                    else:
-                        entries.append(DiffEntry(path=path, actual=actual[i], expected=expected[i]))
-            return DiffResult(kind="sequence", entries=entries)
+            return DiffResult(
+                kind="sequence",
+                entries=BaseMixin._sequence_diff_entries(actual, expected, _prefix, _seen),
+            )
         if isinstance(actual, (set, frozenset)) and isinstance(expected, (set, frozenset)):
             entries = []
             for item in sorted(actual - expected, key=repr):
@@ -305,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)
@@ -333,23 +407,7 @@ class BaseMixin(_MixinBase):
             and not isinstance(expected, type)
         ):
             child_seen = _seen | {id(actual), id(expected)}
-            entries = []
-            for field in dataclasses.fields(actual):
-                actual_value = getattr(actual, field.name)
-                expected_value = getattr(expected, field.name, _SENTINEL)
-                if expected_value is _SENTINEL:
-                    entries.append(DiffEntry(path=f"{prefix}.{field.name}", actual=actual_value, expected=None))
-                elif actual_value != expected_value:
-                    sub_entries = BaseMixin._sub_diff_entries(
-                        actual_value, expected_value, f"{prefix}.{field.name}", _seen=child_seen
-                    )
-                    if sub_entries is not None:
-                        entries.extend(sub_entries)
-                    else:
-                        entries.append(
-                            DiffEntry(path=f"{prefix}.{field.name}", actual=actual_value, expected=expected_value)
-                        )
-            return entries or None
+            return BaseMixin._dataclass_diff_entries(actual, expected, prefix, child_seen) or None
         if is_namedtuple(actual) and is_namedtuple(expected):
             child_seen = _seen | {id(actual), id(expected)}
             entries = []
@@ -394,6 +452,9 @@ class BaseMixin(_MixinBase):
                     else:
                         entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=expected_dict[key]))
             return entries or None
+        if isinstance(actual, (list, tuple)) and isinstance(expected, (list, tuple)):
+            child_seen = _seen | {id(actual), id(expected)}
+            return BaseMixin._sequence_diff_entries(actual, expected, prefix, child_seen) or None
         return None
 
     def satisfies(self, matcher) -> Self:
@@ -488,11 +549,12 @@ class BaseMixin(_MixinBase):
         return self
 
     def matches_structure(self, spec: dict[Any, Any]) -> Self:
-        """Asserts that val is a dict matching the given structure specification.
+        """Asserts that val matches the given structure specification.
 
-        Each key in ``spec`` maps to either a :class:`~assertpy2.matchers.Matcher`, a raw value
-        (checked via ``==``), or a nested ``dict`` for recursive matching.  Extra keys in val
-        that are absent from the spec are allowed.
+        ``val`` may be a dict or a pydantic-style model (anything exposing ``model_dump()``), which is
+        normalized to its dict before matching.  Each key in ``spec`` maps to either a
+        :class:`~assertpy2.matchers.Matcher`, a raw value (checked via ``==``), or a nested ``dict``
+        for recursive matching.  Extra keys in val that are absent from the spec are allowed.
 
         Args:
             spec: a dict where values can be Matcher instances, raw values, or nested dicts
@@ -515,7 +577,7 @@ class BaseMixin(_MixinBase):
         Raises:
             AssertionError: if val does **not** match the structure spec
         """
-        if not isinstance(self.val, dict):
+        if not isinstance(self.val, dict) and not is_model_dump_object(self.val):
             raise TypeError("val must be a dict")
         if not isinstance(spec, dict):
             raise TypeError("given arg must be a dict")
@@ -697,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