assertpy2 2.13.0__tar.gz → 2.14.0__tar.gz

{assertpy2-2.13.0 → assertpy2-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.13.0
+Version: 2.14.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
@@ -188,7 +188,6 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
-- **Property-based tested**: comparison, selective-diff, matcher algebra, and collection logic are checked with [Hypothesis](https://hypothesis.readthedocs.io) against reference semantics, on top of 100% branch coverage.
 
 **Type safety**
 

{assertpy2-2.13.0 → assertpy2-2.14.0}/README.md

@@ -140,7 +140,6 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
-- **Property-based tested**: comparison, selective-diff, matcher algebra, and collection logic are checked with [Hypothesis](https://hypothesis.readthedocs.io) against reference semantics, on top of 100% branch coverage.
 
 **Type safety**
 

{assertpy2-2.13.0 → assertpy2-2.14.0}/assertpy2/__init__.py

@@ -13,7 +13,7 @@ from .assertpy import (
     soft_fail,
 )
 from .async_assertions import AsyncAssertionBuilder
-from .errors import AssertionFailure, DiffEntry, DiffResult
+from .errors import AssertionFailure, DiffEntry, DiffResult, PollSample, PollTrace
 from .file import contents_of
 from .matchers import Matcher, clear_custom_matchers, match, register_matcher, unregister_matcher
 from .snapshot import SnapshotCreatedWarning
@@ -25,6 +25,8 @@ __all__ = [
     "DiffResult",
     "Matcher",
     "NegatedBuilder",
+    "PollSample",
+    "PollTrace",
     "SnapshotCreatedWarning",
     "SoftAssertionCollector",
     "WarningLoggingAdapter",

{assertpy2-2.13.0 → assertpy2-2.14.0}/assertpy2/_compare.py

@@ -2,7 +2,7 @@
 
 ``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
+(`assertpy2._diff._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.
 
@@ -133,7 +133,7 @@ def _find_ambiguous_operand(actual, expected, _seen=None):
     return None
 
 
-def _guarded_not_equal(actual, expected) -> bool:
+def _guarded_not_equal(actual, expected, *, method="is_equal_to") -> bool:
     """``bool(actual != expected)``, converting the ambiguity raised from *inside* a container's ``==``
     (where the top-level operand gate cannot see the array member) into the actionable ``TypeError``."""
     try:
@@ -142,7 +142,18 @@ def _guarded_not_equal(actual, expected) -> bool:
         operand = _find_ambiguous_operand(actual, expected)
         if operand is None:
             raise
-        raise _array_equality_error("is_equal_to", operand) from error
+        raise _array_equality_error(method, operand) from error
+
+
+def _guarded_equal(actual, expected, *, method) -> bool:
+    """``bool(actual == expected)`` with the same nested array/frame-like guard as `_guarded_not_equal`."""
+    try:
+        return bool(actual == expected)
+    except (ValueError, TypeError) as error:
+        operand = _find_ambiguous_operand(actual, expected)
+        if operand is None:
+            raise
+        raise _array_equality_error(method, operand) from error
 
 
 def _is_real_number(value) -> bool:

assertpy2-2.14.0/assertpy2/_diff.py

@@ -0,0 +1,346 @@
+"""Recursive diff engine shared by the equality assertions and the dict error path.
+
+Three walkers coexist on purpose and must not be merged: `_build_equality_diff()` dispatches a
+top-level pair (top-level dicts are handled by `HelpersMixin._dict_err()` instead, so its ladder
+starts at namedtuples), `_sub_diff_entries()` decomposes nested values (mappings first), and
+`_walk_leaves()` iterates scalar leaves for the recursive leaf assertions.  Their dispatch orders
+differ deliberately; a shared type classifier was investigated and rejected, because a single global
+precedence changes behavior for values that quack like several container shapes at once.
+`_sequence_diff_entries()` and `_dataclass_diff_entries()` are the pieces genuinely shared by the
+diff builders.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Final
+
+from ._compare import _node_decision
+from ._introspection import is_mapping_like, is_model_dump_object, is_namedtuple
+from .errors import DiffEntry, DiffResult, _safe_repr, _safe_str
+
+__tracebackhide__ = True
+
+_SENTINEL: Final = object()
+
+
+def _sequence_diff_entries(actual, expected, prefix, seen, config=None) -> list[DiffEntry]:
+    """Diff two sequences element-by-element, recursing into nested containers.
+
+    ``seen`` must already include the ids of ``actual``/``expected`` so a self-referential element
+    is caught.  Shared by the top-level (`_build_equality_diff()`) and nested
+    (`_sub_diff_entries()`) paths so both decompose sequences identically.  Elements have no field
+    name, so a ``config`` applies only type comparators and tolerance to them.
+    """
+    entries: list[DiffEntry] = []
+    max_len = max(len(actual), len(expected))
+    for i in range(max_len):
+        path = f"{prefix}[{i}]" if prefix else f"[{i}]"
+        if i >= len(actual):
+            entries.append(DiffEntry(path=path, actual=None, expected=expected[i]))
+        elif i >= len(expected):
+            entries.append(DiffEntry(path=path, actual=actual[i], expected=None))
+        else:
+            decision = _node_decision(actual[i], expected[i], config)
+            if decision == "leaf":
+                entries.append(DiffEntry(path=path, actual=actual[i], expected=expected[i]))
+            elif decision == "recurse":
+                sub_entries = _sub_diff_entries(actual[i], expected[i], path, _seen=seen, config=config)
+                if sub_entries is not None:
+                    entries.extend(sub_entries)
+                else:
+                    entries.append(DiffEntry(path=path, actual=actual[i], expected=expected[i]))
+    return entries
+
+
+def _dataclass_diff_entries(actual, expected, prefix, seen, config=None) -> list[DiffEntry]:
+    """Diff two dataclasses over the sorted union of field names, both directions, recursing.
+
+    Reports fields present on only one side, and recurses into nested containers.  ``seen`` must
+    already include the ids of ``actual``/``expected``.  Shared by the top-level and nested paths
+    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)}
+    for field in sorted(actual_names | expected_names):
+        path = f"{prefix}.{field}"
+        if field not in expected_names:
+            entries.append(DiffEntry(path=path, actual=getattr(actual, field), expected=None))
+        elif field not in actual_names:
+            entries.append(DiffEntry(path=path, actual=None, expected=getattr(expected, field)))
+        else:
+            actual_value = getattr(actual, field)
+            expected_value = getattr(expected, field)
+            decision = _node_decision(actual_value, expected_value, config, field=field)
+            if decision == "leaf":
+                entries.append(DiffEntry(path=path, actual=actual_value, expected=expected_value))
+            elif decision == "recurse":
+                sub_entries = _sub_diff_entries(actual_value, expected_value, path, _seen=seen, config=config)
+                if sub_entries is not None:
+                    entries.extend(sub_entries)
+                else:
+                    entries.append(DiffEntry(path=path, actual=actual_value, expected=expected_value))
+    return entries
+
+
+def _build_equality_diff(
+    actual: object, expected: object, *, _prefix: str = "", _seen: set[int] | None = None, config=None
+) -> DiffResult:
+    if _seen is None:
+        _seen = set()
+    pair_key = (id(actual), id(expected))
+    if pair_key[0] in _seen or pair_key[1] in _seen:
+        return DiffResult(
+            kind="scalar",
+            entries=[DiffEntry(path=_prefix or ".", actual="<circular ref>", expected="<circular ref>")],
+        )
+    _seen = _seen | {pair_key[0], pair_key[1]}
+
+    if config is not None:
+        decision = _node_decision(actual, expected, config)
+        if decision == "equal":
+            return DiffResult(kind="scalar", entries=[])
+        if decision == "leaf":
+            return DiffResult(kind="scalar", entries=[DiffEntry(path=_prefix or ".", actual=actual, expected=expected)])
+
+    def _field_entries(field_actual: object, field_expected: object, field_path: str) -> list[DiffEntry]:
+        nested = _sub_diff_entries(field_actual, field_expected, field_path, _seen=_seen, config=config)
+        if nested is not None:
+            return nested
+        return [DiffEntry(path=field_path, actual=field_actual, expected=field_expected)]
+
+    if is_namedtuple(actual) and is_namedtuple(expected):
+        entries: list[DiffEntry] = []
+        for field in actual._fields:
+            actual_value = getattr(actual, field)
+            expected_value = getattr(expected, field, _SENTINEL)
+            path = f"{_prefix}.{field}"
+            if expected_value is _SENTINEL:
+                entries.append(DiffEntry(path=path, actual=actual_value, expected=None))
+            else:
+                decision = _node_decision(actual_value, expected_value, config, field=field)
+                if decision == "leaf":
+                    entries.append(DiffEntry(path=path, actual=actual_value, expected=expected_value))
+                elif decision == "recurse":
+                    entries.extend(_field_entries(actual_value, expected_value, path))
+        entries.extend(
+            DiffEntry(path=f"{_prefix}.{field}", actual=None, expected=getattr(expected, field))
+            for field in expected._fields
+            if not hasattr(actual, field)
+        )
+        return DiffResult(kind="namedtuple", entries=entries)
+    if (
+        dataclasses.is_dataclass(actual)
+        and not isinstance(actual, type)
+        and dataclasses.is_dataclass(expected)
+        and not isinstance(expected, type)
+    ):
+        return DiffResult(
+            kind="dataclass",
+            entries=_dataclass_diff_entries(actual, expected, _prefix, _seen, config),
+        )
+    if is_model_dump_object(actual) and is_model_dump_object(expected):
+        actual_dict = actual.model_dump()
+        expected_dict = expected.model_dump()
+        entries = []
+        for key in sorted(set(actual_dict) | set(expected_dict)):
+            path = f"{_prefix}.{key}" if _prefix else f".{key}"
+            if key not in expected_dict:
+                entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=None))
+            elif key not in actual_dict:
+                entries.append(DiffEntry(path=path, actual=None, expected=expected_dict[key]))
+            else:
+                decision = _node_decision(actual_dict[key], expected_dict[key], config, field=key)
+                if decision == "leaf":
+                    entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=expected_dict[key]))
+                elif decision == "recurse":
+                    sub_entries = _sub_diff_entries(
+                        actual_dict[key], expected_dict[key], path, _seen=_seen, config=config
+                    )
+                    if sub_entries is not None:
+                        entries.extend(sub_entries)
+                    else:
+                        entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=expected_dict[key]))
+        return DiffResult(kind="model", entries=entries)
+    if isinstance(actual, (list, tuple)) and isinstance(expected, (list, tuple)):
+        return DiffResult(
+            kind="sequence",
+            entries=_sequence_diff_entries(actual, expected, _prefix, _seen, config),
+        )
+    if isinstance(actual, (set, frozenset)) and isinstance(expected, (set, frozenset)):
+        entries = []
+        for item in sorted(actual - expected, key=_safe_repr):
+            entries.append(DiffEntry(path="extra", actual=item, expected=None))
+        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):
+        entries = []
+        actual_lines = actual.splitlines()
+        expected_lines = expected.splitlines()
+        max_len = max(len(actual_lines), len(expected_lines))
+        for i in range(max_len):
+            if i >= len(actual_lines):
+                entries.append(DiffEntry(path=f"line {i + 1}", actual=None, expected=expected_lines[i]))
+            elif i >= len(expected_lines):
+                entries.append(DiffEntry(path=f"line {i + 1}", actual=actual_lines[i], expected=None))
+            elif actual_lines[i] != expected_lines[i]:
+                entries.append(DiffEntry(path=f"line {i + 1}", actual=actual_lines[i], expected=expected_lines[i]))
+        if not entries:
+            entries.append(DiffEntry(path=".", actual=actual, expected=expected))
+        return DiffResult(kind="string", entries=entries)
+    return DiffResult(kind="scalar", entries=[DiffEntry(path=_prefix or ".", actual=actual, expected=expected)])
+
+
+def _sub_diff_entries(
+    actual: object, expected: object, prefix: str, *, _seen: set[int] | None = None, config=None
+) -> list[DiffEntry] | None:
+    """Canonical recursive diff for a value, returning path-level entries (or ``None`` for a leaf).
+
+    Recurses into mappings, dataclasses, namedtuples, model-dump objects and sequences, returning a
+    (possibly empty) list for those; anything else returns ``None`` so the caller renders a single
+    leaf entry.  The empty-list-vs-``None`` distinction lets a caller tell a recursable value whose
+    children are all ``config``-tolerated (empty list, no entry) from a genuinely differing leaf
+    (``None``, one entry).  This is the single nested engine shared by the top-level paths:
+    `_build_equality_diff()` (lists, dataclasses, ...) and the dict path
+    (`HelpersMixin._dict_err()`), which calls it with an empty ``prefix`` so the top-level dict
+    keys render bare (``b``) and nested keys render dotted (``u.b``).
+    """
+    if _seen is None:
+        _seen = set()
+    if id(actual) in _seen or id(expected) in _seen:
+        return [DiffEntry(path=prefix, actual="<circular ref>", expected="<circular ref>")]
+
+    if is_mapping_like(actual) and is_mapping_like(expected):
+        child_seen = _seen | {id(actual), id(expected)}
+        entries: list[DiffEntry] = []
+        actual_keys = set(actual)
+        expected_keys = set(expected)
+        for key in sorted(actual_keys | expected_keys, key=_safe_repr):
+            path = f"{prefix}.{_safe_str(key)}" if prefix else _safe_str(key)
+            if key not in expected_keys:
+                entries.append(DiffEntry(path=path, actual=actual[key], expected=None))
+            elif key not in actual_keys:
+                entries.append(DiffEntry(path=path, actual=None, expected=expected[key]))
+            else:
+                decision = _node_decision(actual[key], expected[key], config, field=key)
+                if decision == "leaf":
+                    entries.append(DiffEntry(path=path, actual=actual[key], expected=expected[key]))
+                elif decision == "recurse":
+                    sub_entries = _sub_diff_entries(actual[key], expected[key], path, _seen=child_seen, config=config)
+                    if sub_entries is not None:
+                        entries.extend(sub_entries)
+                    else:
+                        entries.append(DiffEntry(path=path, actual=actual[key], expected=expected[key]))
+        return entries
+    if (
+        dataclasses.is_dataclass(actual)
+        and not isinstance(actual, type)
+        and dataclasses.is_dataclass(expected)
+        and not isinstance(expected, type)
+    ):
+        child_seen = _seen | {id(actual), id(expected)}
+        return _dataclass_diff_entries(actual, expected, prefix, child_seen, config)
+    if is_namedtuple(actual) and is_namedtuple(expected):
+        child_seen = _seen | {id(actual), id(expected)}
+        entries = []
+        for field_name in actual._fields:
+            actual_value = getattr(actual, field_name)
+            expected_value = getattr(expected, field_name, _SENTINEL)
+            if expected_value is _SENTINEL:
+                entries.append(DiffEntry(path=f"{prefix}.{field_name}", actual=actual_value, expected=None))
+            else:
+                decision = _node_decision(actual_value, expected_value, config, field=field_name)
+                if decision == "leaf":
+                    entries.append(
+                        DiffEntry(path=f"{prefix}.{field_name}", actual=actual_value, expected=expected_value)
+                    )
+                elif decision == "recurse":
+                    sub_entries = _sub_diff_entries(
+                        actual_value, expected_value, f"{prefix}.{field_name}", _seen=child_seen, config=config
+                    )
+                    if sub_entries is not None:
+                        entries.extend(sub_entries)
+                    else:
+                        entries.append(
+                            DiffEntry(path=f"{prefix}.{field_name}", actual=actual_value, expected=expected_value)
+                        )
+        for field_name in expected._fields:
+            if not hasattr(actual, field_name):
+                entries.append(
+                    DiffEntry(path=f"{prefix}.{field_name}", actual=None, expected=getattr(expected, field_name))
+                )
+        return entries
+    if is_model_dump_object(actual) and is_model_dump_object(expected):
+        child_seen = _seen | {id(actual), id(expected)}
+        actual_dict = actual.model_dump()
+        expected_dict = expected.model_dump()
+        entries = []
+        for key in sorted(set(actual_dict) | set(expected_dict)):
+            path = f"{prefix}.{key}"
+            if key not in expected_dict:
+                entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=None))
+            elif key not in actual_dict:
+                entries.append(DiffEntry(path=path, actual=None, expected=expected_dict[key]))
+            else:
+                decision = _node_decision(actual_dict[key], expected_dict[key], config, field=key)
+                if decision == "leaf":
+                    entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=expected_dict[key]))
+                elif decision == "recurse":
+                    sub_entries = _sub_diff_entries(
+                        actual_dict[key], expected_dict[key], path, _seen=child_seen, config=config
+                    )
+                    if sub_entries is not None:
+                        entries.extend(sub_entries)
+                    else:
+                        entries.append(DiffEntry(path=path, actual=actual_dict[key], expected=expected_dict[key]))
+        return entries
+    if isinstance(actual, (list, tuple)) and isinstance(expected, (list, tuple)):
+        child_seen = _seen | {id(actual), id(expected)}
+        return _sequence_diff_entries(actual, expected, prefix, child_seen, config)
+    return None
+
+
+def _walk_leaves(value, prefix="", _seen=None):
+    """Yield ``(path, leaf)`` for every scalar leaf of an object graph, depth-first.
+
+    Recurses into the same containers as the rich-diff engine (`_sub_diff_entries()`): mappings,
+    dataclasses, namedtuples, model-dump objects, lists and tuples.  Anything else - scalars, strings,
+    sets, opaque objects - is yielded as a single leaf, so the paths match the diffs.  A circular
+    reference yields one ``(path, "<circular ref>")`` leaf and stops, mirroring the cycle guard.
+    """
+    if _seen is None:
+        _seen = set()
+    if id(value) in _seen:
+        yield (prefix or ".", "<circular ref>")
+        return
+    if is_mapping_like(value):
+        child_seen = _seen | {id(value)}
+        for key in value:
+            yield from _walk_leaves(value[key], f"{prefix}.{_safe_str(key)}" if prefix else _safe_str(key), child_seen)
+        return
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        child_seen = _seen | {id(value)}
+        for field in dataclasses.fields(value):
+            path = f"{prefix}.{field.name}" if prefix else field.name
+            yield from _walk_leaves(getattr(value, field.name), path, child_seen)
+        return
+    if is_namedtuple(value):
+        child_seen = _seen | {id(value)}
+        for field_name in value._fields:
+            path = f"{prefix}.{field_name}" if prefix else field_name
+            yield from _walk_leaves(getattr(value, field_name), path, child_seen)
+        return
+    if is_model_dump_object(value):
+        child_seen = _seen | {id(value)}
+        dumped = value.model_dump()
+        for key in dumped:
+            yield from _walk_leaves(dumped[key], f"{prefix}.{key}" if prefix else str(key), child_seen)
+        return
+    if isinstance(value, (list, tuple)):
+        child_seen = _seen | {id(value)}
+        for index, item in enumerate(value):
+            yield from _walk_leaves(item, f"{prefix}[{index}]" if prefix else f"[{index}]", child_seen)
+        return
+    yield (prefix or ".", value)

{assertpy2-2.13.0 → assertpy2-2.14.0}/assertpy2/_introspection.py

@@ -9,7 +9,14 @@ models (``model_dump``), ``attrs`` classes (``__attrs_attrs__``) and namedtuples
 
 from __future__ import annotations
 
-from typing import Any, Protocol, TypeGuard, runtime_checkable
+from typing import Any, Final, Protocol, TypeGuard, runtime_checkable
+
+# Exact builtin types whose instances cannot carry protocol members (no instance ``__dict__``), so the
+# expensive ``runtime_checkable`` isinstance (getattr_static per member) is skipped for them.  Exact
+# types only: subclasses always take the full structural check.
+_ATOMIC_TYPES: Final = frozenset(
+    {type(None), bool, int, float, complex, str, bytes, bytearray, list, tuple, set, frozenset}
+)
 
 
 @runtime_checkable
@@ -48,6 +55,8 @@ class MappingLike(Protocol):
 
 def is_model_dump_object(obj: object) -> TypeGuard[SupportsModelDump]:
     """Return whether ``obj`` exposes a callable ``model_dump()`` (e.g. a pydantic model)."""
+    if type(obj) is dict or type(obj) in _ATOMIC_TYPES:
+        return False
     return isinstance(obj, SupportsModelDump) and callable(obj.model_dump)
 
 
@@ -63,4 +72,8 @@ def is_attrs_instance(obj: object) -> TypeGuard[AttrsInstance]:
 
 def is_mapping_like(obj: object) -> TypeGuard[MappingLike]:
     """Return whether ``obj`` is dict-like: iterable with ``keys()`` and ``[]`` access."""
+    if type(obj) is dict:
+        return True
+    if type(obj) in _ATOMIC_TYPES:
+        return False
     return isinstance(obj, MappingLike) and callable(obj.keys)

{assertpy2-2.13.0 → assertpy2-2.14.0}/assertpy2/_mixin_base.py

@@ -7,7 +7,7 @@ if TYPE_CHECKING:
 
     from ._compare import _CompareConfig
     from ._compat import Self
-    from .errors import DiffEntry, DiffResult
+    from .errors import DiffResult
 
 
 class _MixinBase:
@@ -99,16 +99,6 @@ class _MixinBase:
         @staticmethod
         def _to_comparable_dict(obj: object) -> dict[str, object] | None: ...
 
-        @staticmethod
-        def _sub_diff_entries(
-            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
         _NUMERIC_COMPAREABLE: frozenset[type]
         _NUMERIC_NON_COMPAREABLE: frozenset[type]

{assertpy2-2.13.0 → assertpy2-2.14.0}/assertpy2/_typing.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    import datetime
     from collections.abc import Callable, Hashable, Iterable
     from pathlib import Path
     from typing import Any, Protocol
@@ -81,6 +82,11 @@ if TYPE_CHECKING:
         def contains_any_of(self, *items: str) -> Self: ...
         def contains_none_of(self, *items: str) -> Self: ...
         def is_unicode(self) -> Self: ...
+        # NumericMixin - lexicographic ordering
+        def is_greater_than(self, other: str) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: str) -> Self: ...
+        def is_less_than(self, other: str) -> Self: ...
+        def is_less_than_or_equal_to(self, other: str) -> Self: ...
         # ContainsMixin
         def contains(self, *items: object) -> Self: ...
         def does_not_contain(self, *items: object) -> Self: ...
@@ -215,6 +221,12 @@ if TYPE_CHECKING:
         def is_equal_to_ignoring_milliseconds(self, other: object) -> Self: ...
         def is_equal_to_ignoring_seconds(self, other: object) -> Self: ...
         def is_equal_to_ignoring_time(self, other: object) -> Self: ...
+        # NumericMixin - chronological ordering; at runtime operands must match val's exact type
+        def is_greater_than(self, other: datetime.date) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: datetime.date) -> Self: ...
+        def is_less_than(self, other: datetime.date) -> Self: ...
+        def is_less_than_or_equal_to(self, other: datetime.date) -> Self: ...
+        def is_between(self, low: datetime.date, high: datetime.date) -> Self: ...
 
     class _PathAssertion(_CoreAssertion, Protocol):
         """Assertions available for ``pathlib.Path`` values."""
@@ -245,6 +257,11 @@ if TYPE_CHECKING:
         def has_byte_at(self, index: int, expected: int) -> Self: ...
         def is_hex_equal_to(self, expected_hex: str) -> Self: ...
         def decoded_as(self, encoding: str = ...) -> _StringAssertion: ...
+        # NumericMixin - lexicographic ordering
+        def is_greater_than(self, other: bytes | bytearray) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: bytes | bytearray) -> Self: ...
+        def is_less_than(self, other: bytes | bytearray) -> Self: ...
+        def is_less_than_or_equal_to(self, other: bytes | bytearray) -> Self: ...
 
     class _InvokedAssertion(_StringAssertion, Protocol):
         """Assertions available after ``when_called_with()`` captured an exception/warning message.

{assertpy2-2.13.0 → assertpy2-2.14.0}/assertpy2/assertpy.py

@@ -49,7 +49,7 @@ from .snapshot import SnapshotMixin
 from .string import StringMixin
 from .warning import WarningMixin
 
-__version__ = "2.13.0"
+__version__ = "2.14.0"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
@@ -410,7 +410,12 @@ def add_extension(func):
     """
     if not callable(func):
         raise TypeError("func must be callable")
-    _extensions[func.__name__] = func
+    if isinstance(func, types.FunctionType):
+        # plain functions bind once here via the descriptor protocol, keeping assert_that() free of
+        # per-call grafting; the dedicated subclass keeps AssertionBuilder itself pristine on removal
+        setattr(_ExtendedBuilder, func.__name__, func)
+    else:
+        _extensions[func.__name__] = func
 
 
 def remove_extension(func):
@@ -428,13 +433,18 @@ def remove_extension(func):
     """
     if not callable(func):
         raise TypeError("func must be callable")
-    if func.__name__ in _extensions:
-        del _extensions[func.__name__]
+    if func.__name__ in vars(_ExtendedBuilder):
+        delattr(_ExtendedBuilder, func.__name__)
+    _extensions.pop(func.__name__, None)
 
 
 def _builder(val, description="", kind=None, expected=None, logger=None):
-    """Internal helper to build a new `AssertionBuilder` instance and glue on any extension methods."""
-    ab = AssertionBuilder(val, description, kind, expected, logger)
+    """Internal helper to build a new `AssertionBuilder` instance and glue on any extension methods.
+
+    Function extensions already live on `_ExtendedBuilder`; only non-function callables (which the
+    descriptor protocol cannot bind) still need per-instance grafting here.
+    """
+    ab = _ExtendedBuilder(val, description, kind, expected, logger)
     if _extensions:
         for name, func in _extensions.items():
             meth = types.MethodType(func, ab)
@@ -454,15 +464,19 @@ class WarningLoggingAdapter(logging.LoggerAdapter):
                 frame = frame.f_back
 
             previous_frame = None
-            for frame in reversed(
-                frames
-            ):  # pragma: no branch - loop always finds an assertpy frame when called from error()
+            for frame in reversed(frames):
                 for assertpy_filename in ASSERTPY_FILES:
                     if frame[0].endswith(assertpy_filename):
                         return previous_frame
                 previous_frame = frame
-
-        filename, lineno = _unwind(inspect.currentframe())
+            return None  # pragma: no cover - error() is always reached through an assertpy frame
+
+        # a user file living under a directory named "assertpy2" can shadow every frame, so the
+        # location prefix is skipped rather than crashing the warning
+        caller = _unwind(inspect.currentframe())
+        if caller is None:
+            return msg, kwargs
+        filename, lineno = caller
         return f"[{os.path.basename(filename)}:{lineno}]: {msg}", kwargs
 
 
@@ -482,6 +496,10 @@ class NegatedBuilder:
         self._builder = builder
 
     def __getattr__(self, name: str) -> object:
+        if name == "eventually":
+            # eventually() switches the chain to polling instead of asserting, so "inverting" it is
+            # meaningless and would otherwise fail loudly with a misleading message
+            raise TypeError("eventually() cannot be negated with not_; assert the inverted condition instead")
         attr = getattr(self._builder, name)
         if not callable(attr):
             return attr
@@ -590,8 +608,9 @@ class AssertionBuilder(
             val: the value to be tested (aka the actual value)
             description (str, optional): the extra error message description.  Defaults to ``''``
                 (aka empty string)
-            kind (str, optional): the kind of assertions, one of ``None``, ``soft``, or ``warn``.
-                Defaults to ``None``
+            kind (str, optional): the failure mode of the assertions, one of ``None`` (raise),
+                ``soft`` (collect), or ``warn`` (log).  Defaults to ``None``.  Unrelated to
+                [`DiffResult.kind`][assertpy2.errors.DiffResult], which is a diff category
             expected (Error, optional): the expected exception.  Defaults to ``None``
             logger (Logger, optional): the logger for warning messages.  Defaults to ``None``
         """
@@ -650,6 +669,11 @@ class AssertionBuilder(
         while a service boots, a record not yet visible) can be retried too by listing those exception
         types in ``ignoring``.
 
+        Polling itself is always strict - retrying *requires* hard failures - but the final timeout
+        failure honors the builder's mode: inside
+        [`soft_assertions()`][assertpy2.assertpy.soft_assertions] it is collected instead of raised,
+        and under [`assert_warn()`][assertpy2.assertpy.assert_warn] it is logged.
+
         Args:
             timeout: maximum seconds to keep retrying (default ``5.0``)
             interval: seconds between retries (default ``0.5``)
@@ -695,4 +719,11 @@ class AssertionBuilder(
             timeout=timeout,
             interval=interval,
             ignoring=_normalize_ignoring(ignoring),
+            kind=self.kind,
+            logger=self.logger,
         )
+
+
+class _ExtendedBuilder(AssertionBuilder):
+    """Host for user extensions: `add_extension()` installs plain functions here, so binding happens
+    once at registration and `AssertionBuilder` itself stays pristine when an extension is removed."""