assertpy2 2.16.0__tar.gz → 2.18.0__tar.gz

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
@@ -85,7 +85,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/codeql.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           languages: python
-      - uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/codspeed.yml

@@ -31,7 +31,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Run benchmarks under CodSpeed
         uses: CodSpeedHQ/action@f99becdce5e5d51fd556489ebef684f4ecfd6286 # v4.18.5

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/docs.yml

@@ -22,7 +22,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/mutation.yml

@@ -26,7 +26,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
 
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: false
 
@@ -46,15 +46,24 @@ jobs:
         with:
           subject-path: dist/*.tar.gz
 
-      - name: Prepare provenance bundles
+      - name: Collect provenance (sigstore bundles + in-toto)
         run: |
           mkdir -p provenance
           cp "$WHEEL_BUNDLE" "provenance/$(basename dist/*.whl).sigstore.json"
           cp "$SDIST_BUNDLE" "provenance/$(basename dist/*.tar.gz).sigstore.json"
+          jq -c '.dsseEnvelope' "$WHEEL_BUNDLE" > provenance/provenance.intoto.jsonl
+          jq -c '.dsseEnvelope' "$SDIST_BUNDLE" >> provenance/provenance.intoto.jsonl
+          test -s provenance/provenance.intoto.jsonl
         env:
           WHEEL_BUNDLE: ${{ steps.attest-wheel.outputs.bundle-path }}
           SDIST_BUNDLE: ${{ steps.attest-sdist.outputs.bundle-path }}
 
+      - name: Install syft
+        uses: anchore/sbom-action/download-syft@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+
+      - name: Generate SBOM (CycloneDX)
+        run: syft scan dir:dist -o "cyclonedx-json=provenance/assertpy2.sbom.cdx.json"
+
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
 

{assertpy2-2.16.0 → assertpy2-2.18.0}/.github/workflows/scorecard.yml

@@ -29,6 +29,6 @@ jobs:
           name: SARIF file
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
         with:
           sarif_file: results.sarif

{assertpy2-2.16.0 → assertpy2-2.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.16.0
+Version: 2.18.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
@@ -175,6 +175,7 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 - [**Composable matchers**](https://solganis.github.io/assertpy2/guides/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`, usable in plain `assert ==`.
 - [**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.
 - [**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.
@@ -203,7 +204,7 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 - [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected`, `.diff`, and the diff renders into the message itself, so it shows off pytest too.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive structural diffs across containers, dataclasses, attrs, and Pydantic models, with intra-line carets for strings and circular-reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): three modes under one typed API, all updated with `--assertpy2-snapshot-update`: `snapshot()` (external JSON file), [`matches_inline()`](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) (recorded into the test source), and [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots) (value-tolerant structural regressions).
-- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1), reporting every violation with its JSON path.
+- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1 and Swagger 2.0), reporting every violation with its JSON path.
 
 **Extensibility**
 

{assertpy2-2.16.0 → assertpy2-2.18.0}/README.md

@@ -123,6 +123,7 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 - [**Composable matchers**](https://solganis.github.io/assertpy2/guides/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`, usable in plain `assert ==`.
 - [**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.
 - [**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.
@@ -151,7 +152,7 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 - [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected`, `.diff`, and the diff renders into the message itself, so it shows off pytest too.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive structural diffs across containers, dataclasses, attrs, and Pydantic models, with intra-line carets for strings and circular-reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): three modes under one typed API, all updated with `--assertpy2-snapshot-update`: `snapshot()` (external JSON file), [`matches_inline()`](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) (recorded into the test source), and [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots) (value-tolerant structural regressions).
-- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1), reporting every violation with its JSON path.
+- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1 and Swagger 2.0), reporting every violation with its JSON path.
 
 **Extensibility**
 

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/__init__.py

@@ -14,7 +14,7 @@ from .assertpy import (
     soft_fail,
 )
 from .async_assertions import AsyncAssertionBuilder, SyncAssertionBuilder
-from .errors import AssertionFailure, DiffEntry, DiffResult, PollSample, PollTrace
+from .errors import AssertionFailure, DiffEntry, DiffResult, PollSample, PollTrace, VacuousAssertionWarning
 from .file import contents_of
 from .matchers import Matcher, clear_custom_matchers, match, register_matcher, unregister_matcher
 from .snapshot import SnapshotCreatedWarning, SnapshotUpdatedWarning, register_snapshot_serializer
@@ -32,6 +32,7 @@ __all__ = [
     "SnapshotUpdatedWarning",
     "SoftAssertionCollector",
     "SyncAssertionBuilder",
+    "VacuousAssertionWarning",
     "WarningLoggingAdapter",
     "__version__",
     "add_extension",

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_engine/_compare.py

@@ -89,11 +89,13 @@ def _ambiguous_array_operand(value: object, other: object) -> object | 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."""
+    # point at the assertion that delegates to the library's own comparison: it reports the differing
+    # column or index, where wrapping `.equals()` in is_true() would report a bare False
+    dedicated = "is_frame_equal(expected)" if hasattr(operand, "equals") else "is_array_equal(expected)"
     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."
+        f" no single truth value. Use {dedicated}, assert on extracted scalars (columns, shape, length),"
+        " or use satisfies(...) with an explicit predicate."
     )
 
 

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_engine/_contract.py

@@ -86,7 +86,7 @@ def contract_drift(payload: object, model: Any, path: str = "") -> list[str]:
     return drift
 
 
-def shape(value: object) -> object:
+def shape(value: object, _seen: frozenset[int] = frozenset()) -> object:
     """The structural shape of a value: paths and type *categories*, never values.
 
     Numbers collapse to one category (so ``5`` and ``5.0`` do not read as drift) and ``None`` becomes
@@ -101,10 +101,15 @@ def shape(value: object) -> object:
         return "number"
     if isinstance(value, str):
         return "str"
-    if isinstance(value, dict):
-        return {key: shape(item) for key, item in value.items()}
-    if isinstance(value, (list, tuple)):
-        element_shapes = [shape(item) for item in value]
+    if isinstance(value, (dict, list, tuple)):
+        if id(value) in _seen:
+            # a self-referential graph (an ORM backref, a tree with parent pointers) would otherwise
+            # recurse until the interpreter gives up; every sibling walker marks the cycle instead
+            return "<circular ref>"
+        nested = _seen | {id(value)}
+        if isinstance(value, dict):
+            return {key: shape(item, nested) for key, item in value.items()}
+        element_shapes = [shape(item, nested) for item in value]
         return [reduce(_merge, element_shapes)] if element_shapes else []
     return type(value).__name__
 

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_engine/_diff.py

@@ -183,7 +183,11 @@ def _build_equality_diff(
         for item in sorted(expected - actual, key=_safe_repr):
             entries.append(DiffEntry(path="missing", actual=None, expected=item))
         return DiffResult(kind="set", entries=entries)
-    if isinstance(actual, str) and isinstance(expected, str):
+    # bytes render as their b'...' literal, which difflib can point into exactly like text, and both
+    # kinds expose splitlines(), so one branch serves them
+    both_text = isinstance(actual, str) and isinstance(expected, str)
+    both_bytes = isinstance(actual, (bytes, bytearray)) and isinstance(expected, (bytes, bytearray))
+    if both_text or both_bytes:
         entries = []
         actual_lines = actual.splitlines()
         expected_lines = expected.splitlines()

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_engine/_mixin_base.py

@@ -38,6 +38,7 @@ class _MixinBase:
             kind: str | None = ...,
             expected: type[BaseException] | None = ...,
             logger: logging.LoggerAdapter | None = ...,
+            origin: str | None = ...,
         ) -> Self: ...
 
         # WarningMixin (terminals dispatched from ExceptionMixin.when_called_with)

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_engine/_typing.py

@@ -54,8 +54,8 @@ if TYPE_CHECKING:
         def is_callable(self) -> Self: ...
         def is_not_callable(self) -> Self: ...
         def satisfies(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
-        def all_fields_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
-        def has_no_none_fields(self) -> Self: ...
+        def all_fields_satisfy(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = ...) -> Self: ...
+        def has_no_none_fields(self, *, allow_empty: bool = ...) -> Self: ...
         # ContainsMixin - universal
         def is_in(self, *items: object) -> Self: ...
         def is_not_in(self, *items: object) -> Self: ...
@@ -135,7 +135,7 @@ if TYPE_CHECKING:
         def has_size_between(self, low: int, high: int) -> Self: ...
         def is_empty(self) -> Self: ...
         def is_not_empty(self) -> Self: ...
-        def is_subset_of(self, *supersets: object) -> Self: ...
+        def is_subset_of(self, *supersets: object, allow_empty: bool = ...) -> Self: ...
         # StringMixin - regex
         def extracting_group(self, pattern: str, group: int | str = ...) -> Self: ...
         def matches_with_groups(self, pattern: str) -> Self: ...
@@ -203,18 +203,22 @@ if TYPE_CHECKING:
         # CollectionMixin
         def is_iterable(self) -> Self: ...
         def is_not_iterable(self) -> Self: ...
-        def is_subset_of(self, *supersets: object) -> Self: ...
-        def is_sorted(self, key: Callable[..., object] = ..., reverse: bool = ...) -> Self: ...
+        def is_subset_of(self, *supersets: object, allow_empty: bool = ...) -> Self: ...
+        def is_sorted(
+            self, key: Callable[..., object] = ..., reverse: bool = ..., *, allow_empty: bool = ...
+        ) -> Self: ...
         # ExtractingMixin - extracted values have a dynamic type, so the element type is dropped
         def extracting(self, *names: object, **kwargs: object) -> _IterableAssertion[Any]: ...
         # BaseMixin
-        def each(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
+        def each(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = ...) -> Self: ...
         def any_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
-        def all_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
+        def all_satisfy(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = ...) -> Self: ...
         def none_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
         def satisfies_exactly(self, *matchers: Matcher | Callable[..., bool]) -> Self: ...
         def satisfies_exactly_in_any_order(self, *matchers: Matcher | Callable[..., bool]) -> Self: ...
-        def zip_satisfies(self, other: Iterable[object], predicate: Callable[..., bool]) -> Self: ...
+        def zip_satisfies(
+            self, other: Iterable[object], predicate: Callable[..., bool], *, allow_empty: bool = ...
+        ) -> Self: ...
         def contains_only_once(self, *items: object) -> Self: ...
         def has_same_size_as(self, other: object) -> Self: ...
         def has_size_greater_than(self, size: int) -> Self: ...
@@ -267,7 +271,7 @@ if TYPE_CHECKING:
         def is_not_empty(self) -> Self: ...
         # BaseMixin
         def matches_structure(self, spec: dict) -> Self: ...
-        def each(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
+        def each(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = ...) -> Self: ...
         # ExtractingMixin - extracted values have a dynamic type, so the key/value types are dropped
         def extracting(self, *names: object, **kwargs: object) -> _DictAssertion[Any, Any]: ...
         # JsonMixin - navigation yields a dynamically-typed value, so the key/value types are dropped

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_matcher_impls.py

@@ -48,6 +48,16 @@ def _is_matcher(obj: object) -> TypeIs[Matcher]:
     return isinstance(obj, Matcher)
 
 
+def _require_matcher(operand: object, operator: str) -> None:
+    """Reject a non-matcher operand where the combinator is built, not where it is later applied.
+
+    Combining silently would hand back a matcher that raises ``AttributeError: 'int' object has no
+    attribute 'matches'`` at assertion time, far from the line that built it.
+    """
+    if not _is_matcher(operand):
+        raise TypeError(f"cannot combine a Matcher with <{type(operand).__name__}> using '{operator}'")
+
+
 class BaseMatcher:
     """Abstract base for all matchers with operator support."""
 
@@ -61,11 +71,13 @@ class BaseMatcher:
         return f"was <{value}>"
 
     def __and__(self, other: Matcher) -> AllOfMatcher:
+        _require_matcher(other, "&")
         left = list(self.matchers) if isinstance(self, AllOfMatcher) else [self]
         right = list(other.matchers) if isinstance(other, AllOfMatcher) else [other]
         return AllOfMatcher(*left, *right)
 
     def __or__(self, other: Matcher) -> AnyOfMatcher:
+        _require_matcher(other, "|")
         left = list(self.matchers) if isinstance(self, AnyOfMatcher) else [self]
         right = list(other.matchers) if isinstance(other, AnyOfMatcher) else [other]
         return AnyOfMatcher(*left, *right)

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_satisfies.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 import collections.abc
+import os
+import warnings
 from typing import TYPE_CHECKING, Any
 
 from ._engine._diff import _walk_leaves
 from ._engine._introspection import is_attrs_instance, is_model_dump_object
 from ._engine._mixin_base import _MixinBase
-from .errors import DiffEntry, DiffResult
+from .errors import DiffEntry, DiffResult, VacuousAssertionWarning
 from .matchers import IsNotNoneMatcher, Matcher, StructureMatcher, _apply_matcher, _describe_matcher, _is_matcher
 
 if TYPE_CHECKING:
@@ -47,10 +49,53 @@ def _max_bipartite_assignment(satisfied: list[list[bool]]) -> list[int | None]:
     return assignment
 
 
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+def _env_enabled() -> bool:
+    """Read the environment switch, at import and from the pytest plugin rather than per assertion.
+
+    The switch cannot change within a process, and the lookup with its two string operations costs
+    around 300ns: more than the emptiness check it decides to skip, on every quantifier call.
+    """
+    return os.environ.get("ASSERTPY2_VACUOUS", "").strip().lower() in _TRUTHY
+
+
+_VACUOUS_GUARD: bool = _env_enabled()
+"""Whether a universal assertion over an empty value warns.
+
+Off by default: a suite running ``filterwarnings = ["error"]`` would otherwise fail on upgrade, and a
+property-based test generates empty collections as a matter of course.  Turn it on with the pytest
+``--assertpy2-vacuous`` flag or the ``ASSERTPY2_VACUOUS`` environment variable for other runners.
+"""
+
+
+def _warn_if_vacuous(name: str, value: object, allow_empty: bool) -> None:
+    """Warn when a universal assertion is about to pass because there is nothing to quantify over.
+
+    Called from each public entry point rather than from the shared implementation, so the name in the
+    message is the one the caller used and ``stacklevel`` lands on their line rather than ours.
+    """
+    if allow_empty or not _VACUOUS_GUARD:
+        return
+    try:
+        empty = len(value) == 0  # ty: ignore[invalid-argument-type]  # guarded by the except below
+    except Exception:  # a diagnostic must never crash the assertion it is watching
+        # no usable len(): an unsized value (a one-shot iterable) or a broken __len__.  Either way,
+        # stay out of the way rather than draining the value or surfacing its error as our own.
+        return
+    if empty:
+        warnings.warn(
+            f"{name}() passed over an empty value, so nothing was checked. Pass allow_empty=True if that is intended.",
+            VacuousAssertionWarning,
+            stacklevel=3,
+        )
+
+
 class SatisfiesMixin(_MixinBase):
     """Predicate and matcher-application assertions: satisfies / each / *_satisfy / matches_structure."""
 
-    def all_fields_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self:
+    def all_fields_satisfy(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = False) -> Self:
         """Asserts that every scalar leaf in val's object graph satisfies the given matcher.
 
         Walks val recursively (mappings, dataclasses, namedtuples, Pydantic models, lists, tuples) and
@@ -75,6 +120,7 @@ class SatisfiesMixin(_MixinBase):
             AssertionError: if any leaf does **not** satisfy the matcher
             TypeError: if matcher is neither a Matcher nor callable
         """
+        _warn_if_vacuous("all_fields_satisfy", self.val, allow_empty)
         if not _is_matcher(matcher) and not callable(matcher):
             raise TypeError("given arg must be a Matcher or callable")
         description = _describe_matcher(matcher)
@@ -94,7 +140,7 @@ class SatisfiesMixin(_MixinBase):
             )
         return self
 
-    def has_no_none_fields(self) -> Self:
+    def has_no_none_fields(self, *, allow_empty: bool = False) -> Self:
         """Asserts that no scalar leaf in val's object graph is ``None``.
 
         Convenience wrapper over `all_fields_satisfy()` with a not-``None`` matcher; reports the path
@@ -111,7 +157,8 @@ class SatisfiesMixin(_MixinBase):
         Raises:
             AssertionError: if any leaf **is** ``None``
         """
-        return self.all_fields_satisfy(IsNotNoneMatcher())
+        _warn_if_vacuous("has_no_none_fields", self.val, allow_empty)
+        return self.all_fields_satisfy(IsNotNoneMatcher(), allow_empty=True)
 
     def satisfies(self, matcher: Matcher | Callable[..., bool]) -> Self:
         """Asserts that val satisfies the given matcher.
@@ -159,7 +206,7 @@ class SatisfiesMixin(_MixinBase):
             raise TypeError("given arg must be a Matcher or callable")
         return self
 
-    def each(self, matcher: Matcher | Callable[..., bool]) -> Self:
+    def each(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = False) -> Self:
         """Asserts that every item in val satisfies the given matcher.
 
         Args:
@@ -184,6 +231,7 @@ class SatisfiesMixin(_MixinBase):
         Raises:
             AssertionError: if any item does **not** satisfy the matcher
         """
+        _warn_if_vacuous("each", self.val, allow_empty)
         if not isinstance(self.val, collections.abc.Iterable):
             raise TypeError("val is not iterable")
         if _is_matcher(matcher):
@@ -322,17 +370,29 @@ class SatisfiesMixin(_MixinBase):
         """
         if not isinstance(self.val, collections.abc.Iterable):
             raise TypeError("val is not iterable")
-        if _is_matcher(matcher):
-            if not any(matcher.matches(item) for item in self.val):
-                return self.error(f"Expected any item to satisfy {matcher.describe()}, but none did.")
-        elif callable(matcher):
-            if not any(matcher(item) for item in self.val):
-                return self.error(f"Expected any item to satisfy {_describe_matcher(matcher)}, but none did.")
+        description = _describe_matcher(matcher)
+        if _is_matcher(matcher) or callable(matcher):
+            if not any(_apply_matcher(matcher, item) for item in self.val):
+                # "none did" alone leaves the reader to fetch the items themselves; the universal
+                # sibling already lists every one that failed
+                items = list(self.val)
+                return self.error(
+                    f"Expected any item to satisfy {description}, but none of the {len(items)} did.",
+                    actual=self.val,
+                    expected=description,
+                    diff=DiffResult(
+                        kind="match",
+                        entries=[
+                            DiffEntry(path=f"[{index}]", actual=item, expected=description)
+                            for index, item in enumerate(items[:5])
+                        ],
+                    ),
+                )
         else:
             raise TypeError("given arg must be a Matcher or callable")
         return self
 
-    def all_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self:
+    def all_satisfy(self, matcher: Matcher | Callable[..., bool], *, allow_empty: bool = False) -> Self:
         """Asserts that all items in val satisfy the given matcher.
 
         Semantic alias for [`each()`][assertpy2.base.BaseMixin.each].
@@ -354,7 +414,8 @@ class SatisfiesMixin(_MixinBase):
         Raises:
             AssertionError: if any item does **not** satisfy the matcher
         """
-        return self.each(matcher)
+        _warn_if_vacuous("all_satisfy", self.val, allow_empty)
+        return self.each(matcher, allow_empty=True)
 
     def none_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self:
         """Asserts that no item in val satisfies the given matcher.
@@ -533,7 +594,9 @@ class SatisfiesMixin(_MixinBase):
             )
         return self
 
-    def zip_satisfies(self, other: Iterable[object], predicate: Callable[..., bool]) -> Self:
+    def zip_satisfies(
+        self, other: Iterable[object], predicate: Callable[..., bool], *, allow_empty: bool = False
+    ) -> Self:
         """Asserts that each pair from zipping val with other satisfies the two-arg predicate.
 
         Pairs the i-th item of val with the i-th item of ``other`` and checks ``predicate(a, b)``.
@@ -556,6 +619,7 @@ class SatisfiesMixin(_MixinBase):
             AssertionError: if the lengths differ, or any pair does **not** satisfy the predicate
             TypeError: if val or other is not iterable, or predicate is not callable
         """
+        _warn_if_vacuous("zip_satisfies", self.val, allow_empty)
         if not callable(predicate):
             raise TypeError("given predicate must be callable")
         if not isinstance(self.val, collections.abc.Iterable):

{assertpy2-2.16.0 → assertpy2-2.18.0}/assertpy2/_snapshot_codec.py

@@ -31,19 +31,27 @@ _SERIALIZERS: list[_Serializer] = []
 _RESERVED_MARKERS = frozenset({"__type__", "__data__", "__tag__", "__class__", "__module__"})
 
 
-def _prepare(value):
+def _prepare(value, _seen: frozenset[int] = frozenset()):
     """Pre-process a value so ``json`` round-trips dicts that it otherwise mangles: dicts with a
     non-string key (which ``json`` coerces to a string) and dicts that collide with the codec's markers
     (which the decoder would misread).  Both are wrapped in a ``{"__type__": "dict", "__data__": [[k,
     v], ...]}`` envelope; a plain string-keyed dict without markers is left as an ordinary object so
     existing snapshots stay byte-identical."""
-    if isinstance(value, dict):
-        if all(isinstance(key, str) for key in value) and not _RESERVED_MARKERS.intersection(value):
-            return {key: _prepare(item) for key, item in value.items()}
-        items = sorted(value.items(), key=lambda pair: repr(pair[0]))  # deterministic order for mixed keys
-        return {"__type__": "dict", "__data__": [[_prepare(key), _prepare(item)] for key, item in items]}
-    if isinstance(value, (list, tuple)):
-        return [_prepare(item) for item in value]
+    if isinstance(value, (dict, list, tuple)):
+        if id(value) in _seen:
+            # json cannot represent a cycle at all, so the only question is how this fails: naming the
+            # cycle beats a thousand frames of RecursionError from an unguarded walk
+            raise ValueError("cannot snapshot a value that contains a circular reference")
+        nested = _seen | {id(value)}
+        if isinstance(value, dict):
+            if all(isinstance(key, str) for key in value) and not _RESERVED_MARKERS.intersection(value):
+                return {key: _prepare(item, nested) for key, item in value.items()}
+            items = sorted(value.items(), key=lambda pair: repr(pair[0]))  # deterministic for mixed keys
+            return {
+                "__type__": "dict",
+                "__data__": [[_prepare(key, nested), _prepare(item, nested)] for key, item in items],
+            }
+        return [_prepare(item, nested) for item in value]
     return value