assertpy2 2.11.0__tar.gz → 2.12.0__tar.gz

{assertpy2-2.11.0 → assertpy2-2.12.0}/.github/workflows/mutation.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        module: [base, numeric, string, contains, collection, dict, date, matchers, helpers]
+        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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
@@ -34,7 +34,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: uv sync --extra json --group mutation
+        run: uv sync --extra json --extra behave --group mutation
 
       - name: Run mutation testing
         env:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.11.0
+Version: 2.12.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
@@ -135,7 +135,7 @@ 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>
 
-Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
+Recursive diffs work for dicts, dataclasses, namedtuples, and Pydantic models.
 For responses with dynamic fields (IDs, timestamps), validate a subset with
 [`matches_structure()`](https://solganis.github.io/assertpy2/matchers/#structural-matching) instead of exact equality.
 
@@ -160,16 +160,16 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 
 See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) guide for the full walkthrough.
 
----
-
 <h2 align="center">Features</h2>
 
 **Fluent API**
 
 - [**Composable matchers**](https://solganis.github.io/assertpy2/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
 - [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation, reporting the exact path to each mismatch on failure.
+- [**Recursive field assertions**](https://solganis.github.io/assertpy2/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph, reporting the exact path.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
+- [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
 
 **Built-in types**
@@ -177,7 +177,8 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [Strings](https://solganis.github.io/assertpy2/assertions/#strings), [numbers](https://solganis.github.io/assertpy2/assertions/#numbers), [lists](https://solganis.github.io/assertpy2/assertions/#lists), [tuples](https://solganis.github.io/assertpy2/assertions/#tuples), [sets](https://solganis.github.io/assertpy2/assertions/#sets), [dicts](https://solganis.github.io/assertpy2/assertions/#dicts), [dates](https://solganis.github.io/assertpy2/assertions/#dates), [booleans](https://solganis.github.io/assertpy2/assertions/#booleans), [objects](https://solganis.github.io/assertpy2/assertions/#objects), [bytes](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray), [files](https://solganis.github.io/assertpy2/assertions/#files), [exceptions](https://solganis.github.io/assertpy2/errors/#expected-exceptions).
 - [**Bytes assertions**](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
 - [**Dynamic assertions**](https://solganis.github.io/assertpy2/assertions/#dynamic-assertions-on-objects): `has_<name>()` for any attribute, property, or zero-argument method.
-- [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects).
+- [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects), including by regex or type.
+- [**Recursive comparison**](https://solganis.github.io/assertpy2/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance` (absolute float tolerance at any depth) or `comparators` (per-type / per-field predicates) for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
 
 **Testing**
@@ -202,8 +203,6 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 See the [full documentation](https://solganis.github.io/assertpy2/) for all assertion methods, examples, and advanced features.
 
----
-
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/integrations/">Integrations</a></h2>
 
 Optional adapters, each its own extra; full configuration and examples are in the

{assertpy2-2.11.0 → assertpy2-2.12.0}/README.md

@@ -87,7 +87,7 @@ 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>
 
-Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
+Recursive diffs work for dicts, dataclasses, namedtuples, and Pydantic models.
 For responses with dynamic fields (IDs, timestamps), validate a subset with
 [`matches_structure()`](https://solganis.github.io/assertpy2/matchers/#structural-matching) instead of exact equality.
 
@@ -112,16 +112,16 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 
 See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) guide for the full walkthrough.
 
----
-
 <h2 align="center">Features</h2>
 
 **Fluent API**
 
 - [**Composable matchers**](https://solganis.github.io/assertpy2/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
 - [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation, reporting the exact path to each mismatch on failure.
+- [**Recursive field assertions**](https://solganis.github.io/assertpy2/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph, reporting the exact path.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
+- [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
 
 **Built-in types**
@@ -129,7 +129,8 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [Strings](https://solganis.github.io/assertpy2/assertions/#strings), [numbers](https://solganis.github.io/assertpy2/assertions/#numbers), [lists](https://solganis.github.io/assertpy2/assertions/#lists), [tuples](https://solganis.github.io/assertpy2/assertions/#tuples), [sets](https://solganis.github.io/assertpy2/assertions/#sets), [dicts](https://solganis.github.io/assertpy2/assertions/#dicts), [dates](https://solganis.github.io/assertpy2/assertions/#dates), [booleans](https://solganis.github.io/assertpy2/assertions/#booleans), [objects](https://solganis.github.io/assertpy2/assertions/#objects), [bytes](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray), [files](https://solganis.github.io/assertpy2/assertions/#files), [exceptions](https://solganis.github.io/assertpy2/errors/#expected-exceptions).
 - [**Bytes assertions**](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
 - [**Dynamic assertions**](https://solganis.github.io/assertpy2/assertions/#dynamic-assertions-on-objects): `has_<name>()` for any attribute, property, or zero-argument method.
-- [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects).
+- [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects), including by regex or type.
+- [**Recursive comparison**](https://solganis.github.io/assertpy2/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance` (absolute float tolerance at any depth) or `comparators` (per-type / per-field predicates) for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
 
 **Testing**
@@ -154,8 +155,6 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 
 See the [full documentation](https://solganis.github.io/assertpy2/) for all assertion methods, examples, and advanced features.
 
----
-
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/integrations/">Integrations</a></h2>
 
 Optional adapters, each its own extra; full configuration and examples are in the

assertpy2-2.12.0/assertpy2/_compare.py

@@ -0,0 +1,136 @@
+"""Per-call configuration for tolerant / custom-comparator equality, shared by the equality and diff code.
+
+``is_equal_to`` builds a `_CompareConfig` from its ``tolerance``/``comparators`` kwargs and threads it
+through both the boolean comparison (`HelpersMixin._dict_not_equal()`) and the diff/message rendering
+(`BaseMixin._sub_diff_entries()`, `HelpersMixin._dict_err()`).  `_node_decision()` is the single
+switch both sides consult, so a tolerated or comparator-equal leaf is reported in neither.  With ``config is
+None`` every helper reproduces the engine's historical ``actual != expected`` behavior exactly.
+
+Following the package convention, the impl helpers take unannotated args (the typed public surface lives in
+`assertpy2._typing`); they operate on arbitrary user values whose operators ``numbers.Number`` cannot
+express to the type checker.
+"""
+
+from __future__ import annotations
+
+import math
+import numbers
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@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.
+    """
+
+    tolerance: float | None = None
+    comparators: dict[object, Callable[[object, object], bool]] | None = None
+
+
+def _build_compare_config(tolerance, comparators) -> _CompareConfig | None:
+    """Validate the ``is_equal_to`` ``tolerance``/``comparators`` kwargs and build a config (``None`` if neither).
+
+    ``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.
+    """
+    if tolerance is None and comparators is None:
+        return None
+    if tolerance is not None:
+        if isinstance(tolerance, bool) or not isinstance(tolerance, numbers.Number) or isinstance(tolerance, complex):
+            raise TypeError("given tolerance arg must be a real number")
+        if math.isnan(tolerance):
+            raise ValueError("given tolerance arg must not be NaN")
+        if tolerance < 0:
+            raise ValueError("given tolerance arg must not be negative")
+    if comparators is not None:
+        if not isinstance(comparators, dict):
+            raise TypeError("given comparators arg must be a dict")
+        for comparator in comparators.values():
+            if not callable(comparator):
+                raise TypeError("each comparator must be callable")
+    return _CompareConfig(tolerance=tolerance, comparators=comparators)
+
+
+def _is_real_number(value) -> bool:
+    """Return whether ``value`` is a real number eligible for tolerance (excludes ``bool`` and ``complex``).
+
+    Array/frame-likes are not `numbers.Number`, so they are excluded too - tolerance never triggers
+    their element-wise ``==`` that has no single truth value.
+    """
+    return isinstance(value, numbers.Number) and not isinstance(value, (bool, complex))
+
+
+def _within_tolerance(actual, expected, tolerance) -> bool:
+    """Return whether two real numbers are within ``tolerance`` (absolute); ``NaN`` is never within.
+
+    Only actual ``float`` operands are checked for ``NaN`` (other reals cannot be ``NaN``), which also keeps
+    ``math.isnan`` off arbitrary-precision ``int`` values that would overflow it.
+    """
+    if isinstance(actual, float) and math.isnan(actual):
+        return False
+    if isinstance(expected, float) and math.isnan(expected):
+        return False
+    return abs(actual - expected) <= tolerance
+
+
+def _resolve_comparator(actual, config: _CompareConfig, *, field):
+    """Resolve the comparator owning a leaf: immediate field name first, then exact type, then ``isinstance``.
+
+    ``field`` is the leaf's immediate key/field name (``None`` for sequence elements and bare scalars, which
+    have no name).  Returns ``None`` when no comparator applies, so the caller falls back to tolerance / ``==``.
+    """
+    comparators = config.comparators
+    if comparators is None:
+        return None
+    if field is not None and not isinstance(field, type) and field in comparators:
+        return comparators[field]
+    if type(actual) in comparators:
+        return comparators[type(actual)]
+    for key, comparator in comparators.items():
+        if isinstance(key, type) and isinstance(actual, key):
+            return comparator
+    return None
+
+
+def _node_decision(actual, expected, config: _CompareConfig | None, *, field=None) -> str:
+    """Classify a node as ``"equal"``, ``"leaf"`` or ``"recurse"``.
+
+    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.
+    """
+    if config is not None:
+        comparator = _resolve_comparator(actual, config, field=field)
+        if comparator is not None:
+            return "equal" if comparator(actual, expected) else "leaf"
+        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 actual != expected else "equal"
+
+
+def _spec_matches(key, value, specs) -> bool:
+    """Return whether a dict ``key``/``value`` matches any ignore/include ``spec``.
+
+    A spec matches by exact key equality (today's behavior), by a compiled `re.Pattern` searched
+    against ``str(key)``, or by a ``type`` the ``value`` is an instance of.  Nested-path tuples never match
+    here - they are expanded by the recursion in `HelpersMixin._dict_not_equal()`.
+    """
+    for spec in specs:
+        if isinstance(spec, re.Pattern):
+            if spec.search(str(key)):
+                return True
+        elif isinstance(spec, type):
+            if isinstance(value, spec):
+                return True
+        elif spec == key:
+            return True
+    return False

{assertpy2-2.11.0 → assertpy2-2.12.0}/assertpy2/_compat.py

@@ -1,6 +1,6 @@
 """Internal compatibility shims.
 
-``Self`` entered the standard library's :mod:`typing` in Python 3.11; on 3.10 it is provided by
+``Self`` entered the standard library's `typing` in Python 3.11; on 3.10 it is provided by
 ``typing_extensions``. Re-exporting it from one place lets every mixin import ``Self`` without repeating
 the version gate, and lets ``typing_extensions`` be dropped as a runtime dependency on Python 3.11+.
 """

{assertpy2-2.11.0 → assertpy2-2.12.0}/assertpy2/_mixin_base.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     import logging
 
+    from ._compare import _CompareConfig
     from ._compat import Self
     from .errors import DiffEntry, DiffResult
 
@@ -60,7 +61,7 @@ class _MixinBase:
 
         def _is_dict_like(
             self,
-            d: object,
+            candidate: object,
             check_keys: bool = ...,
             check_values: bool = ...,
             check_getitem: bool = ...,
@@ -68,7 +69,7 @@ class _MixinBase:
 
         def _require_dict_like(
             self,
-            d: object,
+            candidate: object,
             check_keys: bool = ...,
             check_values: bool = ...,
             check_getitem: bool = ...,
@@ -83,6 +84,7 @@ class _MixinBase:
             other: object,
             ignore: object = ...,
             include: object = ...,
+            config: _CompareConfig | None = ...,
         ) -> bool: ...
 
         def _dict_err(
@@ -91,6 +93,7 @@ class _MixinBase:
             other: object,
             ignore: object = ...,
             include: object = ...,
+            config: _CompareConfig | None = ...,
         ) -> None: ...
 
         @staticmethod
@@ -98,7 +101,12 @@ class _MixinBase:
 
         @staticmethod
         def _sub_diff_entries(
-            actual: object, expected: object, prefix: str, *, _seen: set[int] | None = ...
+            actual: object,
+            expected: object,
+            prefix: str,
+            *,
+            _seen: set[int] | None = ...,
+            config: _CompareConfig | None = ...,
         ) -> list[DiffEntry] | None: ...
 
         # NumericMixin class attrs used by HelpersMixin._validate_between_args

{assertpy2-2.11.0 → assertpy2-2.12.0}/assertpy2/_typing.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Hashable
+    from collections.abc import Callable, Hashable, Iterable
     from pathlib import Path
     from typing import Any, Protocol
 
@@ -21,7 +21,13 @@ if TYPE_CHECKING:
         # BaseMixin
         def described_as(self, description: str) -> Self: ...
         def is_equal_to(
-            self, other: object, *, ignore: _KeySpecs | None = ..., include: _KeySpecs | None = ...
+            self,
+            other: object,
+            *,
+            ignore: _KeySpecs | None = ...,
+            include: _KeySpecs | None = ...,
+            tolerance: float | None = ...,
+            comparators: dict[object, Callable[..., bool]] | None = ...,
         ) -> Self: ...
         def is_not_equal_to(self, other: object) -> Self: ...
         def is_same_as(self, other: object) -> Self: ...
@@ -36,6 +42,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: ...
         # ContainsMixin - universal
         def is_in(self, *items: object) -> Self: ...
         def is_not_in(self, *items: object) -> Self: ...
@@ -73,8 +81,11 @@ if TYPE_CHECKING:
         def does_not_contain_duplicates(self) -> Self: ...
         def contains_exactly(self, *items: object) -> Self: ...
         def contains_in_order(self, *items: object) -> Self: ...
+        def contains_only_once(self, *items: object) -> Self: ...
+        def has_same_size_as(self, other: object) -> Self: ...
         def is_empty(self) -> Self: ...
         def is_not_empty(self) -> Self: ...
+        def is_subset_of(self, *supersets: object) -> Self: ...
         # StringMixin - regex
         def extracting_group(self, pattern: str, group: int | str = ...) -> Self: ...
         def matches_with_groups(self, pattern: str) -> Self: ...
@@ -138,6 +149,10 @@ if TYPE_CHECKING:
         def any_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
         def all_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
         def none_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
+        def satisfies_exactly(self, *matchers: Matcher | Callable[..., bool]) -> Self: ...
+        def zip_satisfies(self, other: Iterable[object], predicate: Callable[..., bool]) -> Self: ...
+        def contains_only_once(self, *items: object) -> Self: ...
+        def has_same_size_as(self, other: object) -> Self: ...
         # CollectionMixin - pipeline
         def filtered_on(self, predicate: Callable[..., bool]) -> Self: ...
         def mapped(self, func: Callable[..., object]) -> Self: ...
@@ -166,6 +181,7 @@ if TYPE_CHECKING:
         # ContainsMixin
         def contains(self, *items: object) -> Self: ...
         def does_not_contain(self, *items: object) -> Self: ...
+        def has_same_size_as(self, other: object) -> Self: ...
         def is_empty(self) -> Self: ...
         def is_not_empty(self) -> Self: ...
         # BaseMixin
@@ -209,6 +225,7 @@ if TYPE_CHECKING:
 
         # ContainsMixin
         def contains(self, *items: object) -> Self: ...
+        def has_same_size_as(self, other: object) -> Self: ...
         def is_empty(self) -> Self: ...
         def is_not_empty(self) -> Self: ...
         # BytesMixin
@@ -223,8 +240,9 @@ if TYPE_CHECKING:
     class _InvokedAssertion(_StringAssertion, Protocol):
         """Assertions available after ``when_called_with()`` captured an exception/warning message.
 
-        The captured message is a ``str`` (hence the string assertions); :meth:`returned` pivots to
-        the value the callable returned.  Its static type is unknown, so ``returned()`` exposes the
+        The captured message is a ``str`` (hence the string assertions);
+        [`returned()`][assertpy2.exception.ExceptionMixin.returned] pivots to the value the callable
+        returned.  Its static type is unknown, so ``returned()`` exposes the
         type-agnostic core assertions (``is_equal_to``, ``is_instance_of``, ``satisfies``, ...) -
         type-safe by construction, never advertising methods that may not apply.
         """