assertpy2 2.26.0__tar.gz → 2.27.0__tar.gz

{assertpy2-2.26.0 → assertpy2-2.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.26.0
+Version: 2.27.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

{assertpy2-2.26.0 → assertpy2-2.27.0}/assertpy2/_clustering.py

@@ -239,6 +239,25 @@ def _shown(value: object) -> str:
     return _bounded(stable_repr(value))
 
 
+class _Absent:
+    """A side that held nothing at all.
+
+    An absent key carries `None`, and read as a value it printed as ``None`` and keyed with every
+    failure whose value really is `None`.
+    """
+
+    def __repr__(self) -> str:
+        return "<absent>"
+
+
+_ABSENT = _Absent()
+
+
+def _side_of(entry: DiffEntry, side: str) -> object:
+    """One side of an entry, or the absent marker where that side held nothing."""
+    return _ABSENT if entry.absent == side else (entry.actual if side == "actual" else entry.expected)
+
+
 def _identity(value: object) -> str:
     """A value as a cluster key: the whole of it, in a fixed number of characters.
 
@@ -265,7 +284,9 @@ def signature(diff: DiffResult, entry: DiffEntry, label: str | None = None) -> S
         return Signature(False, diff.kind, label=label)
     if diff.kind not in _VALUES_ARE_VALUES:
         return None
-    return Signature(False, diff.kind, values=(_identity(entry.actual), _identity(entry.expected)))
+    return Signature(
+        False, diff.kind, values=(_identity(_side_of(entry, "actual")), _identity(_side_of(entry, "expected")))
+    )
 
 
 def is_well_formed(key: Signature) -> bool:
@@ -305,7 +326,9 @@ def observations_of(diff: DiffResult | None, label: str | None = None) -> list[O
     for entry in diff.entries:
         key = signature(diff, entry, label)
         if key is not None:
-            seen.setdefault(key, Observation(key, _shown(entry.actual), _shown(entry.expected)))
+            seen.setdefault(
+                key, Observation(key, _shown(_side_of(entry, "actual")), _shown(_side_of(entry, "expected")))
+            )
     return list(seen.values())
 
 

{assertpy2-2.26.0 → assertpy2-2.27.0}/assertpy2/_engine/_builder_check_typing.py

@@ -27,7 +27,6 @@ if TYPE_CHECKING:
     from ..matchers import Matcher
     from ..outcome import AssertionOutcome
     from ._capable_typing import (
-        _Callable,
         _Indexed,
         _Keyed,
         _KeyedWithItems,
@@ -1136,15 +1135,6 @@ if TYPE_CHECKING:
             **options: Any,
         ) -> AssertionOutcome: ...
 
-        @overload
-        def when_called_with(
-            self: _CheckAnyValue[Callable[..., _P]], *some_args: object, **some_kwargs: object
-        ) -> AssertionOutcome: ...
-        @overload
-        def when_called_with(
-            self: _CheckAnyValue[_Callable], *some_args: object, **some_kwargs: object
-        ) -> AssertionOutcome: ...
-
         @overload
         def is_not_none(self: _CheckAnyValue[str | None]) -> AssertionOutcome: ...
         @overload

{assertpy2-2.26.0 → assertpy2-2.27.0}/assertpy2/_engine/_check_typing.py

@@ -150,6 +150,12 @@ if TYPE_CHECKING:
         @property
         def not_(self) -> Self: ...
 
+    class _CheckReturningAssertion(Protocol):
+        """The verdict twin of `_ReturningAssertion`."""
+
+        @property
+        def not_(self) -> Self: ...
+
     class _CheckZeroAssertion(Protocol):
         """The verdict twin of `_ZeroAssertion`."""
 
@@ -679,9 +685,41 @@ if TYPE_CHECKING:
         @property
         def not_(self) -> Self: ...
 
+    class _CheckWarnedAssertion(_CheckTextAssertion, _CheckReturningAssertion, Protocol):
+        """The verdict twin of `_WarnedAssertion`."""
+
+        @property
+        def not_(self) -> Self: ...
+
     class _CheckCallableAssertion(_CheckCoreAssertion, Protocol[_P_co]):
         """The verdict twin of `_CallableAssertion`."""
 
+        @property
+        def not_(self) -> Self: ...
+
+    class _CheckCompletedAssertion(_CheckCallableAssertion[_P_co], _CheckReturningAssertion, Protocol[_P_co]):
+        """The verdict twin of `_CompletedAssertion`."""
+
+        @property
+        def not_(self) -> Self: ...
+
+    class _CheckExpectedRaiseAssertion(_CheckCallableAssertion[_P_co], Protocol[_P_co]):
+        """The verdict twin of `_ExpectedRaiseAssertion`."""
+
+        def when_called_with(self, *some_args: object, **some_kwargs: object) -> AssertionOutcome: ...
+        @property
+        def not_(self) -> Self: ...
+
+    class _CheckExpectedWarningAssertion(_CheckCallableAssertion[_P_co], Protocol[_P_co]):
+        """The verdict twin of `_ExpectedWarningAssertion`."""
+
+        def when_called_with(self, *some_args: object, **some_kwargs: object) -> AssertionOutcome: ...
+        @property
+        def not_(self) -> Self: ...
+
+    class _CheckExpectedCompletionAssertion(_CheckCallableAssertion[_P_co], Protocol[_P_co]):
+        """The verdict twin of `_ExpectedCompletionAssertion`."""
+
         def when_called_with(self, *some_args: object, **some_kwargs: object) -> AssertionOutcome: ...
         @property
         def not_(self) -> Self: ...

{assertpy2-2.26.0 → assertpy2-2.27.0}/assertpy2/_engine/_compare.py

@@ -16,6 +16,8 @@ from __future__ import annotations
 import dataclasses
 import datetime
 import decimal
+import fractions
+import inspect
 import math
 import numbers
 import pathlib
@@ -24,8 +26,9 @@ import uuid
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
-from ._introspection import is_mapping_like, is_model_dump_object
-from ._require import verdict
+from ._introspection import is_attrs_instance, is_mapping_like, is_model_dump_object
+from ._ordering import nan_operand
+from ._require import raised_inside, verdict
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -225,16 +228,73 @@ def _is_real_number(value) -> bool:
 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.
+    Checked by type rather than through `math.isnan`, which overflows on an arbitrary-precision ``int``
+    and signals on a `Decimal` NaN.
+
+    The subtraction is tried as written, so two floats keep the arithmetic they always had.  A `Decimal`
+    against a ``float`` refuses to subtract at all and a bignum ``int`` overflows one, and those two pairs
+    are measured exactly instead, through `fractions.Fraction`.
     """
-    if isinstance(actual, float) and math.isnan(actual):
-        return False
-    if isinstance(expected, float) and math.isnan(expected):
+    if nan_operand(actual) or nan_operand(expected):
         return False
     if actual == expected:  # equal values (including inf == inf) are within any tolerance
         return True
-    return abs(actual - expected) <= tolerance
+    if _is_infinite(actual) or _is_infinite(expected):
+        return False  # unequal, and no distance from an infinity is within a finite tolerance
+    try:
+        return abs(actual - expected) <= tolerance
+    except (TypeError, OverflowError) as error:
+        if raised_inside(error):  # their own `__sub__` or `__abs__` raised: a bug in the value, not a refusal
+            raise
+        return abs(fractions.Fraction(actual) - fractions.Fraction(expected)) <= fractions.Fraction(tolerance)
+
+
+def _is_infinite(value) -> bool:
+    """A `float` or `Decimal` infinity, asked by type so nothing else is converted to a float to answer.
+
+    Through `Decimal`'s own method rather than the value's: a subclass overriding `is_infinite` would
+    otherwise decide this, and run its code before the arithmetic it is being asked about.
+    """
+    if isinstance(value, float):
+        return math.isinf(value)
+    return isinstance(value, decimal.Decimal) and decimal.Decimal.is_infinite(value)
+
+
+class WindowRefusedError(TypeError):
+    """The two operands form no window: neither the arithmetic nor an exact conversion takes them.
+
+    A `TypeError` still, so a caller that let the operand's own refusal out keeps letting this one out,
+    and a matcher, which may not raise, can tell it from a `__sub__` of somebody's own that raised.
+    """
+
+
+def tolerance_window(middle: Any, tolerance: Any) -> tuple[Any, Any]:
+    """The closed interval ``middle`` plus and minus ``tolerance``.
+
+    Typed as `Any` because the pairing is a run-time fact: the assertion has refused every combination
+    but two before it asks, a number against a number and a datetime against a timedelta, and a checker
+    reading the public signature alone is right to refuse the arithmetic.  The matcher asks without
+    refusing anything first, which is what `WindowRefusedError` is for: it hands back the operands' own
+    refusal as something a matcher may answer "no match" to.
+    """
+    if _is_infinite(middle) and _is_real_number(tolerance):
+        # its own window, the way a float infinity already gets one: no distance from it is finite.  The
+        # tolerance is still read, or an infinity paired with anything at all would answer "close enough"
+        return middle, middle
+    try:
+        return middle - tolerance, middle + tolerance
+    except TypeError as refusal:
+        if raised_inside(refusal):  # their own `__sub__` raised: that is a bug in the value
+            raise
+        if not all(isinstance(operand, numbers.Number) for operand in (middle, tolerance)):
+            raise WindowRefusedError(str(refusal)) from None
+        # a `Decimal` refuses arithmetic with a `float` or a `Fraction`, which both convert exactly, while
+        # an infinite or NaN one does not convert at all
+        try:
+            exact, span = fractions.Fraction(middle), fractions.Fraction(tolerance)
+        except (TypeError, ValueError, OverflowError) as failed:
+            raise WindowRefusedError(str(failed)) from None
+        return exact - span, exact + span
 
 
 def _resolve_comparator(actual, config: _CompareConfig, *, field):
@@ -293,6 +353,51 @@ def _keyed_types_differ(actual, expected) -> bool:
     return False
 
 
+def _kinds_never_equal(actual, expected) -> bool:
+    """Whether ``==`` rejects the pair by its kind alone, which a walk over the parts cannot see.
+
+    Under a compare config the walker decides by parts, so ``[1.0]`` against ``(1.0,)``, or two dataclasses
+    of different classes holding the same fields, had no differing part and passed, while ``==`` rejects
+    both outright.  Asked only once ``==`` has already said no, so it never fails a pair ``==`` accepts.
+
+    The kind alone is not the answer: a list subclass may define ``__eq__`` to accept a tuple.  So a pair
+    of different kinds counts only when both sides' own ``__eq__`` decline it, which leaves ``==`` at
+    identity whatever the parts hold.  A pydantic model answers ``False`` rather than declining, so which of
+    class or fields decided cannot be told apart, and models are left to the walk.
+    """
+    if isinstance(actual, (list, tuple)) and isinstance(expected, (list, tuple)):
+        kinds_differ = isinstance(actual, list) is not isinstance(expected, list)
+    else:
+        both_dataclasses = all(
+            dataclasses.is_dataclass(side) and not isinstance(side, type) for side in (actual, expected)
+        )
+        both_attrs = is_attrs_instance(actual) and is_attrs_instance(expected)
+        kinds_differ = (both_dataclasses or both_attrs) and type(actual) is not type(expected)
+    return kinds_differ and _both_decline(actual, expected)
+
+
+def _declines(value: Any, other: Any) -> bool:
+    """Whether *value*'s own ``__eq__`` answers ``NotImplemented`` for *other*, asked as ``==`` asks it.
+
+    Read statically off the type, since `type(x).__eq__` is an ordinary read that a metaclass answers,
+    and bound through the descriptor protocol, since that is what turns a function, a `staticmethod` or
+    anything else on the class into the callable the operator uses.
+    """
+    held: Any = inspect.getattr_static(type(value), "__eq__", None)
+    bind: Any = getattr(type(held), "__get__", None)
+    # measured against `==` itself: a callable that binds to nothing is called with the other side alone
+    asking = held if bind is None else bind(held, value, type(value))
+    return asking(other) is NotImplemented
+
+
+def _both_decline(actual: Any, expected: Any) -> bool:
+    """Whether each side's own ``__eq__`` answers ``NotImplemented`` for the other."""
+    try:
+        return _declines(actual, expected) and _declines(expected, actual)
+    except Exception:  # an `__eq__` that raises decides nothing here, and the walk goes on as before
+        return False
+
+
 def _node_decision(actual, expected, config: _CompareConfig | None, *, field=None, at_root: bool = False) -> str:
     """Classify a node as ``"equal"``, ``"leaf"``, ``"recurse"`` or ``"strict"``.
 
@@ -327,7 +432,18 @@ def _node_decision(actual, expected, config: _CompareConfig | None, *, field=Non
                 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"
+    return _plain_decision(actual, expected, config, at_root=at_root)
+
+
+def _plain_decision(actual, expected, config: _CompareConfig | None, *, at_root: bool = False) -> str:
+    """``==``'s answer as a decision, where under a config a pair ruled out by its kind alone is a leaf."""
+    if actual is expected and not at_root:
+        # the same rule a container's own `==` applies to its members, and the verdict came from that `==`:
+        # without it the diff listed a NaN both sides hold as differing, and the hint blamed it
+        return "equal"
+    if not _guarded_not_equal(actual, expected):
+        return "equal"
+    return "leaf" if config is not None and _kinds_never_equal(actual, expected) else "recurse"
 
 
 def _spec_matches(key, value, specs) -> bool:

{assertpy2-2.26.0 → assertpy2-2.27.0}/assertpy2/_engine/_diff.py

@@ -27,6 +27,7 @@ or answered for the wrong one.  Ask the walker and read its answer instead: ``No
 
 from __future__ import annotations
 
+import collections
 import dataclasses
 import difflib
 from typing import TYPE_CHECKING, TypeVar
@@ -48,7 +49,7 @@ def _field_dict(obj, is_model):
     """Field mapping of a pydantic-style model (``model_dump()``) or an attrs instance (shallow)."""
     if is_model:
         return obj.model_dump()
-    return {field.name: getattr(obj, field.name) for field in obj.__attrs_attrs__}
+    return {field.name: getattr(obj, field.name) for field in obj.__attrs_attrs__ if field.eq is not False}
 
 
 def _child_entries(actual, expected, path: _Path, *, descended_for, _seen=None, config=None) -> list[DiffEntry]:
@@ -329,8 +330,9 @@ def _dataclass_diff_entries(actual, expected, prefix: _Path, seen, config=None)
     so both report dataclass fields identically.
     """
     entries: list[DiffEntry] = []
-    actual_names = [field.name for field in dataclasses.fields(actual)]
-    expected_names = [field.name for field in dataclasses.fields(expected)]
+    # a field declared `compare=False` is outside the dataclass's own `==`, so it stays outside here
+    actual_names = [field.name for field in dataclasses.fields(actual) if field.compare]
+    expected_names = [field.name for field in dataclasses.fields(expected) if field.compare]
     in_actual, in_expected = set(actual_names), set(expected_names)
     for field in _ordered_keys(actual_names, expected_names):
         if field not in in_expected:
@@ -492,6 +494,7 @@ def _mapping_diff_entries(actual, expected, prefix: _Path, child_seen: set[int],
     entries: list[DiffEntry] = []
     actual_keys = set(kept)
     expected_keys = set(kept_expected)
+    entries.extend(_order_entries(actual, expected, kept, kept_expected, prefix))
     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}
@@ -522,6 +525,15 @@ def _mapping_diff_entries(actual, expected, prefix: _Path, child_seen: set[int],
     return entries
 
 
+def _order_entries(actual, expected, kept, kept_expected, prefix: _Path) -> list[DiffEntry]:
+    """The key order of two `OrderedDict` values holding the same keys in different places, which their `==` reads."""
+    if not (isinstance(actual, collections.OrderedDict) and isinstance(expected, collections.OrderedDict)):
+        return []
+    if set(kept) != set(kept_expected) or list(kept) == list(kept_expected):
+        return []
+    return [prefix.leaf_entry(actual=list(kept), expected=list(kept_expected))]
+
+
 def _sub_diff_entries(
     actual: object, expected: object, prefix: _Path = _ROOT, *, _seen: set[int] | None = None, config=None
 ) -> list[DiffEntry] | None:

{assertpy2-2.26.0 → assertpy2-2.27.0}/assertpy2/_engine/_equality.py

@@ -14,13 +14,27 @@ calling `self._dict_not_equal(...)` still works, and the matcher calls the same
 
 from __future__ import annotations
 
+import collections
 import collections.abc
+import dataclasses
+import datetime
+import enum
+import numbers
+import pathlib
 import re
 import types
-from typing import TYPE_CHECKING, cast
-
-from ._compare import _guarded_not_equal, _keyed_types_differ, _node_decision, _spec_matches
+import uuid
+from typing import TYPE_CHECKING, Any, cast
+
+from ._compare import (
+    _guarded_not_equal,
+    _keyed_types_differ,
+    _kinds_never_equal,
+    _node_decision,
+    _spec_matches,
+)
 from ._diff import _sub_diff_entries
+from ._introspection import is_attrs_instance, is_model_dump_object, is_namedtuple
 from ._path import _ROOT
 from ._require import refuse
 
@@ -46,6 +60,80 @@ def normalize_key_specs(specs: object, param: str) -> list:
     refuse(specs, "a key, a nested-path tuple, or a list/set/frozenset of them", subject=param)
 
 
+def key_specs_given(specs: object) -> bool:
+    """Whether an ``ignore``/``include`` argument asks for anything, a falsy key such as ``0`` or ``""`` included.
+
+    Truthiness answered this and dropped a single falsy key in silence.  An empty collection still asks
+    for nothing, as it always did.
+    """
+    return specs is not None and not (isinstance(specs, (list, set, frozenset)) and not specs)
+
+
+def comparable_fields(obj: object) -> dict | None:
+    """An object with introspectable fields as a dict of them, or ``None`` when it has no fields to compare.
+
+    Dataclasses are converted by reference rather than through `dataclasses.asdict`, which deep-copies and
+    crashes on a field that cannot be copied, and a field declared ``compare=False`` is left out, as the
+    dataclass's own ``==`` leaves it out.  An attrs field declared ``eq=False`` is left out the same way.
+
+    A value of a builtin kind is not a bag of fields even when it carries a ``__dict__``: a subclass of
+    `Decimal` or `str` has an empty one, and reading it made every two such values compare equal.
+    """
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return cast("dict", _shallow_fields(obj))
+    if is_namedtuple(obj):
+        return dict(obj._asdict())
+    if is_model_dump_object(obj):
+        return obj.model_dump()
+    if is_attrs_instance(obj):
+        # deferred: at module level it cost 8.5 ms and 22 modules of a 39.8 ms import wherever attrs is installed
+        import attrs
+
+        return attrs.asdict(obj, filter=lambda attribute, _value: attribute.eq is not False)
+    builtin_kinds = (
+        type,
+        numbers.Number,
+        str,
+        bytes,
+        bytearray,
+        datetime.date,
+        datetime.time,
+        datetime.timedelta,
+        enum.Enum,
+        uuid.UUID,
+        pathlib.PurePath,
+    )
+    if hasattr(obj, "__dict__") and not isinstance(obj, builtin_kinds):
+        return dict(vars(obj))
+    return None
+
+
+def _shallow_fields(node: Any) -> Any:
+    """`dataclasses.asdict` by reference, without the copy, and without the fields ``==`` leaves out."""
+    if dataclasses.is_dataclass(node) and not isinstance(node, type):
+        return {
+            field.name: _shallow_fields(getattr(node, field.name))
+            for field in dataclasses.fields(node)
+            if field.compare
+        }
+    if isinstance(node, tuple) and hasattr(node, "_fields"):
+        return type(node)(*[_shallow_fields(item) for item in node])
+    if isinstance(node, (list, tuple)):
+        return type(node)(_shallow_fields(item) for item in node)
+    if isinstance(node, dict):
+        return {_shallow_fields(key): _shallow_fields(value) for key, value in node.items()}
+    return node
+
+
+def _as_fields(value: object) -> dict | None:
+    """A plain dict as itself, anything else through `comparable_fields`."""
+    return value if isinstance(value, dict) else comparable_fields(value)
+
+
+def _plain_sequence(value: object) -> bool:
+    return isinstance(value, (list, tuple)) and not is_namedtuple(value)
+
+
 def ignore_specs(ignore: object) -> list:
     """Ignore-specs, keeping nested paths whole: a one-element tuple is just that key."""
     return [
@@ -193,6 +281,8 @@ def values_differ(value: object, other: object, config: _CompareConfig | None, *
         return False
     if config is None:
         return _guarded_not_equal(value, other)
+    if _kinds_never_equal(value, other) and _guarded_not_equal(value, other):
+        return True
     entries = _sub_diff_entries(value, other, _ROOT, config=config)
     if entries is None:
         # a leaf the walker does not decompose: `strict_types` asked here called two equal sets unequal
@@ -246,36 +336,32 @@ def mapping_differs(
         return False
     seen = seen | {pair}
 
-    if not (ignore or include or config is not None):
+    ignoring, including = key_specs_given(ignore), key_specs_given(include)
+    if not (ignoring or including or config is not None):
         return _guarded_not_equal(actual, expected)
 
-    ignores = ignore_specs(ignore) if ignore else []
-    if ignore or include:
-        includes = include_specs(include) if include else []
-        if include:
-            missing = missing_include_keys(left, includes)
-            if missing:
-                raise IncludeKeysMissingError(left, includes, missing)
-        keys_in_actual = {
-            key
-            for key in left
-            if (not ignore or not _spec_matches(key, left[key], ignores))
-            and (not include or _spec_matches(key, left[key], includes))
-        }
-        keys_in_expected = {
-            key
-            for key in right
-            if (not ignore or not _spec_matches(key, right[key], ignores))
-            and (not include or _spec_matches(key, right[key], includes))
-        }
-    else:
-        keys_in_actual = set(left)
-        keys_in_expected = set(right)
-
-    if keys_in_actual != keys_in_expected:
+    ignores = ignore_specs(ignore) if ignoring else []
+    includes = include_specs(include) if including else []
+    # read once for the whole mapping: asked per key, a five-hundred path include normalised itself five
+    # hundred times.  After `include_specs`, so a one-shot iterable is still refused under its own name
+    nested_paths = ignore_specs(include) if including else []
+    if includes:
+        missing = missing_include_keys(left, includes)
+        if missing:
+            raise IncludeKeysMissingError(left, includes, missing)
+    keys_in_actual = _kept_keys(left, ignores, includes)
+    keys_in_expected = _kept_keys(right, ignores, includes)
+    if keys_in_actual != keys_in_expected or _order_differs(actual, expected, keys_in_actual):
         return True
-    if config is not None and config.strict_types and _keyed_types_differ(actual, expected):
-        # `{True: "a"}` and `{1: "a"}` are equal to Python and not under strict types; the walk below sees only values
+    if (
+        config is not None
+        and config.strict_types
+        and _keyed_types_differ(
+            dict.fromkeys(key for key in left if key in keys_in_actual),
+            dict.fromkeys(key for key in right if key in keys_in_expected),
+        )
+    ):
+        # `{True: "a"}` and `{1: "a"}` are equal to Python and not under strict types; only the keys still compared
         return True
     for key in keys_in_actual:
         nested_left, nested_right = left[key], right[key]
@@ -285,18 +371,78 @@ def mapping_differs(
                 continue
             if decision == "leaf":
                 return True
-        nested_ignore = [entry[1:] for entry in ignores if type(entry) is tuple and entry[0] == key] if ignore else None
+        nested_ignore = (
+            [entry[1:] for entry in ignores if type(entry) is tuple and entry[0] == key] if ignoring else None
+        )
         # the nested half of an include keeps whole paths, and the level above already consumed the first segment
         nested_include = (
-            [entry[1:] for entry in ignore_specs(include) if type(entry) is tuple and entry[0] == key]
-            if include
-            else None
+            [entry[1:] for entry in nested_paths if type(entry) is tuple and entry[0] == key] if including else None
         )
-        if mapping_shaped(nested_left, check_values=False) and mapping_shaped(nested_right, check_values=False):
-            if mapping_differs(
-                nested_left, nested_right, ignore=nested_ignore, include=nested_include, config=config, seen=seen
-            ):
-                return True
-        elif values_differ(nested_left, nested_right, config):
+        if _nested_differs(
+            nested_left, nested_right, ignore=nested_ignore, include=nested_include, config=config, seen=seen
+        ):
             return True
     return False
+
+
+def _kept_keys(mapping: MappingLike, ignores: list, includes: list) -> set:
+    """The keys a comparison looks at: those no ignore-spec names, and an include-spec does when there are any."""
+    return {
+        key
+        for key in mapping
+        if not (ignores and _spec_matches(key, mapping[key], ignores))
+        and (not includes or _spec_matches(key, mapping[key], includes))
+    }
+
+
+def _order_differs(actual: object, expected: object, kept: set) -> bool:
+    """Whether two `OrderedDict` values hold the compared keys in different orders, which their `==` reads."""
+    if not (isinstance(actual, collections.OrderedDict) and isinstance(expected, collections.OrderedDict)):
+        return False
+    return [key for key in actual if key in kept] != [key for key in expected if key in kept]
+
+
+def _nested_differs(
+    left: object, right: object, *, ignore: object, include: object, config: _CompareConfig | None, seen: frozenset
+) -> bool:
+    """One value under a key, compared with the rest of the key path that reaches into it."""
+    if mapping_shaped(left, check_values=False) and mapping_shaped(right, check_values=False):
+        return mapping_differs(left, right, ignore=ignore, include=include, config=config, seen=seen)
+    if key_specs_given(ignore) or key_specs_given(include):
+        # a path that goes on into a dataclass, a model or an object is followed through its fields
+        left_fields, right_fields = comparable_fields(left), comparable_fields(right)
+        if left_fields is not None and right_fields is not None:
+            return mapping_differs(left_fields, right_fields, ignore=ignore, include=include, config=config, seen=seen)
+    return values_differ(left, right, config)
+
+
+def filtered_differs(
+    actual: object, expected: object, *, ignore: object, include: object, config: _CompareConfig | None
+) -> bool:
+    """`is_equal_to`'s verdict under ``ignore``/``include`` for a pair that is not two mappings.
+
+    The builder takes a sequence pair element by element and anything else through its fields.  A matcher
+    answering the same question takes the same route, or `match.equal_to(user, ignore="updated_at")`
+    compared ``updated_at`` anyway.  An element with no fields is compared whole, as the builder compares
+    it.  At the top a value with no fields is one the builder refuses with a `TypeError`, and a matcher,
+    which must not raise, answers that it differs.
+    """
+    if _plain_sequence(actual) and _plain_sequence(expected):
+        sequence_actual = cast("list | tuple", actual)
+        sequence_expected = cast("list | tuple", expected)
+        if len(sequence_actual) != len(sequence_expected):
+            return True
+        return any(
+            _filtered_pair_differs(item, counterpart, ignore=ignore, include=include, config=config, at_root=False)
+            for item, counterpart in zip(sequence_actual, sequence_expected, strict=True)
+        )
+    return _filtered_pair_differs(actual, expected, ignore=ignore, include=include, config=config, at_root=True)
+
+
+def _filtered_pair_differs(
+    actual: object, expected: object, *, ignore: object, include: object, config: _CompareConfig | None, at_root: bool
+) -> bool:
+    left, right = _as_fields(actual), _as_fields(expected)
+    if left is None or right is None:
+        return at_root or values_differ(actual, expected, config)
+    return mapping_differs(left, right, ignore=ignore, include=include, config=config)