assertpy2 2.3.2__py3-none-any.whl → 2.3.3__py3-none-any.whl

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/assertpy.py

@@ -73,7 +73,7 @@ from .numeric import NumericMixin
 from .snapshot import SnapshotMixin
 from .string import StringMixin
 
-__version__ = "2.3.2"
+__version__ = "2.3.3"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch

assertpy2/matchers.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 import uuid as _uuid_mod
+from collections.abc import Callable
 from typing import Any, Protocol, runtime_checkable
 
 
@@ -547,6 +548,65 @@ class StructureMatcher(BaseMatcher):
         return f"{{{', '.join(parts)}}}"
 
 
+# --- Custom matcher registry ---
+
+_custom_matchers: dict[str, Callable[..., BaseMatcher]] = {}
+
+
+def register_matcher(name: str) -> Callable[[Callable[..., BaseMatcher]], Callable[..., BaseMatcher]]:
+    """Register a custom matcher factory on the ``match`` namespace.
+
+    Args:
+        name: the name to register on ``match`` (e.g. ``"is_valid_email"``)
+
+    Returns:
+        A decorator that registers the wrapped function and returns it unchanged.
+
+    Examples:
+        Register a simple matcher::
+
+            @register_matcher("is_valid_email")
+            def is_valid_email():
+                return match.matches_regex(r"^[\\w.-]+@[\\w.-]+\\.\\w+$")
+
+            assert_that(email).satisfies(match.is_valid_email())
+
+        Register a parametrised matcher::
+
+            @register_matcher("has_status")
+            def has_status(expected: str):
+                return match.has_property("status", match.equal_to(expected))
+
+            assert_that(order).satisfies(match.has_status("active"))
+    """
+    if not isinstance(name, str):
+        raise TypeError("name must be a string")
+    if not name.isidentifier():
+        raise ValueError(f"name must be a valid Python identifier, got {name!r}")
+
+    def decorator(func: Callable[..., BaseMatcher]) -> Callable[..., BaseMatcher]:
+        if not callable(func):
+            raise TypeError("func must be callable")
+        _custom_matchers[name] = func
+        return func
+
+    return decorator
+
+
+def unregister_matcher(name: str) -> None:
+    """Remove a previously registered custom matcher.
+
+    Args:
+        name: the matcher name to remove
+
+    Raises:
+        KeyError: if the name is not registered
+    """
+    if name not in _custom_matchers:
+        raise KeyError(f"no custom matcher registered with name {name!r}")
+    del _custom_matchers[name]
+
+
 # --- Namespace ---
 
 
@@ -705,5 +765,12 @@ class _MatchNamespace:
     def structure(spec: dict) -> StructureMatcher:
         return StructureMatcher(spec)
 
+    def __getattr__(self, name: str) -> Callable[..., BaseMatcher]:
+        try:
+            factory = _custom_matchers[name]
+        except KeyError:
+            raise AttributeError(f"match has no matcher {name!r}") from None
+        return factory
+
 
 match = _MatchNamespace()

assertpy2/string.py

@@ -519,3 +519,93 @@ class StringMixin(_MixinBase):
         if not isinstance(self.val, str):
             return self.error(f"Expected <{self.val}> to be unicode, but was <{type(self.val).__name__}>.")
         return self
+
+    def extracting_group(self, pattern: str, group: int | str = 0) -> Self:
+        """Search val for ``pattern`` and return a new builder whose val is the captured group.
+
+        Args:
+            pattern: the regular expression pattern (must contain at least one group)
+            group: the group index (int) or name (str) to extract. Defaults to ``0``
+                (the entire match).
+
+        Examples:
+            Usage with positional groups::
+
+                assert_that("status=200 path=/api").extracting_group(r"status=(\\d+)", 1).is_equal_to("200")
+
+            Usage with named groups::
+
+                assert_that("2024-01-15 ERROR").extracting_group(
+                    r"(?P<level>\\w+)$", "level"
+                ).is_equal_to("ERROR")
+
+        Returns:
+            AssertionBuilder: a **new** builder whose val is the extracted group string
+
+        Raises:
+            TypeError: if val is not a string or pattern is not a string
+            ValueError: if pattern is empty
+            AssertionError: if the pattern does not match val or the group does not exist
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if not isinstance(pattern, str):
+            raise TypeError("given pattern arg must be a string")
+        if len(pattern) == 0:
+            raise ValueError("given pattern arg must not be empty")
+        m = re.search(pattern, self.val)
+        if m is None:
+            return self.error(f"Expected <{self.val}> to match pattern <{pattern}>, but did not.")
+        try:
+            extracted = m.group(group)
+        except IndexError:
+            return self.error(f"Expected pattern <{pattern}> to have group <{group}>, but it does not.")
+        if extracted is None:
+            return self.error(
+                f"Expected group <{group}> of pattern <{pattern}> to be matched in <{self.val}>, but it was not."
+            )
+        return self.builder(extracted, self.description, self.kind)
+
+    def matches_with_groups(self, pattern: str) -> Self:
+        """Search val for ``pattern`` and return a new builder whose val is the tuple of all groups.
+
+        If the pattern contains **named** groups, the builder val is a ``dict``
+        of ``{name: value}`` for all named groups.  Otherwise it is the
+        ``tuple`` returned by ``Match.groups()``.
+
+        Args:
+            pattern: the regular expression pattern with one or more groups
+
+        Examples:
+            Positional groups::
+
+                assert_that("2024-01-15 ERROR").matches_with_groups(
+                    r"(\\d{4}-\\d{2}-\\d{2}) (\\w+)"
+                ).is_length(2)
+
+            Named groups::
+
+                assert_that("status=200").matches_with_groups(
+                    r"(?P<key>\\w+)=(?P<val>\\w+)"
+                ).contains_key("key").contains_key("val")
+
+        Returns:
+            AssertionBuilder: a **new** builder whose val is the groups tuple or groupdict
+
+        Raises:
+            TypeError: if val is not a string or pattern is not a string
+            ValueError: if pattern is empty
+            AssertionError: if the pattern does not match val
+        """
+        if not isinstance(self.val, str):
+            raise TypeError("val is not a string")
+        if not isinstance(pattern, str):
+            raise TypeError("given pattern arg must be a string")
+        if len(pattern) == 0:
+            raise ValueError("given pattern arg must not be empty")
+        m = re.search(pattern, self.val)
+        if m is None:
+            return self.error(f"Expected <{self.val}> to match pattern <{pattern}>, but did not.")
+        groupdict = m.groupdict()
+        result = groupdict if groupdict else m.groups()
+        return self.builder(result, self.description, self.kind)

{assertpy2-2.3.2.dist-info → assertpy2-2.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.3.2
+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
@@ -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>
+  <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/badge/type--checker-ty-blue" alt="ty"></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.2.dist-info → assertpy2-2.3.3.dist-info}/RECORD

@@ -1,7 +1,7 @@
-assertpy2/__init__.py,sha256=qWkj2DcIPGMFANMff8rF9PKMl4a-D-vE1_o1BiKmTEc,703
+assertpy2/__init__.py,sha256=QAaBt_YH4owfEJ3BybdaBLuZlY2IUqs8dW0kWb0e2tA,791
 assertpy2/_mixin_base.py,sha256=3g_bcRPNjZI6waSfvDcBXlCSuSQu7oc3E8qssJ4bTjU,2485
 assertpy2/_typing.py,sha256=lHwVYbqdT8KXEd9UM5X40OmoTXY9wX74AXHFMUN42k0,8857
-assertpy2/assertpy.py,sha256=SGImQJbEGIqsGYpxza8nlznxSQP52xcNc6jbAgyUhuA,20089
+assertpy2/assertpy.py,sha256=HmGlrfvolnsK6DgVPq-Pfn0eFP6YOkidZJDkF3Mu-6s,20089
 assertpy2/async_assertions.py,sha256=LXscgWxLTcGT9uz0Z3WlCmMngS0-AdbqRb7b27u36-c,2838
 assertpy2/base.py,sha256=uz9NXGxwmPS1RFBqOFMS3lOy1UvGehT5gZF4KYoqRs0,25554
 assertpy2/behave_matchers.py,sha256=UoRqYh8RECJLe8w0k622rcudP95fXku4n7aXBiQxGG0,2292
@@ -15,14 +15,14 @@ assertpy2/exception.py,sha256=I_zAJx-wZtTQkB1a4EhL5sniAqypedQn4FtFQY5G0qk,6752
 assertpy2/extracting.py,sha256=kYPLCif4_1MUlJNMSid7EcaTz7SuHzPedspk1Jc_ysw,10367
 assertpy2/file.py,sha256=rVUofKCUOLyPzFQctxwOhF0OZCrx0Evb361Air4JynM,9575
 assertpy2/helpers.py,sha256=sxj9NmbHsFOsY-FGgyYLHe7dVhwBT6qX9wT6QoYK7TE,13688
-assertpy2/matchers.py,sha256=GAf29rQ2q_1u_UaK1c4QTYW4sNcDmLfdoVvlccXC2Qk,20494
+assertpy2/matchers.py,sha256=k94k7i5N_GVnmrfAxegsLGFubHHcw57PFP3zCuNQ-wU,22607
 assertpy2/numeric.py,sha256=sHiSxbXF3XD9A16dB0gcMxe2bTrtPKJCxe1OLIvjSGY,21950
 assertpy2/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 assertpy2/pytest_plugin.py,sha256=H68GieYEX9n9Exsgmuo1Y93zOYV1oVPfAhvNuNu8d3M,3390
 assertpy2/snapshot.py,sha256=ccdkeXXz11bhEL90iL0ohWhHYJA95K85vhs0y6an1ys,9092
-assertpy2/string.py,sha256=Xwz1ZYVMMwlf9b-VsSWUF_DuTdEe40yye4J-7B0Sbjg,19826
-assertpy2-2.3.2.dist-info/METADATA,sha256=GM_01bU4DWwyr4xV0hJz_J9fcgz4bAqe9FbxynNRdlQ,16617
-assertpy2-2.3.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-assertpy2-2.3.2.dist-info/entry_points.txt,sha256=G7urMRSkSAWVlne6Jzwv_5U5I-Ru4IKKEUb1xADEDCY,47
-assertpy2-2.3.2.dist-info/licenses/LICENSE,sha256=tugsGV7w81349vK3IDCgB1FqfiqRZMcJiyWY5N55t4A,1564
-assertpy2-2.3.2.dist-info/RECORD,,
+assertpy2/string.py,sha256=0Cc_ow28gTHZRqNrz6T8zxhbsyIl1gs1JCamX6jRoV8,23621
+assertpy2-2.3.3.dist-info/METADATA,sha256=sgWV29WffqbQ0QC9o36nPKBn6pizq_Ap8OA5kAOYiNI,18507
+assertpy2-2.3.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+assertpy2-2.3.3.dist-info/entry_points.txt,sha256=G7urMRSkSAWVlne6Jzwv_5U5I-Ru4IKKEUb1xADEDCY,47
+assertpy2-2.3.3.dist-info/licenses/LICENSE,sha256=tugsGV7w81349vK3IDCgB1FqfiqRZMcJiyWY5N55t4A,1564
+assertpy2-2.3.3.dist-info/RECORD,,