assertpy2 2.17.0__tar.gz → 2.19.0__tar.gz

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/ci.yml

@@ -15,6 +15,7 @@ permissions:
 
 jobs:
   test:
+    timeout-minutes: 15
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -31,15 +32,15 @@ jobs:
           - os: macos-latest
             python-version: "3.14"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -78,17 +79,18 @@ jobs:
           files: coverage.xml
 
   lint:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
@@ -111,6 +113,7 @@ jobs:
         run: uv run pyright tests/test_typing.py
 
   ci-ok:
+    timeout-minutes: 5
     needs: [test, lint]
     if: always()
     runs-on: ubuntu-latest

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/codeql.yml

@@ -13,14 +13,15 @@ permissions:
 
 jobs:
   analyze:
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           languages: python
-      - uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/codspeed.yml

@@ -21,20 +21,21 @@ concurrency:
 
 jobs:
   benchmarks:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Run benchmarks under CodSpeed
-        uses: CodSpeedHQ/action@f99becdce5e5d51fd556489ebef684f4ecfd6286 # v4.18.5
+        uses: CodSpeedHQ/action@f22792bfac16f3e14eb9fbea76f4a48e9cc22b93 # v4.19.1
         with:
           mode: simulation
           run: uv run --locked --group benchmark pytest benchmarks/ --codspeed --no-cov

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/docs.yml

@@ -15,17 +15,18 @@ concurrency:
 
 jobs:
   build:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
@@ -42,6 +43,7 @@ jobs:
           path: site
 
   deploy:
+    timeout-minutes: 10
     if: github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/mutation.yml

@@ -21,15 +21,15 @@ jobs:
       matrix:
         module: [base, numeric, string, contains, collection, dict, date, matchers, helpers, _compare, dataframe, json_mixin, snapshot, bytes_mixin, dynamic, extracting, warning, exception, async_assertions, file, behave_matchers]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/publish.yml

@@ -9,6 +9,7 @@ permissions:
 
 jobs:
   publish:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
@@ -16,17 +17,17 @@ jobs:
       contents: write
       attestations: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: false
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.15"
           allow-prereleases: true
@@ -65,7 +66,7 @@ jobs:
         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
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
 
       - name: Upload to GitHub Release
         run: gh release upload "$TAG_NAME" dist/* provenance/*

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/scorecard.yml

@@ -11,15 +11,16 @@ permissions: read-all
 
 jobs:
   analysis:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
       security-events: write
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
         with:
           results_file: results.sarif
           results_format: sarif
@@ -29,6 +30,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@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           sarif_file: results.sarif

{assertpy2-2.17.0 → assertpy2-2.19.0}/.github/workflows/zizmor.yml

@@ -15,11 +15,12 @@ permissions:
 
 jobs:
   zizmor:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7
+      - uses: zizmorcore/zizmor-action@6fc4b006235f201fdab3722e17240ab420d580e5 # v0.6.1

{assertpy2-2.17.0 → assertpy2-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.17.0
+Version: 2.19.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
@@ -88,9 +88,9 @@ def test_user():
     user = {"name": "Alice", "age": 30, "roles": ["viewer", "editor"]}
 
     assert_that(user).contains_key("name", "age")
+    assert_that(user).contains_entry({"name": "Alice"})
     assert_that(user["age"]).is_between(18, 120)
     assert_that(user["roles"]).contains("viewer").does_not_contain("admin")
-    assert_that(user).has_name("Alice")
 ```
 
 The [full documentation](https://solganis.github.io/assertpy2/) covers every assertion, matcher, and integration.
@@ -100,6 +100,7 @@ The [full documentation](https://solganis.github.io/assertpy2/) covers every ass
 A fluent chain reads as one intent and replaces several bare asserts -<br>
 and your IDE offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/concepts/type-safety/):
 
+<!-- docs-guard: skip -->
 ```python
 # bare - three statements, no autocomplete help
 assert isinstance(items, list)
@@ -123,6 +124,7 @@ E     {'status': 'active'} != {'status': 'disabled'}
 
 assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
 
+<!-- docs-guard: skip -->
 ```python
 assert_that(response).is_equal_to(expected)
 ```
@@ -133,6 +135,23 @@ assert_that(response).is_equal_to(expected)
 
 The diff recurses through nested containers, and matcher predicates get the same path-level treatment. For dynamic fields like IDs or timestamps, assert a subset with [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
 
+Matchers are ordinary values, so they also compose inside the expected structure itself, at any depth,
+with or without the fluent chain:
+
+```python
+response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
+
+assert_that(response).is_equal_to(
+    {"id": match.greater_than(0), "user": {"name": "Alice", "age": match.between(18, 120)}, "tags": ["a", "b"]}
+)
+
+# or keep the bare `assert`, and pytest's own rewriting reports it
+assert response == {"id": match.greater_than(0), "user": match.ignore(), "tags": ["a", "b"]}
+```
+
+The fluent form keeps the path-level diff, the bare form keeps pytest's. There are
+[39 matchers](https://solganis.github.io/assertpy2/guides/matchers/), and they combine with `&`, `|` and `~`.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
 </p>
@@ -156,6 +175,7 @@ Works in PyCharm, VS Code, and any LSP-compatible editor.
 An assertion hands the value back, statically narrowed. `is_not_none()` strips `None`,
 `is_instance_of()` narrows to the class, and `.value` returns it with no `cast` and no bare `assert`:
 
+<!-- docs-guard: skip -->
 ```python
 order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
 order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
@@ -164,6 +184,7 @@ order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
 For API tests, [`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms) validates a raw payload against a Pydantic model and narrows the chain to it,<br>
 with `exact=True` catching silent contract drift:
 
+<!-- docs-guard: skip -->
 ```python
 data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 ```
@@ -175,6 +196,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.

{assertpy2-2.17.0 → assertpy2-2.19.0}/README.md

@@ -36,9 +36,9 @@ def test_user():
     user = {"name": "Alice", "age": 30, "roles": ["viewer", "editor"]}
 
     assert_that(user).contains_key("name", "age")
+    assert_that(user).contains_entry({"name": "Alice"})
     assert_that(user["age"]).is_between(18, 120)
     assert_that(user["roles"]).contains("viewer").does_not_contain("admin")
-    assert_that(user).has_name("Alice")
 ```
 
 The [full documentation](https://solganis.github.io/assertpy2/) covers every assertion, matcher, and integration.
@@ -48,6 +48,7 @@ The [full documentation](https://solganis.github.io/assertpy2/) covers every ass
 A fluent chain reads as one intent and replaces several bare asserts -<br>
 and your IDE offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/concepts/type-safety/):
 
+<!-- docs-guard: skip -->
 ```python
 # bare - three statements, no autocomplete help
 assert isinstance(items, list)
@@ -71,6 +72,7 @@ E     {'status': 'active'} != {'status': 'disabled'}
 
 assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
 
+<!-- docs-guard: skip -->
 ```python
 assert_that(response).is_equal_to(expected)
 ```
@@ -81,6 +83,23 @@ assert_that(response).is_equal_to(expected)
 
 The diff recurses through nested containers, and matcher predicates get the same path-level treatment. For dynamic fields like IDs or timestamps, assert a subset with [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
 
+Matchers are ordinary values, so they also compose inside the expected structure itself, at any depth,
+with or without the fluent chain:
+
+```python
+response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
+
+assert_that(response).is_equal_to(
+    {"id": match.greater_than(0), "user": {"name": "Alice", "age": match.between(18, 120)}, "tags": ["a", "b"]}
+)
+
+# or keep the bare `assert`, and pytest's own rewriting reports it
+assert response == {"id": match.greater_than(0), "user": match.ignore(), "tags": ["a", "b"]}
+```
+
+The fluent form keeps the path-level diff, the bare form keeps pytest's. There are
+[39 matchers](https://solganis.github.io/assertpy2/guides/matchers/), and they combine with `&`, `|` and `~`.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
 </p>
@@ -104,6 +123,7 @@ Works in PyCharm, VS Code, and any LSP-compatible editor.
 An assertion hands the value back, statically narrowed. `is_not_none()` strips `None`,
 `is_instance_of()` narrows to the class, and `.value` returns it with no `cast` and no bare `assert`:
 
+<!-- docs-guard: skip -->
 ```python
 order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
 order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
@@ -112,6 +132,7 @@ order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
 For API tests, [`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms) validates a raw payload against a Pydantic model and narrows the chain to it,<br>
 with `exact=True` catching silent contract drift:
 
+<!-- docs-guard: skip -->
 ```python
 data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 ```
@@ -123,6 +144,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.

{assertpy2-2.17.0 → assertpy2-2.19.0}/assertpy2/__init__.py

@@ -14,10 +14,15 @@ 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
+from .snapshot import (
+    SnapshotCreatedWarning,
+    SnapshotKeyReusedWarning,
+    SnapshotUpdatedWarning,
+    register_snapshot_serializer,
+)
 
 __all__ = [
     "AssertionFailure",
@@ -29,9 +34,11 @@ __all__ = [
     "PollSample",
     "PollTrace",
     "SnapshotCreatedWarning",
+    "SnapshotKeyReusedWarning",
     "SnapshotUpdatedWarning",
     "SoftAssertionCollector",
     "SyncAssertionBuilder",
+    "VacuousAssertionWarning",
     "WarningLoggingAdapter",
     "__version__",
     "add_extension",

{assertpy2-2.17.0 → assertpy2-2.19.0}/assertpy2/_engine/_compare.py

@@ -14,9 +14,13 @@ express to the type checker.
 from __future__ import annotations
 
 import dataclasses
+import datetime
+import decimal
 import math
 import numbers
+import pathlib
 import re
+import uuid
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
@@ -26,30 +30,71 @@ if TYPE_CHECKING:
     from collections.abc import Callable
 
 
+_EQ_ATOMIC = frozenset(
+    {
+        int,
+        float,
+        bool,
+        complex,
+        str,
+        bytes,
+        bytearray,
+        type(None),
+        datetime.datetime,
+        datetime.date,
+        datetime.time,
+        datetime.timedelta,
+        decimal.Decimal,
+        uuid.UUID,
+        pathlib.PurePosixPath,
+        pathlib.PureWindowsPath,
+        pathlib.PosixPath,
+        pathlib.WindowsPath,
+    }
+)
+"""Types whose ``==`` is a plain bool and which have nothing inside to walk into.
+
+The stdlib scalars past the builtins are here for cost, not for correctness.  ``strict_types`` walks
+past any value it does not know to be atomic, because a container's own ``==`` says nothing about the
+types inside it - and a ``datetime`` is not a container, so that walk runs the whole introspection
+ladder to come back with nothing.  Over 200 records of timestamps, decimals and UUIDs that was 3.7 ms
+against 0.5 ms with them listed.
+
+Listing one changes no verdict: a type difference is decided by `_types_differ()` before atomicity is
+ever consulted, so ``date`` against ``datetime`` still fails.  Exact types, not ``isinstance``, so a
+subclass with its own structure is still walked.
+"""
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
 class _CompareConfig:
     """Tolerance and custom comparators for a single ``is_equal_to`` call.
 
     ``tolerance`` is an absolute tolerance applied to real-number leaves; ``comparators`` maps a ``type`` or
     an immediate field name to a ``(actual, expected) -> bool`` predicate that owns matching leaves;
-    ``ignore_null`` skips a named field whenever the *expected* side leaves it ``None``.
+    ``ignore_null`` skips a named field whenever the *expected* side leaves it ``None``;
+    ``strict_types`` additionally requires both sides of every node to be the same type, which plain
+    ``==`` does not (``True == 1``, ``Decimal("1") == 1``, and so on all the way down a payload).
     """
 
     tolerance: float | None = None
     comparators: dict[object, Callable[[object, object], bool]] | None = None
     ignore_null: bool = False
+    strict_types: bool = False
 
 
-def _build_compare_config(tolerance, comparators, ignore_null=False) -> _CompareConfig | None:
-    """Validate the ``is_equal_to`` ``tolerance``/``comparators``/``ignore_null`` kwargs and build a config.
+def _build_compare_config(tolerance, comparators, ignore_null=False, strict_types=False) -> _CompareConfig | None:
+    """Validate the ``is_equal_to`` comparison kwargs and build a config.
 
     Returns ``None`` when none are set.  ``tolerance`` must be a non-negative real number (not
     ``bool``/``complex``/``NaN``); ``comparators`` must be a dict of ``(actual, expected) -> bool`` callables
-    keyed by ``type`` or field name; ``ignore_null`` must be a bool.
+    keyed by ``type`` or field name; ``ignore_null`` and ``strict_types`` must be bools.
     """
     if ignore_null is not False and ignore_null is not True:
         raise TypeError("given ignore_null arg must be a bool")
-    if tolerance is None and comparators is None and not ignore_null:
+    if strict_types is not False and strict_types is not True:
+        raise TypeError("given strict_types arg must be a bool")
+    if tolerance is None and comparators is None and not ignore_null and not strict_types:
         return None
     if tolerance is not None:
         if isinstance(tolerance, bool) or not isinstance(tolerance, numbers.Number) or isinstance(tolerance, complex):
@@ -64,7 +109,9 @@ def _build_compare_config(tolerance, comparators, ignore_null=False) -> _Compare
         for comparator in comparators.values():
             if not callable(comparator):
                 raise TypeError("each comparator must be callable")
-    return _CompareConfig(tolerance=tolerance, comparators=comparators, ignore_null=ignore_null)
+    return _CompareConfig(
+        tolerance=tolerance, comparators=comparators, ignore_null=ignore_null, strict_types=strict_types
+    )
 
 
 def _ambiguous_array_operand(value: object, other: object) -> object | None:
@@ -208,13 +255,35 @@ def _resolve_comparator(actual, config: _CompareConfig, *, field):
     return None
 
 
+def _types_differ(actual, expected) -> bool:
+    """Whether ``strict_types`` should reject this pair.
+
+    A matcher standing in for a value is not a value, so it is exempt: the expected side of
+    ``is_equal_to({"id": match.greater_than(0)})`` is a ``GreaterThanMatcher`` by construction, and
+    comparing its type against an ``int`` would break every composed matcher rather than catch a bug.
+
+    ``_is_matcher`` is imported here rather than at module scope because ``_matcher_impls`` imports
+    ``_guarded_not_equal`` from this module, so the module-level import would be a cycle.
+    """
+    if type(actual) is type(expected):
+        return False
+    from .._matcher_impls import _is_matcher
+
+    return not _is_matcher(expected) and not _is_matcher(actual)
+
+
 def _node_decision(actual, expected, config: _CompareConfig | None, *, field=None) -> str:
-    """Classify a node as ``"equal"``, ``"leaf"`` or ``"recurse"``.
+    """Classify a node as ``"equal"``, ``"leaf"``, ``"recurse"`` or ``"strict"``.
 
     With ``config is None`` this is exactly the engine's historical behavior: differing values ``"recurse"``
     (to decompose into a sub-diff), equal values are ``"equal"`` (skipped); ``"leaf"`` never occurs.  With a
     config, a matching comparator or tolerance owns the node - it is classified ``"equal"`` or ``"leaf"`` and
     never recursed into.
+
+    ``"strict"`` is the fourth: the two sides are equal and the same type, but ``strict_types`` still has
+    to look inside, because a container's ``==`` says nothing about the types of its members.  It differs
+    from ``"recurse"`` only in what an undecomposable value means, which
+    `assertpy2._engine._diff._child_entries()` is the single place to know.
     """
     if config is not None:
         if config.ignore_null and field is not None and expected is None:
@@ -222,6 +291,24 @@ def _node_decision(actual, expected, config: _CompareConfig | None, *, field=Non
         comparator = _resolve_comparator(actual, config, field=field)
         if comparator is not None:
             return "equal" if comparator(actual, expected) else "leaf"
+        if config.strict_types:
+            if actual is expected:
+                # what `PyObject_RichCompareBool` hands a container for free, and what forcing the walk
+                # below would otherwise take away: one object is equal to itself without consulting
+                # `__eq__`, which is why a shared subnode is cheap and why `[nan] == [nan]` is true when
+                # both elements are the same float
+                return "equal"
+            if _types_differ(actual, expected):
+                # ahead of tolerance on purpose: a tolerance says how far apart two numbers may be, it
+                # does not say they may be different types, and a strict run that quietly accepted int
+                # vs float inside its own tolerance would be the surprise, not the rule
+                return "leaf"
+            if type(actual) not in _EQ_ATOMIC and not _guarded_not_equal(actual, expected):
+                # a container's own `==` says nothing about the types inside it: `[True] == [1]`.  The
+                # walk normally stops here, so under strict types it has to keep going.  Whether the
+                # walker can actually take this value apart is not predicted here: `"strict"` tells the
+                # caller that a value it cannot decompose is one that is already equal
+                return "strict"
         if config.tolerance is not None and _is_real_number(actual) and _is_real_number(expected):
             return "equal" if _within_tolerance(actual, expected, config.tolerance) else "leaf"
     return "recurse" if _guarded_not_equal(actual, expected) else "equal"

{assertpy2-2.17.0 → assertpy2-2.19.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__