assertpy2 2.24.0__tar.gz → 2.25.0__tar.gz

{assertpy2-2.24.0 → assertpy2-2.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.24.0
+Version: 2.25.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
@@ -30,13 +30,13 @@ Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
 Provides-Extra: allure
 Requires-Dist: allure-pytest>=2.13; extra == 'allure'
 Provides-Extra: behave
-Requires-Dist: behave>=1.2.6; extra == 'behave'
+Requires-Dist: behave>=1.3.0; 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: inline
-Requires-Dist: asttokens>=2.0; extra == 'inline'
+Requires-Dist: asttokens>=2.0.4; extra == 'inline'
 Requires-Dist: executing>=2.2; extra == 'inline'
 Provides-Extra: json
 Requires-Dist: jsonpath-ng>=1.8; extra == 'json'
@@ -130,7 +130,7 @@ Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI respons
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
 
-`assert` states a condition well, and pytest reports it well.
+`assert` states a condition well. pytest reports it well.
 
 What it cannot say is *where* two structures differ. It prints both and leaves the reading to you:
 
@@ -154,12 +154,12 @@ 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>
 
-It recurses through nested containers, and matcher predicates get the same treatment.
+It recurses through nested containers. Matcher predicates get the same treatment.
 
 For dynamic fields like IDs, assert a subset with
 [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
 
-The chain is the other half: one statement carries the whole intent, and your IDE offers only the
+The chain is the other half. Your IDE offers only the
 [methods that fit the value](https://solganis.github.io/assertpy2/concepts/type-safety/).
 
 <!-- docs-guard: skip -->
@@ -169,7 +169,7 @@ assert_that(items).is_instance_of(list).is_length(3).contains("admin")
 
 Matchers are ordinary values that answer `==`, the way `unittest.mock.ANY` does.
 
-Nothing is patched, so a matcher can sit inside the expected structure itself, at any depth:
+Nothing is patched, so a matcher can sit inside the expected structure at any depth:
 
 ```python
 response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
@@ -210,7 +210,7 @@ Your IDE shows only methods relevant to the value you're testing, not the whole
 - `assert_that(b"\x89PNG").` &rarr; bytes methods: `starts_with_bytes`, `is_valid_utf8`, `decoded_as`, ...
 
 15 type-specific Protocols instead of one `Any`.<br>
-Works in PyCharm, VS Code, and any LSP-compatible editor.
+Works in PyCharm, VS Code, and any editor that runs a type checker.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/concepts/type-safety/#typed-narrowing-with-value">Typed narrowing</a></h2>
 
@@ -235,7 +235,7 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting">A failure you can read from code</a></h2>
 
-An exception is the right default, and a dead end for anything that wants to read the result.
+An exception is the right default. Reading the result means catching it.
 
 `check()` runs the next assertion for its verdict instead:
 
@@ -250,11 +250,11 @@ if not outcome and outcome.diff:
 ```
 
 It is truthy when the assertion held. When it did not, it carries `.message`, `.actual`, `.expected`
-and a walkable `.diff`, and so does `AssertionFailure`.
+and a walkable `.diff`. So does `AssertionFailure`.
 
 So a reporter reads structure instead of parsing a string. That is how the
-[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works, and it
-is open to anything else you build.
+[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works.
+Anything else you build can too.
 
 <h2 align="center">Features</h2>
 
@@ -262,8 +262,6 @@ is open to anything else you build.
 
 - [**Structural matching**](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching): `matches_structure()` for declarative dict/API-response validation.
 - [**Recursive field assertions**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph.
-- [**Vacuous-assertion guard**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-checked-nothing): `--assertpy2-vacuous` warns when a universal assertion passes over an empty collection, having checked nothing.
-- [**Dangling-assertion detector**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-never-ran): `--assertpy2-dangling` warns when a chain builds an assertion and never runs it. `assert assert_that(x).is_positive` passes on any value, and neither ruff nor coverage sees it.
 - [**Universal negation**](https://solganis.github.io/assertpy2/guides/fluent/#universal-negation): `.not_` inverts any assertion, no dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/guides/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/guides/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`, plus `*_in_any_order` variants.
@@ -281,6 +279,7 @@ is open to anything else you build.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/guides/assertions/#selective-comparison-ignore--include): `is_equal_to(ignore=..., include=...)` for selective key/field matching by name, regex, or type.
 - [**Recursive comparison**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance`, `comparators`, or `ignore_null` for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/guides/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
+- [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 
 **Testing**
 
@@ -288,17 +287,28 @@ is open to anything else you build.
 - [**Polling assertions**](https://solganis.github.io/assertpy2/guides/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace on timeout.
 - [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), search an `ExceptionGroup` (`contains_error()`, `errors()`, `error_of()`), or pivot to the object (`raised()`).
 - [**HTTP responses**](https://solganis.github.io/assertpy2/recipes/#test-an-http-api-response): assert on the response itself and every failure names the request it came from, with `decoded_as_json()` to step into the body. No client library is a dependency.
+- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): an external JSON file, an [inline](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) value recorded into the test source, or a [value-tolerant contract](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots), all updated with `--assertpy2-snapshot-update`.
+- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi()` checks a JSON body against an operation's response schema, reporting every violation with its JSON path.
+
+**Failure reporting**
+
 - [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected` and `.diff`, and the diff renders into the message, so it shows off pytest too.
 - [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, handing back an `AssertionOutcome`.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive diffs across containers, dataclasses, attrs and Pydantic models, with intra-line carets for strings.
-- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): an external JSON file, an [inline](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) value recorded into the test source, or a [value-tolerant contract](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots), all updated with `--assertpy2-snapshot-update`.
-- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi()` checks a JSON body against an operation's response schema, reporting every violation with its JSON path.
+
+**Plugin for pytest**
+
+Set from the command line or from `[tool.pytest.ini_options]`, not from a call.
+
+- [**Failure clustering**](https://solganis.github.io/assertpy2/guides/errors/#what-the-failures-had-in-common): forty failing tests are usually not forty problems. Where three or more differ at the same place, the run ends with a line saying where. On by default, `assertpy2_failure_clusters = "off"` turns it off.
+- [**Diagnostic profiles**](https://solganis.github.io/assertpy2/guides/errors/#configuration): `assertpy2_profile` turns the guards below on in one line. `compatible` (default) leaves them off, `safe` warns, `strict` fails the tests they find. A setting you name yourself still wins.
+- [**Vacuous-assertion guard**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-checked-nothing): `--assertpy2-vacuous` warns when a universal assertion passes over an empty collection, having checked nothing.
+- [**Dangling-assertion detector**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-never-ran): `--assertpy2-dangling` warns when a chain builds an assertion and never runs it. `assert assert_that(x).is_positive` passes on any value, and neither ruff nor coverage sees it.
 
 **Extensibility**
 
 - [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` composes existing ones, `BaseMatcher` carries its own predicate. Both compose with `&`, `|`, `~`.
 - [**Custom assertions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` adds a method to the builder.
-- [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/extending/integrations/">Integrations</a></h2>
 

{assertpy2-2.24.0 → assertpy2-2.25.0}/README.md

@@ -78,7 +78,7 @@ Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI respons
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
 
-`assert` states a condition well, and pytest reports it well.
+`assert` states a condition well. pytest reports it well.
 
 What it cannot say is *where* two structures differ. It prints both and leaves the reading to you:
 
@@ -102,12 +102,12 @@ 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>
 
-It recurses through nested containers, and matcher predicates get the same treatment.
+It recurses through nested containers. Matcher predicates get the same treatment.
 
 For dynamic fields like IDs, assert a subset with
 [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
 
-The chain is the other half: one statement carries the whole intent, and your IDE offers only the
+The chain is the other half. Your IDE offers only the
 [methods that fit the value](https://solganis.github.io/assertpy2/concepts/type-safety/).
 
 <!-- docs-guard: skip -->
@@ -117,7 +117,7 @@ assert_that(items).is_instance_of(list).is_length(3).contains("admin")
 
 Matchers are ordinary values that answer `==`, the way `unittest.mock.ANY` does.
 
-Nothing is patched, so a matcher can sit inside the expected structure itself, at any depth:
+Nothing is patched, so a matcher can sit inside the expected structure at any depth:
 
 ```python
 response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
@@ -158,7 +158,7 @@ Your IDE shows only methods relevant to the value you're testing, not the whole
 - `assert_that(b"\x89PNG").` &rarr; bytes methods: `starts_with_bytes`, `is_valid_utf8`, `decoded_as`, ...
 
 15 type-specific Protocols instead of one `Any`.<br>
-Works in PyCharm, VS Code, and any LSP-compatible editor.
+Works in PyCharm, VS Code, and any editor that runs a type checker.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/concepts/type-safety/#typed-narrowing-with-value">Typed narrowing</a></h2>
 
@@ -183,7 +183,7 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting">A failure you can read from code</a></h2>
 
-An exception is the right default, and a dead end for anything that wants to read the result.
+An exception is the right default. Reading the result means catching it.
 
 `check()` runs the next assertion for its verdict instead:
 
@@ -198,11 +198,11 @@ if not outcome and outcome.diff:
 ```
 
 It is truthy when the assertion held. When it did not, it carries `.message`, `.actual`, `.expected`
-and a walkable `.diff`, and so does `AssertionFailure`.
+and a walkable `.diff`. So does `AssertionFailure`.
 
 So a reporter reads structure instead of parsing a string. That is how the
-[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works, and it
-is open to anything else you build.
+[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works.
+Anything else you build can too.
 
 <h2 align="center">Features</h2>
 
@@ -210,8 +210,6 @@ is open to anything else you build.
 
 - [**Structural matching**](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching): `matches_structure()` for declarative dict/API-response validation.
 - [**Recursive field assertions**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph.
-- [**Vacuous-assertion guard**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-checked-nothing): `--assertpy2-vacuous` warns when a universal assertion passes over an empty collection, having checked nothing.
-- [**Dangling-assertion detector**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-never-ran): `--assertpy2-dangling` warns when a chain builds an assertion and never runs it. `assert assert_that(x).is_positive` passes on any value, and neither ruff nor coverage sees it.
 - [**Universal negation**](https://solganis.github.io/assertpy2/guides/fluent/#universal-negation): `.not_` inverts any assertion, no dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/guides/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/guides/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`, plus `*_in_any_order` variants.
@@ -229,6 +227,7 @@ is open to anything else you build.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/guides/assertions/#selective-comparison-ignore--include): `is_equal_to(ignore=..., include=...)` for selective key/field matching by name, regex, or type.
 - [**Recursive comparison**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance`, `comparators`, or `ignore_null` for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/guides/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
+- [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 
 **Testing**
 
@@ -236,17 +235,28 @@ is open to anything else you build.
 - [**Polling assertions**](https://solganis.github.io/assertpy2/guides/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace on timeout.
 - [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), search an `ExceptionGroup` (`contains_error()`, `errors()`, `error_of()`), or pivot to the object (`raised()`).
 - [**HTTP responses**](https://solganis.github.io/assertpy2/recipes/#test-an-http-api-response): assert on the response itself and every failure names the request it came from, with `decoded_as_json()` to step into the body. No client library is a dependency.
+- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): an external JSON file, an [inline](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) value recorded into the test source, or a [value-tolerant contract](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots), all updated with `--assertpy2-snapshot-update`.
+- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi()` checks a JSON body against an operation's response schema, reporting every violation with its JSON path.
+
+**Failure reporting**
+
 - [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected` and `.diff`, and the diff renders into the message, so it shows off pytest too.
 - [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, handing back an `AssertionOutcome`.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive diffs across containers, dataclasses, attrs and Pydantic models, with intra-line carets for strings.
-- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): an external JSON file, an [inline](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) value recorded into the test source, or a [value-tolerant contract](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots), all updated with `--assertpy2-snapshot-update`.
-- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi()` checks a JSON body against an operation's response schema, reporting every violation with its JSON path.
+
+**Plugin for pytest**
+
+Set from the command line or from `[tool.pytest.ini_options]`, not from a call.
+
+- [**Failure clustering**](https://solganis.github.io/assertpy2/guides/errors/#what-the-failures-had-in-common): forty failing tests are usually not forty problems. Where three or more differ at the same place, the run ends with a line saying where. On by default, `assertpy2_failure_clusters = "off"` turns it off.
+- [**Diagnostic profiles**](https://solganis.github.io/assertpy2/guides/errors/#configuration): `assertpy2_profile` turns the guards below on in one line. `compatible` (default) leaves them off, `safe` warns, `strict` fails the tests they find. A setting you name yourself still wins.
+- [**Vacuous-assertion guard**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-checked-nothing): `--assertpy2-vacuous` warns when a universal assertion passes over an empty collection, having checked nothing.
+- [**Dangling-assertion detector**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-never-ran): `--assertpy2-dangling` warns when a chain builds an assertion and never runs it. `assert assert_that(x).is_positive` passes on any value, and neither ruff nor coverage sees it.
 
 **Extensibility**
 
 - [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` composes existing ones, `BaseMatcher` carries its own predicate. Both compose with `&`, `|`, `~`.
 - [**Custom assertions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` adds a method to the builder.
-- [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/extending/integrations/">Integrations</a></h2>
 

{assertpy2-2.24.0 → assertpy2-2.25.0}/assertpy2/_engine/_builder_check_typing.py

@@ -26,7 +26,7 @@ if TYPE_CHECKING:
     from .._matcher_impls import ClassInfo
     from ..matchers import Matcher
     from ..outcome import AssertionOutcome
-    from ._capable_typing import _Callable, _Orderable, _PathLike
+    from ._capable_typing import _Callable, _Keyed, _KeyedWithItems, _KeyedWithValues, _Orderable, _PathLike
     from ._introspection import MappingLike
     from ._typing import (
         _U,
@@ -906,29 +906,33 @@ if TYPE_CHECKING:
         @overload
         def contains_key(self: _CheckAnyValue[dict[_K, _V]], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
         @overload
-        def contains_key(self: _CheckAnyValue[_CapableT], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
+        def contains_key(self: _CheckAnyValue[_Keyed], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
 
         @overload
         def does_not_contain_key(self: _CheckAnyValue[dict[_K, _V]], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
         @overload
-        def does_not_contain_key(self: _CheckAnyValue[_CapableT], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
+        def does_not_contain_key(self: _CheckAnyValue[_Keyed], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
 
         @overload
         def contains_value(self: _CheckAnyValue[dict[_K, _V]], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
         @overload
-        def contains_value(self: _CheckAnyValue[_CapableT], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
+        def contains_value(self: _CheckAnyValue[_KeyedWithValues], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
 
         @overload
         def does_not_contain_value(
             self: _CheckAnyValue[dict[_K, _V]], *values: _V | Matcher[_V]
         ) -> AssertionOutcome: ...
         @overload
-        def does_not_contain_value(self: _CheckAnyValue[_CapableT], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
+        def does_not_contain_value(
+            self: _CheckAnyValue[_KeyedWithValues], *values: _V | Matcher[_V]
+        ) -> AssertionOutcome: ...
 
         @overload
         def contains_entry(self: _CheckAnyValue[dict[_K, _V]], *args: object, **kwargs: object) -> AssertionOutcome: ...
         @overload
-        def contains_entry(self: _CheckAnyValue[_CapableT], *args: object, **kwargs: object) -> AssertionOutcome: ...
+        def contains_entry(
+            self: _CheckAnyValue[_KeyedWithItems], *args: object, **kwargs: object
+        ) -> AssertionOutcome: ...
 
         @overload
         def does_not_contain_entry(
@@ -936,7 +940,7 @@ if TYPE_CHECKING:
         ) -> AssertionOutcome: ...
         @overload
         def does_not_contain_entry(
-            self: _CheckAnyValue[_CapableT], *args: object, **kwargs: object
+            self: _CheckAnyValue[_KeyedWithItems], *args: object, **kwargs: object
         ) -> AssertionOutcome: ...
 
         @overload

{assertpy2-2.24.0 → assertpy2-2.25.0}/assertpy2/_engine/_capable_typing.py

@@ -49,6 +49,28 @@ if TYPE_CHECKING:
 
         def __lt__(self, other: Any, /) -> Any: ...
 
+    class _Keyed(Protocol):
+        """`keys()`, which the dict gate reads before anything else.
+
+        Iterability is read too and is deliberately NOT here: the gate asks
+        `isinstance(value, collections.abc.Iterable)`, which a class earns by registration, and
+        requiring `__iter__` structurally refused a registered value that runs.  Same blind spot as
+        `numbers.Number` in the numeric family, and the same answer.
+        """
+
+        def keys(self) -> Any: ...
+
+    class _KeyedWithItems(_Keyed, Protocol):
+        """And a lookup, which reading an entry needs and reading a key does not."""
+
+        def __getitem__(self, key: Any, /) -> Any: ...
+
+    class _KeyedWithValues(_Keyed, Protocol):
+        """And the values, which only the value pair reads.  A lookup is not enough: measured on a
+        subject carrying `keys` and `__getitem__`, `contains_value` still refuses."""
+
+        def values(self) -> Any: ...
+
     class _PathLike(Protocol):
         """A value the filesystem assertions can read a path out of, spelled as `os.PathLike` spells it."""
 
@@ -196,18 +218,22 @@ if TYPE_CHECKING:
             self: _CapableAssertion[bytes | bytearray], sub: bytes | bytearray
         ) -> _CapableAssertion[_CapableT_co]: ...
         def contains_duplicates(self) -> Self: ...
-        def contains_entry(self, *args: object, **kwargs: object) -> Self: ...
+        def contains_entry(
+            self: _CapableAssertion[_KeyedWithItems], *args: object, **kwargs: object
+        ) -> _CapableAssertion[_CapableT_co]: ...
         def contains_error(self, *ex_types: type) -> Self: ...
         def contains_exactly(self, *items: object) -> Self: ...
         def contains_exactly_in_any_order(self, *items: object) -> Self: ...
         def contains_ignoring_case(self, *items: str) -> Self: ...
         def contains_in_order(self, *items: object) -> Self: ...
-        def contains_key(self, *keys: object) -> Self: ...
+        def contains_key(self: _CapableAssertion[_Keyed], *keys: object) -> _CapableAssertion[_CapableT_co]: ...
         def contains_none_of(self, *items: str) -> Self: ...
         def contains_only(self, *items: object) -> Self: ...
         def contains_only_once(self, *items: object) -> Self: ...
         def contains_sequence(self, *items: object) -> Self: ...
-        def contains_value(self, *values: object) -> Self: ...
+        def contains_value(
+            self: _CapableAssertion[_KeyedWithValues], *values: object
+        ) -> _CapableAssertion[_CapableT_co]: ...
         def decoded_as(
             self: _CapableAssertion[bytes | bytearray], encoding: str = ...
         ) -> _CapableAssertion[_CapableT_co]: ...
@@ -215,10 +241,14 @@ if TYPE_CHECKING:
         def described_as(self, description: str) -> Self: ...
         def does_not_contain(self, *items: object) -> Self: ...
         def does_not_contain_duplicates(self) -> Self: ...
-        def does_not_contain_entry(self, *args: object, **kwargs: object) -> Self: ...
+        def does_not_contain_entry(
+            self: _CapableAssertion[_KeyedWithItems], *args: object, **kwargs: object
+        ) -> _CapableAssertion[_CapableT_co]: ...
         def does_not_contain_error(self, *ex_types: type) -> Self: ...
-        def does_not_contain_key(self, *keys: object) -> Self: ...
-        def does_not_contain_value(self, *values: object) -> Self: ...
+        def does_not_contain_key(self: _CapableAssertion[_Keyed], *keys: object) -> _CapableAssertion[_CapableT_co]: ...
+        def does_not_contain_value(
+            self: _CapableAssertion[_KeyedWithValues], *values: object
+        ) -> _CapableAssertion[_CapableT_co]: ...
         def does_not_exist(self: _CapableAssertion[_PathLike]) -> _CapableAssertion[_CapableT_co]: ...
         def does_not_have_json_path(self, path: str) -> Self: ...
         def does_not_match(self: _CapableAssertion[str], pattern: str) -> _CapableAssertion[_CapableT_co]: ...
@@ -355,6 +385,7 @@ if TYPE_CHECKING:
         def is_zero(self) -> Self: ...
         def matches(self: _CapableAssertion[str], pattern: str) -> _CapableAssertion[_CapableT_co]: ...
         def matches_contract_snapshot(self, id: str | None = ..., path: str = ...) -> Self: ...
+        def matches_error_tree(self, *expected: type | list[Any]) -> Self: ...
         def matches_inline(
             self,
             expected: object = ...,

{assertpy2-2.24.0 → assertpy2-2.25.0}/assertpy2/_engine/_check_typing.py

@@ -675,6 +675,7 @@ if TYPE_CHECKING:
         def does_not_contain_error(self, *ex_types: type) -> AssertionOutcome: ...
         def has_root_cause(self, ex: type) -> AssertionOutcome: ...
         def contains_error(self, *ex_types: type) -> AssertionOutcome: ...
+        def matches_error_tree(self, *expected: type | list[Any]) -> AssertionOutcome: ...
         @property
         def not_(self) -> Self: ...
 

{assertpy2-2.24.0 → assertpy2-2.25.0}/assertpy2/_engine/_diff.py

@@ -33,7 +33,7 @@ from typing import TYPE_CHECKING, TypeVar
 
 from ..errors import DiffEntry, DiffResult, _safe_repr
 from ._compare import _guarded_not_equal, _node_decision
-from ._introspection import is_attrs_instance, is_mapping_like, is_model_dump_object, is_namedtuple
+from ._introspection import is_attrs_instance, is_mapping_like, is_model_dump_object, is_namedtuple, keyed_snapshot
 from ._path import _ROOT, _Path
 
 if TYPE_CHECKING:
@@ -480,6 +480,48 @@ def _build_equality_diff(
     return DiffResult(kind="scalar", entries=[_prefix.leaf_entry(actual=actual, expected=expected)])
 
 
+def _mapping_diff_entries(actual, expected, prefix: _Path, child_seen: set[int], config) -> list[DiffEntry] | None:
+    """Path-level entries between two mappings, or ``None`` when either cannot be walked by key.
+
+    Both sides are snapshotted first, so the keys walked below are the ones that were proved readable
+    rather than a second reading of a value free to answer differently between passes.
+    """
+    kept, kept_expected = keyed_snapshot(actual), keyed_snapshot(expected)
+    if kept is None or kept_expected is None:
+        return None
+    entries: list[DiffEntry] = []
+    actual_keys = set(kept)
+    expected_keys = set(kept_expected)
+    if config is not None and config.strict_types:
+        # `{True} & {1}` hands back whichever side the set drew from, losing the type that differs
+        stored = {key: key for key in kept_expected}
+        for key in kept:
+            counterpart = stored.get(key, key)
+            if type(key) is not type(counterpart):
+                entries.append(prefix.key(key).entry(actual=key, expected=counterpart))
+    for key in _ordered_keys(kept, kept_expected):
+        if key not in expected_keys:
+            entries.append(prefix.key(key).entry(actual=kept[key], expected=None, absent="expected"))
+        elif key not in actual_keys:
+            entries.append(prefix.key(key).entry(actual=None, absent="actual", expected=kept_expected[key]))
+        else:
+            decision = _node_decision(kept[key], kept_expected[key], config, field=key)
+            if decision == "leaf":
+                entries.append(prefix.key(key).entry(actual=kept[key], expected=kept_expected[key]))
+            elif decision != "equal":
+                entries.extend(
+                    _child_entries(
+                        kept[key],
+                        kept_expected[key],
+                        prefix.key(key),
+                        descended_for=decision,
+                        _seen=child_seen,
+                        config=config,
+                    )
+                )
+    return entries
+
+
 def _sub_diff_entries(
     actual: object, expected: object, prefix: _Path = _ROOT, *, _seen: set[int] | None = None, config=None
 ) -> list[DiffEntry] | None:
@@ -500,38 +542,7 @@ def _sub_diff_entries(
         return [prefix.entry(actual="<circular ref>", expected="<circular ref>")]
 
     if is_mapping_like(actual) and is_mapping_like(expected):
-        child_seen = _seen | {id(actual), id(expected)}
-        entries: list[DiffEntry] = []
-        actual_keys = set(actual)
-        expected_keys = set(expected)
-        if config is not None and config.strict_types:
-            # `{True} & {1}` hands back whichever side the set drew from, losing the type that differs
-            stored = {key: key for key in expected}
-            for key in actual:
-                counterpart = stored.get(key, key)
-                if type(key) is not type(counterpart):
-                    entries.append(prefix.key(key).entry(actual=key, expected=counterpart))
-        for key in _ordered_keys(actual, expected):
-            if key not in expected_keys:
-                entries.append(prefix.key(key).entry(actual=actual[key], expected=None, absent="expected"))
-            elif key not in actual_keys:
-                entries.append(prefix.key(key).entry(actual=None, absent="actual", expected=expected[key]))
-            else:
-                decision = _node_decision(actual[key], expected[key], config, field=key)
-                if decision == "leaf":
-                    entries.append(prefix.key(key).entry(actual=actual[key], expected=expected[key]))
-                elif decision != "equal":
-                    entries.extend(
-                        _child_entries(
-                            actual[key],
-                            expected[key],
-                            prefix.key(key),
-                            descended_for=decision,
-                            _seen=child_seen,
-                            config=config,
-                        )
-                    )
-        return entries
+        return _mapping_diff_entries(actual, expected, prefix, _seen | {id(actual), id(expected)}, config)
     if (
         dataclasses.is_dataclass(actual)
         and not isinstance(actual, type)
@@ -563,11 +574,11 @@ def _sub_diff_entries(
                             config=config,
                         )
                     )
-        for field_name in expected._fields:
-            if field_name not in actual._fields:  # _fields, not hasattr (count/index collide)
-                entries.append(
-                    prefix.attr(field_name).entry(actual=None, absent="actual", expected=getattr(expected, field_name))
-                )
+        entries.extend(
+            prefix.attr(field_name).entry(actual=None, absent="actual", expected=getattr(expected, field_name))
+            for field_name in expected._fields
+            if field_name not in actual._fields  # _fields, not hasattr (count/index collide)
+        )
         return entries
     both_model = is_model_dump_object(actual) and is_model_dump_object(expected)
     both_attrs = is_attrs_instance(actual) and is_attrs_instance(expected)