assertpy2 2.3.1__tar.gz → 2.3.3__tar.gz

{assertpy2-2.3.1 → assertpy2-2.3.3}/.github/workflows/ci.yml

@@ -64,3 +64,6 @@ jobs:
 
       - name: Ruff format check
         run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run ty check assertpy2/

{assertpy2-2.3.1 → assertpy2-2.3.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.3.1
-Summary: Fluent assertion library for Python with full type safety and soft assertions
+Version: 2.3.3
+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
 Project-URL: Issues, https://github.com/Solganis/assertpy2/issues
@@ -52,9 +52,11 @@ Description-Content-Type: text/markdown
   <a href="https://pepy.tech/projects/assertpy2"><img src="https://static.pepy.tech/badge/assertpy2/month" alt="Downloads"></a>
   <a href="https://pypi.org/project/assertpy2/"><img src="https://img.shields.io/pypi/pyversions/assertpy2" alt="Python"></a>
   <a href="https://codecov.io/gh/Solganis/assertpy2"><img src="https://codecov.io/gh/Solganis/assertpy2/graph/badge.svg" alt="Coverage"></a>
-  <a href="https://github.com/Solganis/assertpy2/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Solganis/assertpy2" alt="License"></a>
+  <br>
+  <a href="https://github.com/Solganis/assertpy2/blob/main/docs/api.md"><img src="https://img.shields.io/badge/Docs-Read%20The%20Docs-black" alt="Documentation"></a>
   <a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
   <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"></a>
+  <a href="https://github.com/astral-sh/ty"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json" alt="ty"></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/assertpy2"><img src="https://api.scorecard.dev/projects/github.com/Solganis/assertpy2/badge" alt="OpenSSF Scorecard"></a>
   <a href="https://www.bestpractices.dev/projects/12990"><img src="https://www.bestpractices.dev/projects/12990/badge" alt="OpenSSF Best Practices"></a>
 </p>
@@ -173,6 +175,8 @@ assert_that(items).is_type_of(list).is_length(3).contains("admin")
 - **Snapshot testing**: store and compare data structures in JSON format, inspired by Jest.
 - **Allure integration**: auto-attach structured diff and actual/expected data to Allure reports.
 - **Behave step matchers**: ready-made parameter types (`PositiveInt`, `BoolLike`, etc.) for Behave step definitions.
+- **Custom matchers**: register domain-specific matchers via `register_matcher()`, composable with `&`, `|`, `~`.
+- **Regex group extraction**: `extracting_group()` and `matches_with_groups()` to assert on regex captures fluently.
 - **Extensions**: add custom assertions via `add_extension()`.
 - Strings, numbers, lists, tuples, sets, dicts, dates, booleans, objects, exceptions.
 
@@ -348,6 +352,51 @@ assert_that(fred).has_shoe_size(12)
 assert_that({"a": 1, "b": 2, "c": 3}).snapshot()
 ```
 
+### Custom matchers
+
+Register domain-specific matchers on the `match` namespace with `register_matcher()`:
+
+```py
+from assertpy2 import assert_that, match, register_matcher
+
+@register_matcher("is_valid_email")
+def is_valid_email():
+    return match.matches_regex(r"^[\w.-]+@[\w.-]+\.\w+$")
+
+# parametrised matchers
+@register_matcher("has_status")
+def has_status(expected: str):
+    return match.has_property("status", match.equal_to(expected))
+
+# use everywhere matchers are accepted
+assert_that("alice@example.com").satisfies(match.is_valid_email())
+assert_that(users).extracting("email").each(match.is_valid_email())
+assert_that(data).matches_structure({"email": match.is_valid_email()})
+
+# composition works automatically
+assert_that(email).satisfies(match.is_valid_email() & match.contains_string("@company.com"))
+```
+
+Remove with `unregister_matcher("is_valid_email")`.
+
+### Regex group extraction
+
+Extract regex groups and continue the fluent chain:
+
+```py
+log = "2024-01-15 ERROR status=500 path=/api/users"
+
+# extract a positional group
+assert_that(log).extracting_group(r"status=(\d+)", 1).is_equal_to("500")
+
+# extract a named group
+assert_that(log).extracting_group(r"(?P<level>\w+) status", "level").is_equal_to("ERROR")
+
+# get all groups as a tuple or dict (named groups)
+assert_that("key=value").matches_with_groups(r"(?P<k>\w+)=(?P<v>\w+)") \
+    .contains_entry({"k": "key"}).contains_entry({"v": "value"})
+```
+
 ### Extensions
 
 ```py

{assertpy2-2.3.1 → assertpy2-2.3.3}/README.md

@@ -17,9 +17,11 @@
   <a href="https://pepy.tech/projects/assertpy2"><img src="https://static.pepy.tech/badge/assertpy2/month" alt="Downloads"></a>
   <a href="https://pypi.org/project/assertpy2/"><img src="https://img.shields.io/pypi/pyversions/assertpy2" alt="Python"></a>
   <a href="https://codecov.io/gh/Solganis/assertpy2"><img src="https://codecov.io/gh/Solganis/assertpy2/graph/badge.svg" alt="Coverage"></a>
-  <a href="https://github.com/Solganis/assertpy2/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Solganis/assertpy2" alt="License"></a>
+  <br>
+  <a href="https://github.com/Solganis/assertpy2/blob/main/docs/api.md"><img src="https://img.shields.io/badge/Docs-Read%20The%20Docs-black" alt="Documentation"></a>
   <a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
   <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"></a>
+  <a href="https://github.com/astral-sh/ty"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json" alt="ty"></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/assertpy2"><img src="https://api.scorecard.dev/projects/github.com/Solganis/assertpy2/badge" alt="OpenSSF Scorecard"></a>
   <a href="https://www.bestpractices.dev/projects/12990"><img src="https://www.bestpractices.dev/projects/12990/badge" alt="OpenSSF Best Practices"></a>
 </p>
@@ -138,6 +140,8 @@ assert_that(items).is_type_of(list).is_length(3).contains("admin")
 - **Snapshot testing**: store and compare data structures in JSON format, inspired by Jest.
 - **Allure integration**: auto-attach structured diff and actual/expected data to Allure reports.
 - **Behave step matchers**: ready-made parameter types (`PositiveInt`, `BoolLike`, etc.) for Behave step definitions.
+- **Custom matchers**: register domain-specific matchers via `register_matcher()`, composable with `&`, `|`, `~`.
+- **Regex group extraction**: `extracting_group()` and `matches_with_groups()` to assert on regex captures fluently.
 - **Extensions**: add custom assertions via `add_extension()`.
 - Strings, numbers, lists, tuples, sets, dicts, dates, booleans, objects, exceptions.
 
@@ -313,6 +317,51 @@ assert_that(fred).has_shoe_size(12)
 assert_that({"a": 1, "b": 2, "c": 3}).snapshot()
 ```
 
+### Custom matchers
+
+Register domain-specific matchers on the `match` namespace with `register_matcher()`:
+
+```py
+from assertpy2 import assert_that, match, register_matcher
+
+@register_matcher("is_valid_email")
+def is_valid_email():
+    return match.matches_regex(r"^[\w.-]+@[\w.-]+\.\w+$")
+
+# parametrised matchers
+@register_matcher("has_status")
+def has_status(expected: str):
+    return match.has_property("status", match.equal_to(expected))
+
+# use everywhere matchers are accepted
+assert_that("alice@example.com").satisfies(match.is_valid_email())
+assert_that(users).extracting("email").each(match.is_valid_email())
+assert_that(data).matches_structure({"email": match.is_valid_email()})
+
+# composition works automatically
+assert_that(email).satisfies(match.is_valid_email() & match.contains_string("@company.com"))
+```
+
+Remove with `unregister_matcher("is_valid_email")`.
+
+### Regex group extraction
+
+Extract regex groups and continue the fluent chain:
+
+```py
+log = "2024-01-15 ERROR status=500 path=/api/users"
+
+# extract a positional group
+assert_that(log).extracting_group(r"status=(\d+)", 1).is_equal_to("500")
+
+# extract a named group
+assert_that(log).extracting_group(r"(?P<level>\w+) status", "level").is_equal_to("ERROR")
+
+# get all groups as a tuple or dict (named groups)
+assert_that("key=value").matches_with_groups(r"(?P<k>\w+)=(?P<v>\w+)") \
+    .contains_entry({"k": "key"}).contains_entry({"v": "value"})
+```
+
 ### Extensions
 
 ```py

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/__init__.py

@@ -12,7 +12,7 @@ from .assertpy import (
 from .async_assertions import AsyncAssertionBuilder
 from .errors import AssertionFailure, DiffEntry, DiffResult
 from .file import contents_of
-from .matchers import Matcher, match
+from .matchers import Matcher, match, register_matcher, unregister_matcher
 
 __all__ = [
     "AssertionFailure",
@@ -28,7 +28,9 @@ __all__ = [
     "contents_of",
     "fail",
     "match",
+    "register_matcher",
     "remove_extension",
     "soft_assertions",
     "soft_fail",
+    "unregister_matcher",
 ]

assertpy2-2.3.3/assertpy2/_mixin_base.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from .errors import DiffResult
+
+
+class _MixinBase:
+    if TYPE_CHECKING:
+        val: Any
+        description: str
+        kind: str | None
+        expected: type[BaseException] | None
+        logger: logging.LoggerAdapter
+        _not_expected: bool
+
+        def error(
+            self,
+            msg: str,
+            *,
+            actual: object = ...,
+            expected: object = ...,
+            diff: DiffResult | None = ...,
+        ) -> Self: ...
+
+        def builder(
+            self,
+            val: object,
+            description: str = ...,
+            kind: str | None = ...,
+            expected: BaseException | None = ...,
+            logger: logging.LoggerAdapter | None = ...,
+        ) -> Self: ...
+
+        # HelpersMixin
+
+        def _fmt_items(self, i: object) -> str: ...
+
+        def _fmt_args_kwargs(self, *some_args: object, **some_kwargs: object) -> str: ...
+
+        def _validate_between_args(self, val_type: type, low: object, high: object) -> None: ...
+
+        def _validate_close_to_args(self, val: object, other: object, tolerance: object) -> None: ...
+
+        def _check_dict_like(
+            self,
+            d: object,
+            check_keys: bool = ...,
+            check_values: bool = ...,
+            check_getitem: bool = ...,
+            name: str = ...,
+            return_as_bool: bool = ...,
+        ) -> bool | None: ...
+
+        def _check_iterable(self, val: object, check_getitem: bool = ..., name: str = ...) -> None: ...
+
+        def _dict_not_equal(
+            self,
+            val: object,
+            other: object,
+            ignore: object = ...,
+            include: object = ...,
+        ) -> bool: ...
+
+        def _dict_err(
+            self,
+            val: object,
+            other: object,
+            ignore: object = ...,
+            include: object = ...,
+        ) -> None: ...
+
+        # NumericMixin class attrs used by HelpersMixin._validate_between_args
+        _NUMERIC_COMPAREABLE: frozenset[type]
+        _NUMERIC_NON_COMPAREABLE: frozenset[type]
+
+        # Cross-mixin methods
+
+        def contains(self, *items: object) -> Self: ...
+
+        def does_not_contain(self, *items: object) -> Self: ...
+
+        def is_equal_to(self, other: object, **kwargs: object) -> Self: ...
+
+        def is_not_equal_to(self, other: object) -> Self: ...

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/assertpy.py

@@ -73,10 +73,10 @@ from .numeric import NumericMixin
 from .snapshot import SnapshotMixin
 from .string import StringMixin
 
-__version__ = "2.3.1"
+__version__ = "2.3.3"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
-contextlib.__tracebackhide__ = True  # monkey patch contextlib with clean py.test tracebacks
+contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
 
 # assertpy files
 ASSERTPY_FILES = [
@@ -475,6 +475,7 @@ class AssertionBuilder(
         self.kind = kind
         self.expected = expected
         self.logger = logger if logger else _default_logger
+        self._not_expected = False
 
     def builder(self, val, description="", kind=None, expected=None, logger=None):
         """Helper to build a new :class:`AssertionBuilder` instance. Use this only if not chaining to ``self``.

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/base.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 import collections.abc
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
 from .errors import DiffEntry, DiffResult
 from .matchers import Matcher, StructureMatcher
 
@@ -40,7 +41,7 @@ if TYPE_CHECKING:
 __tracebackhide__ = True
 
 
-class BaseMixin:
+class BaseMixin(_MixinBase):
     """Base mixin."""
 
     def described_as(self, description) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/behave_matchers.py

@@ -77,7 +77,7 @@ def register_assertpy_types() -> None:
         ImportError: if behave is not installed
     """
     try:
-        from behave import register_type
+        from behave import register_type  # ty: ignore[unresolved-import]  # optional dependency
     except ImportError:
         raise ImportError(
             "behave is required for register_assertpy_types(). Install it with: pip install assertpy2[behave]"

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/collection.py

@@ -31,13 +31,15 @@ from __future__ import annotations
 import collections
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
+
 if TYPE_CHECKING:
     from typing_extensions import Self
 
 __tracebackhide__ = True
 
 
-class CollectionMixin:
+class CollectionMixin(_MixinBase):
     """Collection assertions mixin."""
 
     def is_iterable(self) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/contains.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
 from .matchers import Matcher
 
 if TYPE_CHECKING:
@@ -39,7 +40,7 @@ if TYPE_CHECKING:
 __tracebackhide__ = True
 
 
-class ContainsMixin:
+class ContainsMixin(_MixinBase):
     """Containment assertions mixin."""
 
     def contains(self, *items) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/date.py

@@ -31,13 +31,15 @@ from __future__ import annotations
 import datetime
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
+
 if TYPE_CHECKING:
     from typing_extensions import Self
 
 __tracebackhide__ = True
 
 
-class DateMixin:
+class DateMixin(_MixinBase):
     """Date and time assertions mixin."""
 
     def is_before(self, other) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/dict.py

@@ -30,13 +30,15 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
+
 if TYPE_CHECKING:
     from typing_extensions import Self
 
 __tracebackhide__ = True
 
 
-class DictMixin:
+class DictMixin(_MixinBase):
     """Dict assertions mixin."""
 
     def contains_key(self, *keys) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/dynamic.py

@@ -30,10 +30,12 @@ from __future__ import annotations
 
 import collections
 
+from ._mixin_base import _MixinBase
+
 __tracebackhide__ = True
 
 
-class DynamicMixin:
+class DynamicMixin(_MixinBase):
     """Dynamic assertions mixin.
 
     When testing attributes of an object (or the contents of a dict), the

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/exception.py

@@ -28,7 +28,9 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
+
+from ._mixin_base import _MixinBase
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -46,7 +48,7 @@ class _InertBuilder:
         return lambda *args, **kwargs: self
 
 
-class ExceptionMixin:
+class ExceptionMixin(_MixinBase):
     """Expected exception mixin."""
 
     def raises(self, ex) -> Self:
@@ -116,15 +118,16 @@ class ExceptionMixin:
                     f" when called with ({self._fmt_args_kwargs(*some_args, **some_kwargs)}),"
                     f" but raised <{type(e).__name__}>."
                 )
-                return _InertBuilder()
+                return cast("Self", _InertBuilder())
 
         self.error(
             f"Expected <{self.val.__name__}> to raise <{self.expected.__name__}>"
             f" when called with ({self._fmt_args_kwargs(*some_args, **some_kwargs)})."
         )
-        return _InertBuilder()
+        return cast("Self", _InertBuilder())
 
     def _when_called_with_not_expected(self, *some_args, **some_kwargs) -> Self:
+        assert self.expected is not None
         try:
             self.val(*some_args, **some_kwargs)
         except BaseException as e:
@@ -134,7 +137,7 @@ class ExceptionMixin:
                     f" when called with ({self._fmt_args_kwargs(*some_args, **some_kwargs)}),"
                     f" but did raise <{type(e).__name__}>."
                 )
-                return _InertBuilder()
+                return cast("Self", _InertBuilder())
         return self
 
     def does_not_raise(self, ex) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/extracting.py

@@ -31,13 +31,15 @@ from __future__ import annotations
 import collections.abc
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
+
 if TYPE_CHECKING:
     from typing_extensions import Self
 
 __tracebackhide__ = True
 
 
-class ExtractingMixin:
+class ExtractingMixin(_MixinBase):
     """Collection flattening mixin.
 
     It is often necessary to test collections of objects.  Use the ``extracting()`` helper to

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/file.py

@@ -31,6 +31,8 @@ from __future__ import annotations
 import os
 from typing import TYPE_CHECKING
 
+from ._mixin_base import _MixinBase
+
 if TYPE_CHECKING:
     from typing_extensions import Self
 
@@ -72,17 +74,12 @@ def contents_of(file, encoding="utf-8"):
                 raise ValueError(f"val must be file or path, but was type <{type(file).__name__}>") from None
             raise
 
-    if type(contents) is bytes:
-        return contents.decode(encoding, "replace")
-    try:
+    if isinstance(contents, (bytes, bytearray)):
         return contents.decode(encoding, "replace")
-    except AttributeError:
-        pass  # contents is already a str, no decode needed
-    # if all else fails, just return the contents "as is"
     return contents
 
 
-class FileMixin:
+class FileMixin(_MixinBase):
     """File assertions mixin."""
 
     def exists(self) -> Self:

{assertpy2-2.3.1 → assertpy2-2.3.3}/assertpy2/helpers.py

@@ -33,10 +33,12 @@ import numbers
 
 from assertpy2.errors import DiffEntry, DiffResult
 
+from ._mixin_base import _MixinBase
+
 __tracebackhide__ = True
 
 
-class HelpersMixin:
+class HelpersMixin(_MixinBase):
     """Helpers mixin.  For internal use only."""
 
     def _fmt_items(self, i):