assertpy2 2.7.0__tar.gz → 2.8.1__tar.gz

{assertpy2-2.7.0 → assertpy2-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.7.0
+Version: 2.8.1
 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
@@ -66,7 +66,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-## Quick start
+## [Quick start](https://solganis.github.io/assertpy2/getting-started/)
 
 ```bash
 pip install assertpy2  # drop-in replacement for assertpy, just change the import
@@ -84,27 +84,48 @@ def test_user():
     assert_that(user).has_name("Alice")
 ```
 
-## Why fluent assertions?
+Browse the [full documentation](https://solganis.github.io/assertpy2/) for every assertion, matcher, and integration.
 
-```py
-# bare assert - passes, but failure message is useless
-assert user["age"] >= 18
-# AssertionError
+## [Why fluent assertions?](https://solganis.github.io/assertpy2/comparison/)
 
-# assertpy2 - same check, clear failure message
-assert_that(user["age"]).is_greater_than_or_equal_to(18)
-# AssertionError: Expected <16> to be greater than or equal to <18>, but was not.
+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/):
 
-# bare assert - three separate statements
+```py
+# bare - three statements, no autocomplete help
 assert isinstance(items, list)
 assert len(items) == 3
 assert "admin" in items
 
-# assertpy2 - one fluent chain
+# assertpy2 - one chain, type-aware autocomplete
 assert_that(items).is_type_of(list).is_length(3).contains("admin")
 ```
 
-## Type-aware autocomplete
+The real difference shows up when a test fails. Here a nested response has two wrong
+fields. Plain `assert` dumps both structures and leaves you to find them:
+
+```text
+assert response == expected
+E   AssertionError: assert {'id': 1, ...} == {'id': 1, ...}
+E     Omitting 1 identical items, use -vv to show
+E     Differing items:
+E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Alice', 'role': 'admin'}}
+E     {'status': 'active'} != {'status': 'disabled'}
+```
+
+assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs), in color:
+
+```python
+assert_that(response).is_equal_to(expected)
+```
+
+<img src="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">
+
+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/)
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
 Your IDE shows only methods relevant to the value you're testing, not all 100+:
@@ -117,6 +138,8 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 
 9 type-specific Protocols instead of one `Any`. Works in PyCharm, VS Code, and any LSP-compatible editor.
 
+See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) guide for the full walkthrough.
+
 ---
 
 ## Features
@@ -124,7 +147,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 **Fluent API**
 
 - [**Composable matchers**](https://solganis.github.io/assertpy2/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
-- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation, reporting the exact path to each mismatch on failure.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
@@ -143,8 +166,9 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
 - [**Async assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` with polling/retry for eventual consistency.
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
-- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models. Circular reference protection.
+- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
+- **Property-based tested**: comparison, selective-diff, matcher algebra, and collection logic are checked with [Hypothesis](https://hypothesis.readthedocs.io) against reference semantics, on top of 100% branch coverage.
 
 **Type safety**
 
@@ -166,7 +190,7 @@ See the [full documentation](https://solganis.github.io/assertpy2/) for all asse
 
 ---
 
-## Integrations
+## [Integrations](https://solganis.github.io/assertpy2/integrations/)
 
 ### Allure
 
@@ -214,6 +238,8 @@ def step_impl(context, age):
 
 Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
 
+See the [Integrations guide](https://solganis.github.io/assertpy2/integrations/) for attachment modes, configuration, and full examples.
+
 ---
 
 <p align="center">

{assertpy2-2.7.0 → assertpy2-2.8.1}/README.md

@@ -28,7 +28,7 @@
 
 ---
 
-## Quick start
+## [Quick start](https://solganis.github.io/assertpy2/getting-started/)
 
 ```bash
 pip install assertpy2  # drop-in replacement for assertpy, just change the import
@@ -46,27 +46,48 @@ def test_user():
     assert_that(user).has_name("Alice")
 ```
 
-## Why fluent assertions?
+Browse the [full documentation](https://solganis.github.io/assertpy2/) for every assertion, matcher, and integration.
 
-```py
-# bare assert - passes, but failure message is useless
-assert user["age"] >= 18
-# AssertionError
+## [Why fluent assertions?](https://solganis.github.io/assertpy2/comparison/)
 
-# assertpy2 - same check, clear failure message
-assert_that(user["age"]).is_greater_than_or_equal_to(18)
-# AssertionError: Expected <16> to be greater than or equal to <18>, but was not.
+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/):
 
-# bare assert - three separate statements
+```py
+# bare - three statements, no autocomplete help
 assert isinstance(items, list)
 assert len(items) == 3
 assert "admin" in items
 
-# assertpy2 - one fluent chain
+# assertpy2 - one chain, type-aware autocomplete
 assert_that(items).is_type_of(list).is_length(3).contains("admin")
 ```
 
-## Type-aware autocomplete
+The real difference shows up when a test fails. Here a nested response has two wrong
+fields. Plain `assert` dumps both structures and leaves you to find them:
+
+```text
+assert response == expected
+E   AssertionError: assert {'id': 1, ...} == {'id': 1, ...}
+E     Omitting 1 identical items, use -vv to show
+E     Differing items:
+E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Alice', 'role': 'admin'}}
+E     {'status': 'active'} != {'status': 'disabled'}
+```
+
+assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs), in color:
+
+```python
+assert_that(response).is_equal_to(expected)
+```
+
+<img src="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">
+
+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/)
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
 Your IDE shows only methods relevant to the value you're testing, not all 100+:
@@ -79,6 +100,8 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 
 9 type-specific Protocols instead of one `Any`. Works in PyCharm, VS Code, and any LSP-compatible editor.
 
+See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) guide for the full walkthrough.
+
 ---
 
 ## Features
@@ -86,7 +109,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 **Fluent API**
 
 - [**Composable matchers**](https://solganis.github.io/assertpy2/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
-- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation, reporting the exact path to each mismatch on failure.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
@@ -105,8 +128,9 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
 - [**Async assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` with polling/retry for eventual consistency.
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
-- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models. Circular reference protection.
+- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
+- **Property-based tested**: comparison, selective-diff, matcher algebra, and collection logic are checked with [Hypothesis](https://hypothesis.readthedocs.io) against reference semantics, on top of 100% branch coverage.
 
 **Type safety**
 
@@ -128,7 +152,7 @@ See the [full documentation](https://solganis.github.io/assertpy2/) for all asse
 
 ---
 
-## Integrations
+## [Integrations](https://solganis.github.io/assertpy2/integrations/)
 
 ### Allure
 
@@ -176,6 +200,8 @@ def step_impl(context, age):
 
 Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
 
+See the [Integrations guide](https://solganis.github.io/assertpy2/integrations/) for attachment modes, configuration, and full examples.
+
 ---
 
 <p align="center">

assertpy2-2.8.1/assertpy2/_introspection.py

@@ -0,0 +1,66 @@
+"""Runtime-checkable protocols for duck-typed object introspection.
+
+The comparison and diff code accepts arbitrary user objects, so it inspects them structurally: pydantic
+models (``model_dump``), ``attrs`` classes (``__attrs_attrs__``) and namedtuples (``_fields`` /
+``_asdict``).  Expressing those shapes as ``@runtime_checkable`` protocols lets the diff code use
+``isinstance`` checks the type checker can follow - narrowing the value instead of probing it with
+``hasattr`` and then suppressing the attribute access.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeGuard, runtime_checkable
+
+
+@runtime_checkable
+class SupportsModelDump(Protocol):
+    """A pydantic-style model exposing ``model_dump()``."""
+
+    def model_dump(self) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class NamedTupleLike(Protocol):
+    """A ``collections.namedtuple`` / ``typing.NamedTuple`` instance."""
+
+    _fields: tuple[str, ...]
+
+    def _asdict(self) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class AttrsInstance(Protocol):
+    """An ``attrs``-decorated instance exposing ``__attrs_attrs__``."""
+
+    __attrs_attrs__: tuple[Any, ...]
+
+
+@runtime_checkable
+class MappingLike(Protocol):
+    """A dict-like object that can be iterated over and subscripted by key."""
+
+    def keys(self) -> Any: ...
+
+    def __iter__(self) -> Any: ...
+
+    def __getitem__(self, key: Any) -> Any: ...
+
+
+def is_model_dump_object(obj: object) -> TypeGuard[SupportsModelDump]:
+    """Return whether ``obj`` exposes a callable ``model_dump()`` (e.g. a pydantic model)."""
+    return isinstance(obj, SupportsModelDump) and callable(obj.model_dump)
+
+
+def is_namedtuple(obj: object) -> TypeGuard[NamedTupleLike]:
+    """Return whether ``obj`` is a namedtuple instance (a ``tuple`` carrying ``_fields``/``_asdict``)."""
+    return isinstance(obj, tuple) and isinstance(obj, NamedTupleLike)
+
+
+def is_attrs_instance(obj: object) -> TypeGuard[AttrsInstance]:
+    """Return whether ``obj`` is an ``attrs``-decorated instance."""
+    return isinstance(obj, AttrsInstance)
+
+
+def is_mapping_like(obj: object) -> TypeGuard[MappingLike]:
+    """Return whether ``obj`` is dict-like: iterable with ``keys()`` and ``[]`` access."""
+    return isinstance(obj, MappingLike) and callable(obj.keys)

{assertpy2-2.7.0 → assertpy2-2.8.1}/assertpy2/_mixin_base.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-import logging
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
+    import logging
+
     from ._compat import Self
     from .errors import DiffResult
 

{assertpy2-2.7.0 → assertpy2-2.8.1}/assertpy2/assertpy.py

@@ -9,17 +9,18 @@ import logging
 import os
 import sys
 import types
-from collections.abc import Callable, Iterator
-from typing import TYPE_CHECKING, overload
+from typing import TYPE_CHECKING, Final, overload
 
 if TYPE_CHECKING:
     import datetime
     import pathlib
+    from collections.abc import Callable, Iterator
 
     from ._compat import Self
     from ._typing import (
         _BytesAssertion,
         _CallableAssertion,
+        _CoreAssertion,
         _DateAssertion,
         _DictAssertion,
         _IterableAssertion,
@@ -47,13 +48,13 @@ from .snapshot import SnapshotMixin
 from .string import StringMixin
 from .warning import WarningMixin
 
-__version__ = "2.7.0"
+__version__ = "2.8.1"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
 
 # assertpy files
-ASSERTPY_FILES = [
+ASSERTPY_FILES: Final = [
     os.path.join("assertpy2", file)
     for file in [
         "assertpy.py",
@@ -253,11 +254,16 @@ def assert_that(val: bytes | bytearray, description: str = "") -> _BytesAssertio
 def assert_that(val: Callable[..., object], description: str = "") -> _CallableAssertion: ...
 
 
+# Fallback returns the concrete AssertionBuilder so object- and union-typed values keep the full API.
+# The specific protocols are not assignable to AssertionBuilder, so mypy --strict reports overload-overlap
+# for each specific overload and pyright one reportOverlappingOverload; ty (the gate) does not flag it. Kept
+# intentionally - returning _CoreAssertion here would strip type-specific assertions from object/union values.
 @overload
 def assert_that(val: object, description: str = "") -> AssertionBuilder: ...
 
 
-def assert_that(val, description=""):
+# Return the common base protocol so each overload stays consistent with the impl (no reportInconsistentOverload).
+def assert_that(val, description="") -> _CoreAssertion:
     """Set the value to be tested, plus an optional description, and allow assertions to be called.
 
     This is a factory method for the :class:`AssertionBuilder`, and the single most important

{assertpy2-2.7.0 → assertpy2-2.8.1}/assertpy2/async_assertions.py

@@ -69,7 +69,7 @@ class AsyncAssertionBuilder:
                         method = getattr(builder, name)
                         method(*args, **kwargs)
                         return builder
-                    except AssertionError as exc:
+                    except AssertionError as exc:  # noqa: PERF203  # retry-on-failure needs the try/except per poll iteration
                         last_error = exc
                         if loop.time() >= deadline:
                             raise AssertionError(

{assertpy2-2.7.0 → assertpy2-2.8.1}/assertpy2/base.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import collections.abc
 import dataclasses
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Final
 
+from ._introspection import is_model_dump_object, is_namedtuple
 from ._mixin_base import _MixinBase
 from .errors import DiffEntry, DiffResult
 from .matchers import Matcher, StructureMatcher
@@ -13,11 +14,7 @@ if TYPE_CHECKING:
 
 __tracebackhide__ = True
 
-_SENTINEL = object()
-
-
-def _is_model_dump_object(obj: object) -> bool:
-    return hasattr(obj, "model_dump") and callable(obj.model_dump)
+_SENTINEL: Final = object()
 
 
 class BaseMixin(_MixinBase):
@@ -80,7 +77,9 @@ class BaseMixin(_MixinBase):
                 assert_that({'a': 1, 'b': 2, 'c': 3}).is_equal_to({'a': 1}, ignore=['b', 'c'])
 
                 # ignore nested keys
-                assert_that({'a': {'b': 2, 'c': 3, 'd': 4}}).is_equal_to({'a': {'d': 4}}, ignore=[('a', 'b'), ('a', 'c')])
+                assert_that({'a': {'b': 2, 'c': 3, 'd': 4}}).is_equal_to(
+                    {'a': {'d': 4}}, ignore=[('a', 'b'), ('a', 'c')]
+                )
 
             When the val is *dict-like*, only certain keys can be *included* when checking equality::
 
@@ -133,8 +132,8 @@ class BaseMixin(_MixinBase):
             if self._dict_not_equal(self.val, other, ignore=ignore, include=include):
                 self._dict_err(self.val, other, ignore=ignore, include=include)
         elif ignore or include:
-            val_is_namedtuple = isinstance(self.val, tuple) and hasattr(self.val, "_fields")
-            other_is_namedtuple = isinstance(other, tuple) and hasattr(other, "_fields")
+            val_is_namedtuple = is_namedtuple(self.val)
+            other_is_namedtuple = is_namedtuple(other)
             if (
                 isinstance(self.val, (list, tuple))
                 and isinstance(other, (list, tuple))
@@ -208,14 +207,9 @@ class BaseMixin(_MixinBase):
                 return sub_entries
             return [DiffEntry(path=path, actual=actual_value, expected=expected_value)]
 
-        if (
-            hasattr(actual, "_fields")
-            and isinstance(actual, tuple)
-            and hasattr(expected, "_fields")
-            and isinstance(expected, tuple)
-        ):
+        if is_namedtuple(actual) and is_namedtuple(expected):
             entries: list[DiffEntry] = []
-            for field in actual._fields:  # ty: ignore[not-iterable]  # guarded by hasattr check above
+            for field in actual._fields:
                 actual_value = getattr(actual, field)
                 expected_value = getattr(expected, field, _SENTINEL)
                 path = f"{_prefix}.{field}"
@@ -223,9 +217,11 @@ class BaseMixin(_MixinBase):
                     entries.append(DiffEntry(path=path, actual=actual_value, expected=None))
                 elif actual_value != expected_value:
                     entries.extend(_field_entries(actual_value, expected_value, path))
-            for field in expected._fields:  # ty: ignore[not-iterable]  # guarded by hasattr check above
-                if not hasattr(actual, field):
-                    entries.append(DiffEntry(path=f"{_prefix}.{field}", actual=None, expected=getattr(expected, field)))
+            entries.extend(
+                DiffEntry(path=f"{_prefix}.{field}", actual=None, expected=getattr(expected, field))
+                for field in expected._fields
+                if not hasattr(actual, field)
+            )
             return DiffResult(kind="namedtuple", entries=entries)
         if (
             dataclasses.is_dataclass(actual)
@@ -248,9 +244,9 @@ class BaseMixin(_MixinBase):
                     if actual_value != expected_value:
                         entries.extend(_field_entries(actual_value, expected_value, path))
             return DiffResult(kind="dataclass", entries=entries)
-        if _is_model_dump_object(actual) and _is_model_dump_object(expected):
-            actual_dict = actual.model_dump()  # ty: ignore[unresolved-attribute]  # guarded by _is_model_dump_object check above
-            expected_dict = expected.model_dump()  # ty: ignore[unresolved-attribute]  # guarded by _is_model_dump_object check above
+        if is_model_dump_object(actual) and is_model_dump_object(expected):
+            actual_dict = actual.model_dump()
+            expected_dict = expected.model_dump()
             entries = []
             for key in sorted(set(actual_dict) | set(expected_dict)):
                 path = f"{_prefix}.{key}" if _prefix else f".{key}"
@@ -354,37 +350,34 @@ class BaseMixin(_MixinBase):
                             DiffEntry(path=f"{prefix}.{field.name}", actual=actual_value, expected=expected_value)
                         )
             return entries or None
-        if (
-            hasattr(actual, "_fields")
-            and isinstance(actual, tuple)
-            and hasattr(expected, "_fields")
-            and isinstance(expected, tuple)
-        ):
+        if is_namedtuple(actual) and is_namedtuple(expected):
             child_seen = _seen | {id(actual), id(expected)}
             entries = []
-            for field in actual._fields:  # ty: ignore[not-iterable]  # guarded by hasattr check above
-                actual_value = getattr(actual, field)
-                expected_value = getattr(expected, field, _SENTINEL)
+            for field_name in actual._fields:
+                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}", actual=actual_value, expected=None))
+                    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}", _seen=child_seen
+                        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}", actual=actual_value, expected=expected_value)
+                            DiffEntry(path=f"{prefix}.{field_name}", actual=actual_value, expected=expected_value)
                         )
-            for field in expected._fields:  # ty: ignore[not-iterable]  # guarded by hasattr check above
-                if not hasattr(actual, field):
-                    entries.append(DiffEntry(path=f"{prefix}.{field}", actual=None, expected=getattr(expected, field)))
+            for field_name in expected._fields:
+                if not hasattr(actual, field_name):
+                    entries.append(
+                        DiffEntry(path=f"{prefix}.{field_name}", actual=None, expected=getattr(expected, field_name))
+                    )
             return entries or None
-        if _is_model_dump_object(actual) and _is_model_dump_object(expected):
+        if is_model_dump_object(actual) and is_model_dump_object(expected):
             child_seen = _seen | {id(actual), id(expected)}
-            actual_dict = actual.model_dump()  # ty: ignore[unresolved-attribute]  # guarded by _is_model_dump_object check above
-            expected_dict = expected.model_dump()  # ty: ignore[unresolved-attribute]  # guarded by _is_model_dump_object check above
+            actual_dict = actual.model_dump()
+            expected_dict = expected.model_dump()
             entries = []
             for key in sorted(set(actual_dict) | set(expected_dict)):
                 path = f"{prefix}.{key}"
@@ -430,7 +423,13 @@ class BaseMixin(_MixinBase):
         """
         if isinstance(matcher, Matcher):
             if not matcher.matches(self.val):
-                return self.error(f"Expected {matcher.describe()}, but {matcher.describe_mismatch(self.val)}.")
+                description = matcher.describe()
+                return self.error(
+                    f"Expected {description}, but {matcher.describe_mismatch(self.val)}.",
+                    actual=self.val,
+                    expected=description,
+                    diff=DiffResult(kind="match", entries=[DiffEntry(path=".", actual=self.val, expected=description)]),
+                )
         elif callable(matcher):
             if not matcher(self.val):
                 return self.error(f"Expected <{self.val}> to satisfy <{matcher}>, but did not.")
@@ -466,11 +465,17 @@ class BaseMixin(_MixinBase):
         if not isinstance(self.val, collections.abc.Iterable):
             raise TypeError("val is not iterable")
         if isinstance(matcher, Matcher):
+            description = matcher.describe()
             for i, item in enumerate(self.val):
                 if not matcher.matches(item):
                     return self.error(
-                        f"Expected all items to satisfy {matcher.describe()}, but item at index {i} <{item}> did not:"
-                        f" {matcher.describe_mismatch(item)}."
+                        f"Expected all items to satisfy {description}, but item at index {i} <{item}> did not:"
+                        f" {matcher.describe_mismatch(item)}.",
+                        actual=item,
+                        expected=description,
+                        diff=DiffResult(
+                            kind="match", entries=[DiffEntry(path=f"[{i}]", actual=item, expected=description)]
+                        ),
                     )
         elif callable(matcher):
             for i, item in enumerate(self.val):
@@ -482,7 +487,7 @@ class BaseMixin(_MixinBase):
             raise TypeError("given arg must be a Matcher or callable")
         return self
 
-    def matches_structure(self, spec: dict) -> Self:
+    def matches_structure(self, spec: dict[Any, Any]) -> Self:
         """Asserts that val is a dict matching the given structure specification.
 
         Each key in ``spec`` maps to either a :class:`~assertpy2.matchers.Matcher`, a raw value
@@ -515,10 +520,17 @@ class BaseMixin(_MixinBase):
         if not isinstance(spec, dict):
             raise TypeError("given arg must be a dict")
         matcher = StructureMatcher(spec)
-        if not matcher.matches(self.val):
+        mismatches = matcher.collect_mismatches(self.val)
+        if mismatches:
+            entries = [
+                DiffEntry(path=path, actual=actual, expected=description) for path, actual, description in mismatches
+            ]
             return self.error(
                 f"Expected <{self.val}> to match structure {matcher.describe()}, but"
-                f" {matcher.describe_mismatch(self.val)}."
+                f" {matcher.describe_mismatch(self.val)}.",
+                actual=self.val,
+                expected=spec,
+                diff=DiffResult(kind="match", entries=entries),
             )
         return self
 

{assertpy2-2.7.0 → assertpy2-2.8.1}/assertpy2/behave_matchers.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
-_BOOL_TRUE = frozenset({"true", "yes", "1", "on"})
-_BOOL_FALSE = frozenset({"false", "no", "0", "off"})
+from types import MappingProxyType
+from typing import Final
+
+_BOOL_TRUE: Final = frozenset({"true", "yes", "1", "on"})
+_BOOL_FALSE: Final = frozenset({"false", "no", "0", "off"})
 
 
 def _with_pattern(pattern):
@@ -51,13 +54,15 @@ def _bool_like(text):
     raise ValueError(f"expected boolean-like value, got {text!r}")
 
 
-ASSERTPY_TYPES = {
-    "PositiveInt": _positive_int,
-    "NonNegativeInt": _non_negative_int,
-    "PositiveFloat": _positive_float,
-    "NonEmptyString": _non_empty_string,
-    "BoolLike": _bool_like,
-}
+ASSERTPY_TYPES: Final = MappingProxyType(
+    {
+        "PositiveInt": _positive_int,
+        "NonNegativeInt": _non_negative_int,
+        "PositiveFloat": _positive_float,
+        "NonEmptyString": _non_empty_string,
+        "BoolLike": _bool_like,
+    }
+)
 
 
 def register_assertpy_types() -> None: