assertpy2 2.8.0__tar.gz → 2.9.0__tar.gz

{assertpy2-2.8.0 → assertpy2-2.9.0}/.github/workflows/ci.yml

@@ -68,7 +68,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: uv sync --extra json
+        run: uv sync --extra json --group typecheck
 
       - name: Ruff check
         run: uv run ruff check .
@@ -76,5 +76,11 @@ jobs:
       - name: Ruff format check
         run: uv run ruff format --check .
 
-      - name: Type check
-        run: uv run ty check assertpy2/
+      - name: Type check (ty)
+        run: uv run ty check assertpy2/ tests/test_typing.py
+
+      - name: Type check (mypy --strict, public typing surface)
+        run: uv run mypy --strict --follow-imports=silent tests/test_typing.py
+
+      - name: Type check (pyright, public typing surface)
+        run: uv run pyright tests/test_typing.py

assertpy2-2.9.0/.github/workflows/mutation.yml

@@ -0,0 +1,63 @@
+name: Mutation
+
+on:
+  schedule:
+    - cron: "0 4 * * 1" # weekly, Monday 04:00 UTC
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        module: [base, numeric, string, contains, collection, dict, date, matchers, helpers]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --extra json --group mutation
+
+      - name: Run mutation testing
+        env:
+          MODULE: ${{ matrix.module }}
+        run: |
+          cat > cosmic-ray.toml <<EOF
+          [cosmic-ray]
+          module-path = "assertpy2/${MODULE}.py"
+          timeout = 30.0
+          excluded-modules = []
+          test-command = ".venv/bin/python -m pytest tests/ -x -q -p no:cacheprovider"
+
+          [cosmic-ray.distributor]
+          name = "local"
+          EOF
+          uv run cosmic-ray baseline cosmic-ray.toml
+          uv run cosmic-ray init cosmic-ray.toml session.sqlite
+          uv run cosmic-ray exec cosmic-ray.toml session.sqlite
+          {
+            echo "### Mutation: ${MODULE}.py"
+            echo ""
+            echo "Surviving mutants: $(uv run cr-rate session.sqlite)%"
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "::group::Surviving mutants (${MODULE}.py)"
+          uv run cr-report session.sqlite
+          echo "::endgroup::"

{assertpy2-2.8.0 → assertpy2-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.8.0
+Version: 2.9.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
@@ -66,7 +66,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-## Quick start
+## [Quick start](https://solganis.github.io/assertpy2/getting-started/)
 
 ```bash
 pip install assertpy2  # drop-in replacement for assertpy, just change the import
@@ -84,10 +84,12 @@ def test_user():
     assert_that(user).has_name("Alice")
 ```
 
-## Why fluent assertions?
+Browse the [full documentation](https://solganis.github.io/assertpy2/) for every assertion, matcher, and integration.
+
+## [Why fluent assertions?](https://solganis.github.io/assertpy2/comparison/)
 
 A fluent chain reads as one intent and replaces several bare asserts - and your IDE
-offers only the methods that fit the value's type:
+offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/type-safety/):
 
 ```py
 # bare - three statements, no autocomplete help
@@ -111,25 +113,19 @@ E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Al
 E     {'status': 'active'} != {'status': 'disabled'}
 ```
 
-assertpy2 reports the exact path to every difference:
+assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs), in color:
 
-```text
+```python
 assert_that(response).is_equal_to(expected)
---- Structured Diff ---
-diff (dict):
-  status:
-    - 'active'
-    + 'disabled'
-  user.role:
-    - 'superadmin'
-    + 'admin'
 ```
 
+<img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: status and user.role shown with their paths, removals in red and additions in green">
+
 Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
 For responses with dynamic fields (IDs, timestamps), validate a subset with
-`matches_structure()` instead of exact equality.
+[`matches_structure()`](https://solganis.github.io/assertpy2/matchers/#structural-matching) instead of exact equality.
 
-## Type-aware autocomplete
+## [Type-aware autocomplete](https://solganis.github.io/assertpy2/type-safety/)
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
 Your IDE shows only methods relevant to the value you're testing, not all 100+:
@@ -142,6 +138,8 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 
 9 type-specific Protocols instead of one `Any`. Works in PyCharm, VS Code, and any LSP-compatible editor.
 
+See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) guide for the full walkthrough.
+
 ---
 
 ## Features
@@ -170,6 +168,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - [**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**
 
@@ -191,7 +190,7 @@ See the [full documentation](https://solganis.github.io/assertpy2/) for all asse
 
 ---
 
-## Integrations
+## [Integrations](https://solganis.github.io/assertpy2/integrations/)
 
 ### Allure
 
@@ -239,6 +238,8 @@ def step_impl(context, age):
 
 Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
 
+See the [Integrations guide](https://solganis.github.io/assertpy2/integrations/) for attachment modes, configuration, and full examples.
+
 ---
 
 <p align="center">

{assertpy2-2.8.0 → assertpy2-2.9.0}/README.md

@@ -28,7 +28,7 @@
 
 ---
 
-## Quick start
+## [Quick start](https://solganis.github.io/assertpy2/getting-started/)
 
 ```bash
 pip install assertpy2  # drop-in replacement for assertpy, just change the import
@@ -46,10 +46,12 @@ def test_user():
     assert_that(user).has_name("Alice")
 ```
 
-## Why fluent assertions?
+Browse the [full documentation](https://solganis.github.io/assertpy2/) for every assertion, matcher, and integration.
+
+## [Why fluent assertions?](https://solganis.github.io/assertpy2/comparison/)
 
 A fluent chain reads as one intent and replaces several bare asserts - and your IDE
-offers only the methods that fit the value's type:
+offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/type-safety/):
 
 ```py
 # bare - three statements, no autocomplete help
@@ -73,25 +75,19 @@ E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Al
 E     {'status': 'active'} != {'status': 'disabled'}
 ```
 
-assertpy2 reports the exact path to every difference:
+assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs), in color:
 
-```text
+```python
 assert_that(response).is_equal_to(expected)
---- Structured Diff ---
-diff (dict):
-  status:
-    - 'active'
-    + 'disabled'
-  user.role:
-    - 'superadmin'
-    + 'admin'
 ```
 
+<img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: status and user.role shown with their paths, removals in red and additions in green">
+
 Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
 For responses with dynamic fields (IDs, timestamps), validate a subset with
-`matches_structure()` instead of exact equality.
+[`matches_structure()`](https://solganis.github.io/assertpy2/matchers/#structural-matching) instead of exact equality.
 
-## Type-aware autocomplete
+## [Type-aware autocomplete](https://solganis.github.io/assertpy2/type-safety/)
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
 Your IDE shows only methods relevant to the value you're testing, not all 100+:
@@ -104,6 +100,8 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 
 9 type-specific Protocols instead of one `Any`. Works in PyCharm, VS Code, and any LSP-compatible editor.
 
+See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) guide for the full walkthrough.
+
 ---
 
 ## Features
@@ -132,6 +130,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - [**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**
 
@@ -153,7 +152,7 @@ See the [full documentation](https://solganis.github.io/assertpy2/) for all asse
 
 ---
 
-## Integrations
+## [Integrations](https://solganis.github.io/assertpy2/integrations/)
 
 ### Allure
 
@@ -201,6 +200,8 @@ def step_impl(context, age):
 
 Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
 
+See the [Integrations guide](https://solganis.github.io/assertpy2/integrations/) for attachment modes, configuration, and full examples.
+
 ---
 
 <p align="center">

assertpy2-2.9.0/assertpy2/_introspection.py

@@ -0,0 +1,66 @@
+"""Runtime-checkable protocols for duck-typed object introspection.
+
+The comparison and diff code accepts arbitrary user objects, so it inspects them structurally: pydantic
+models (``model_dump``), ``attrs`` classes (``__attrs_attrs__``) and namedtuples (``_fields`` /
+``_asdict``).  Expressing those shapes as ``@runtime_checkable`` protocols lets the diff code use
+``isinstance`` checks the type checker can follow - narrowing the value instead of probing it with
+``hasattr`` and then suppressing the attribute access.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeGuard, runtime_checkable
+
+
+@runtime_checkable
+class SupportsModelDump(Protocol):
+    """A pydantic-style model exposing ``model_dump()``."""
+
+    def model_dump(self) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class NamedTupleLike(Protocol):
+    """A ``collections.namedtuple`` / ``typing.NamedTuple`` instance."""
+
+    _fields: tuple[str, ...]
+
+    def _asdict(self) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class AttrsInstance(Protocol):
+    """An ``attrs``-decorated instance exposing ``__attrs_attrs__``."""
+
+    __attrs_attrs__: tuple[Any, ...]
+
+
+@runtime_checkable
+class MappingLike(Protocol):
+    """A dict-like object that can be iterated over and subscripted by key."""
+
+    def keys(self) -> Any: ...
+
+    def __iter__(self) -> Any: ...
+
+    def __getitem__(self, key: Any) -> Any: ...
+
+
+def is_model_dump_object(obj: object) -> TypeGuard[SupportsModelDump]:
+    """Return whether ``obj`` exposes a callable ``model_dump()`` (e.g. a pydantic model)."""
+    return isinstance(obj, SupportsModelDump) and callable(obj.model_dump)
+
+
+def is_namedtuple(obj: object) -> TypeGuard[NamedTupleLike]:
+    """Return whether ``obj`` is a namedtuple instance (a ``tuple`` carrying ``_fields``/``_asdict``)."""
+    return isinstance(obj, tuple) and isinstance(obj, NamedTupleLike)
+
+
+def is_attrs_instance(obj: object) -> TypeGuard[AttrsInstance]:
+    """Return whether ``obj`` is an ``attrs``-decorated instance."""
+    return isinstance(obj, AttrsInstance)
+
+
+def is_mapping_like(obj: object) -> TypeGuard[MappingLike]:
+    """Return whether ``obj`` is dict-like: iterable with ``keys()`` and ``[]`` access."""
+    return isinstance(obj, MappingLike) and callable(obj.keys)

{assertpy2-2.8.0 → assertpy2-2.9.0}/assertpy2/_mixin_base.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-import logging
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
+    import logging
+
     from ._compat import Self
     from .errors import DiffResult
 
@@ -57,15 +58,22 @@ class _MixinBase:
 
         def _validate_close_to_args(self, val: object, other: object, tolerance: object) -> None: ...
 
-        def _check_dict_like(
+        def _is_dict_like(
+            self,
+            d: object,
+            check_keys: bool = ...,
+            check_values: bool = ...,
+            check_getitem: bool = ...,
+        ) -> bool: ...
+
+        def _require_dict_like(
             self,
             d: object,
             check_keys: bool = ...,
             check_values: bool = ...,
             check_getitem: bool = ...,
             name: str = ...,
-            return_as_bool: bool = ...,
-        ) -> bool | None: ...
+        ) -> None: ...
 
         def _check_iterable(self, val: object, check_getitem: bool = ..., name: str = ...) -> None: ...
 

{assertpy2-2.8.0 → assertpy2-2.9.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
+    from collections.abc import Callable, Hashable
     from pathlib import Path
     from typing import Any, Protocol
 
@@ -12,12 +12,17 @@ if TYPE_CHECKING:
     from .async_assertions import AsyncAssertionBuilder
     from .matchers import Matcher
 
+    # ``ignore``/``include`` accept a single key, a nested-path tuple, or a list/set/frozenset of them.
+    _KeySpecs = Hashable | list[Hashable] | set[Hashable] | frozenset[Hashable]
+
     class _CoreAssertion(Protocol):
         """Base protocol with assertions available for all types."""
 
         # BaseMixin
         def described_as(self, description: str) -> Self: ...
-        def is_equal_to(self, other: object, **kwargs: object) -> Self: ...
+        def is_equal_to(
+            self, other: object, *, ignore: _KeySpecs | None = ..., include: _KeySpecs | None = ...
+        ) -> Self: ...
         def is_not_equal_to(self, other: object) -> Self: ...
         def is_same_as(self, other: object) -> Self: ...
         def is_not_same_as(self, other: object) -> Self: ...

{assertpy2-2.8.0 → assertpy2-2.9.0}/assertpy2/assertpy.py

@@ -9,17 +9,18 @@ import logging
 import os
 import sys
 import types
-from collections.abc import Callable, Iterator
-from typing import TYPE_CHECKING, overload
+from typing import TYPE_CHECKING, Final, overload
 
 if TYPE_CHECKING:
     import datetime
     import pathlib
+    from collections.abc import Callable, Iterator
 
     from ._compat import Self
     from ._typing import (
         _BytesAssertion,
         _CallableAssertion,
+        _CoreAssertion,
         _DateAssertion,
         _DictAssertion,
         _IterableAssertion,
@@ -47,37 +48,15 @@ from .snapshot import SnapshotMixin
 from .string import StringMixin
 from .warning import WarningMixin
 
-__version__ = "2.8.0"
+__version__ = "2.9.0"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
 
-# assertpy files
-ASSERTPY_FILES = [
-    os.path.join("assertpy2", file)
-    for file in [
-        "assertpy.py",
-        "async_assertions.py",
-        "base.py",
-        "bytes_mixin.py",
-        "collection.py",
-        "contains.py",
-        "date.py",
-        "dict.py",
-        "dynamic.py",
-        "errors.py",
-        "exception.py",
-        "extracting.py",
-        "file.py",
-        "helpers.py",
-        "json_mixin.py",
-        "matchers.py",
-        "numeric.py",
-        "pytest_plugin.py",
-        "snapshot.py",
-        "string.py",
-        "warning.py",
-    ]
+# assertpy2 source files, used to strip internal frames when locating the caller for warn-mode messages.
+# Derived from the package directory so new modules are covered automatically (no hand-maintained list).
+ASSERTPY_FILES: Final = [
+    os.path.join("assertpy2", name) for name in os.listdir(os.path.dirname(__file__)) if name.endswith(".py")
 ]
 
 # soft assertions (contextvars for thread/async safety)
@@ -253,11 +232,16 @@ def assert_that(val: bytes | bytearray, description: str = "") -> _BytesAssertio
 def assert_that(val: Callable[..., object], description: str = "") -> _CallableAssertion: ...
 
 
+# Fallback returns the concrete AssertionBuilder so object- and union-typed values keep the full API.
+# The specific protocols are not assignable to AssertionBuilder, so mypy --strict reports overload-overlap
+# for each specific overload and pyright one reportOverlappingOverload; ty (the gate) does not flag it. Kept
+# intentionally - returning _CoreAssertion here would strip type-specific assertions from object/union values.
 @overload
 def assert_that(val: object, description: str = "") -> AssertionBuilder: ...
 
 
-def assert_that(val, description=""):
+# Return the common base protocol so each overload stays consistent with the impl (no reportInconsistentOverload).
+def assert_that(val, description="") -> _CoreAssertion:
     """Set the value to be tested, plus an optional description, and allow assertions to be called.
 
     This is a factory method for the :class:`AssertionBuilder`, and the single most important
@@ -613,7 +597,7 @@ class AssertionBuilder(
     def error(self, msg, *, actual=None, expected=None, diff=None) -> Self:
         """Helper to raise an ``AssertionError`` with the given message.
 
-        If an error description is set by :meth:`~assertpy.base.BaseMixin.described_as`, then that
+        If an error description is set by :meth:`~assertpy2.base.BaseMixin.described_as`, then that
         description is prepended to the error message.
 
         When structured data (``actual``, ``expected``, or ``diff``) is provided, raises

{assertpy2-2.8.0 → assertpy2-2.9.0}/assertpy2/async_assertions.py

@@ -61,15 +61,14 @@ class AsyncAssertionBuilder:
                 last_error: AssertionError | None = None
                 while True:
                     try:
-                        if inspect.iscoroutinefunction(self._func):
-                            val = await self._func()
-                        else:
-                            val = self._func()
+                        val = self._func()
+                        if inspect.isawaitable(val):
+                            val = await val
                         builder = self._builder_func(val, self._description)
                         method = getattr(builder, name)
                         method(*args, **kwargs)
                         return builder
-                    except AssertionError as exc:
+                    except AssertionError as exc:  # noqa: PERF203  # retry-on-failure needs the try/except per poll iteration
                         last_error = exc
                         if loop.time() >= deadline:
                             raise AssertionError(