assertpy2 2.3.2__tar.gz → 2.3.4__tar.gz

{assertpy2-2.3.2 → assertpy2-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.3.2
+Version: 2.3.4
 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>
@@ -158,23 +160,25 @@ assert_that(items).is_type_of(list).is_length(3).contains("admin")
 
 ## Features
 
-- **Composable matchers**: `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~` operators.
-- **Structural matching**: `matches_structure()` for declarative dict/API response validation.
-- **Async assertions**: `eventually()` with polling/retry for async and eventual consistency testing.
-- **Structured errors**: `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
+- [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~` operators.
+- [**Structural matching**](docs/api.md#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Async assertions**](docs/api.md#async-assertions): `eventually()` with polling/retry for async and eventual consistency testing.
+- [**Structured errors**](docs/api.md#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
 - **Typed overloads**: `assert_that()` returns type-specific Protocols, IDE shows only relevant methods per type.
 - **Type safety**: `Self` return types, `py.typed` ([PEP 561](https://peps.python.org/pep-0561/)).
-- **Soft assertions**: thread-safe and async-safe via `contextvars`, collect all failures with `soft_assertions()`.
-- **Fluent chaining**: write assertions as readable one-liners that chain naturally.
-- **Dynamic assertions**: `has_<name>()` for any attribute, property, or zero-argument method on objects and dicts.
-- **Dict comparison**: `is_equal_to()` with `ignore` and `include` for selective key matching.
-- **Extracting**: flatten collections on attributes with `filter` and `sort` support.
-- **File assertions**: `exists()`, `is_file()`, `is_readable()`, `is_writable()`, `is_executable()` with `pathlib.Path` support.
-- **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.
-- **Extensions**: add custom assertions via `add_extension()`.
-- Strings, numbers, lists, tuples, sets, dicts, dates, booleans, objects, exceptions.
+- [**Soft assertions**](docs/api.md#soft-assertions): thread-safe and async-safe via `contextvars`, collect all failures with `soft_assertions()`.
+- [**Fluent chaining**](docs/api.md#chaining): write assertions as readable one-liners that chain naturally.
+- [**Dynamic assertions**](docs/api.md#objects): `has_<name>()` for any attribute, property, or zero-argument method on objects and dicts.
+- [**Dict comparison**](docs/api.md#dicts): `is_equal_to()` with `ignore` and `include` for selective key matching.
+- [**Extracting**](docs/api.md#objects): flatten collections on attributes with `filter` and `sort` support.
+- [**File assertions**](docs/api.md#files): `exists()`, `is_file()`, `is_readable()`, `is_writable()`, `is_executable()` with `pathlib.Path` support.
+- [**Snapshot testing**](docs/api.md#snapshot-testing): store and compare data structures in JSON format, inspired by Jest.
+- [**Allure integration**](docs/api.md#allure-integration): auto-attach structured diff and actual/expected data to Allure reports.
+- [**Behave step matchers**](docs/api.md#behave-step-matchers): ready-made parameter types (`PositiveInt`, `BoolLike`, etc.) for Behave step definitions.
+- [**Custom matchers**](docs/api.md#custom-matchers---registering-domain-matchers): register domain-specific matchers via `register_matcher()`, composable with `&`, `|`, `~`.
+- [**Regex group extraction**](docs/api.md#regex-group-extraction): `extracting_group()` and `matches_with_groups()` to assert on regex captures fluently.
+- [**Extensions**](docs/api.md#extension-system---adding-custom-assertions): add custom assertions via `add_extension()`.
+- [Strings](docs/api.md#strings), [numbers](docs/api.md#numbers), [lists](docs/api.md#lists), [tuples](docs/api.md#tuples), [sets](docs/api.md#sets), [dicts](docs/api.md#dicts), [dates](docs/api.md#dates), [booleans](docs/api.md#booleans), [objects](docs/api.md#objects), [exceptions](docs/api.md#failure).
 
 
 ## Composable matchers
@@ -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 → assertpy2-2.3.4}/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>
+  <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>
@@ -123,23 +125,25 @@ assert_that(items).is_type_of(list).is_length(3).contains("admin")
 
 ## Features
 
-- **Composable matchers**: `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~` operators.
-- **Structural matching**: `matches_structure()` for declarative dict/API response validation.
-- **Async assertions**: `eventually()` with polling/retry for async and eventual consistency testing.
-- **Structured errors**: `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
+- [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~` operators.
+- [**Structural matching**](docs/api.md#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Async assertions**](docs/api.md#async-assertions): `eventually()` with polling/retry for async and eventual consistency testing.
+- [**Structured errors**](docs/api.md#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
 - **Typed overloads**: `assert_that()` returns type-specific Protocols, IDE shows only relevant methods per type.
 - **Type safety**: `Self` return types, `py.typed` ([PEP 561](https://peps.python.org/pep-0561/)).
-- **Soft assertions**: thread-safe and async-safe via `contextvars`, collect all failures with `soft_assertions()`.
-- **Fluent chaining**: write assertions as readable one-liners that chain naturally.
-- **Dynamic assertions**: `has_<name>()` for any attribute, property, or zero-argument method on objects and dicts.
-- **Dict comparison**: `is_equal_to()` with `ignore` and `include` for selective key matching.
-- **Extracting**: flatten collections on attributes with `filter` and `sort` support.
-- **File assertions**: `exists()`, `is_file()`, `is_readable()`, `is_writable()`, `is_executable()` with `pathlib.Path` support.
-- **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.
-- **Extensions**: add custom assertions via `add_extension()`.
-- Strings, numbers, lists, tuples, sets, dicts, dates, booleans, objects, exceptions.
+- [**Soft assertions**](docs/api.md#soft-assertions): thread-safe and async-safe via `contextvars`, collect all failures with `soft_assertions()`.
+- [**Fluent chaining**](docs/api.md#chaining): write assertions as readable one-liners that chain naturally.
+- [**Dynamic assertions**](docs/api.md#objects): `has_<name>()` for any attribute, property, or zero-argument method on objects and dicts.
+- [**Dict comparison**](docs/api.md#dicts): `is_equal_to()` with `ignore` and `include` for selective key matching.
+- [**Extracting**](docs/api.md#objects): flatten collections on attributes with `filter` and `sort` support.
+- [**File assertions**](docs/api.md#files): `exists()`, `is_file()`, `is_readable()`, `is_writable()`, `is_executable()` with `pathlib.Path` support.
+- [**Snapshot testing**](docs/api.md#snapshot-testing): store and compare data structures in JSON format, inspired by Jest.
+- [**Allure integration**](docs/api.md#allure-integration): auto-attach structured diff and actual/expected data to Allure reports.
+- [**Behave step matchers**](docs/api.md#behave-step-matchers): ready-made parameter types (`PositiveInt`, `BoolLike`, etc.) for Behave step definitions.
+- [**Custom matchers**](docs/api.md#custom-matchers---registering-domain-matchers): register domain-specific matchers via `register_matcher()`, composable with `&`, `|`, `~`.
+- [**Regex group extraction**](docs/api.md#regex-group-extraction): `extracting_group()` and `matches_with_groups()` to assert on regex captures fluently.
+- [**Extensions**](docs/api.md#extension-system---adding-custom-assertions): add custom assertions via `add_extension()`.
+- [Strings](docs/api.md#strings), [numbers](docs/api.md#numbers), [lists](docs/api.md#lists), [tuples](docs/api.md#tuples), [sets](docs/api.md#sets), [dicts](docs/api.md#dicts), [dates](docs/api.md#dates), [booleans](docs/api.md#booleans), [objects](docs/api.md#objects), [exceptions](docs/api.md#failure).
 
 
 ## Composable matchers
@@ -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.2 → assertpy2-2.3.4}/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, clear_custom_matchers, match, register_matcher, unregister_matcher
 
 __all__ = [
     "AssertionFailure",
@@ -25,10 +25,13 @@ __all__ = [
     "add_extension",
     "assert_that",
     "assert_warn",
+    "clear_custom_matchers",
     "contents_of",
     "fail",
     "match",
+    "register_matcher",
     "remove_extension",
     "soft_assertions",
     "soft_fail",
+    "unregister_matcher",
 ]

{assertpy2-2.3.2 → assertpy2-2.3.4}/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.4"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch

{assertpy2-2.3.2 → assertpy2-2.3.4}/assertpy2/matchers.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import re
+import threading
 import uuid as _uuid_mod
+from collections.abc import Callable
 from typing import Any, Protocol, runtime_checkable
 
 
@@ -116,7 +118,10 @@ class GreaterThanMatcher(BaseMatcher):
         self.boundary = boundary
 
     def matches(self, value: Any) -> bool:
-        return value > self.boundary
+        try:
+            return value > self.boundary
+        except TypeError:
+            return False
 
     def describe(self) -> str:
         return f"a value greater than <{self.boundary}>"
@@ -127,7 +132,10 @@ class GreaterThanOrEqualToMatcher(BaseMatcher):
         self.boundary = boundary
 
     def matches(self, value: Any) -> bool:
-        return value >= self.boundary
+        try:
+            return value >= self.boundary
+        except TypeError:
+            return False
 
     def describe(self) -> str:
         return f"a value greater than or equal to <{self.boundary}>"
@@ -138,7 +146,10 @@ class LessThanMatcher(BaseMatcher):
         self.boundary = boundary
 
     def matches(self, value: Any) -> bool:
-        return value < self.boundary
+        try:
+            return value < self.boundary
+        except TypeError:
+            return False
 
     def describe(self) -> str:
         return f"a value less than <{self.boundary}>"
@@ -149,7 +160,10 @@ class LessThanOrEqualToMatcher(BaseMatcher):
         self.boundary = boundary
 
     def matches(self, value: Any) -> bool:
-        return value <= self.boundary
+        try:
+            return value <= self.boundary
+        except TypeError:
+            return False
 
     def describe(self) -> str:
         return f"a value less than or equal to <{self.boundary}>"
@@ -161,7 +175,10 @@ class BetweenMatcher(BaseMatcher):
         self.high = high
 
     def matches(self, value: Any) -> bool:
-        return self.low <= value <= self.high
+        try:
+            return self.low <= value <= self.high
+        except TypeError:
+            return False
 
     def describe(self) -> str:
         return f"a value between <{self.low}> and <{self.high}>"
@@ -173,7 +190,10 @@ class CloseToMatcher(BaseMatcher):
         self.tolerance = tolerance
 
     def matches(self, value: Any) -> bool:
-        return abs(value - self.expected) <= self.tolerance
+        try:
+            return abs(value - self.expected) <= self.tolerance
+        except TypeError:
+            return False
 
     def describe(self) -> str:
         return f"a value within <{self.tolerance}> of <{self.expected}>"
@@ -501,7 +521,7 @@ class StructureMatcher(BaseMatcher):
     def matches(self, value: Any) -> bool:
         if not isinstance(value, dict):
             return False
-        return self._match_recursive(value, self._spec, "") is None
+        return self._match_recursive(value, self._spec, "", set()) is None
 
     def describe(self) -> str:
         return f"a dict matching structure {self._describe_spec(self._spec)}"
@@ -509,12 +529,16 @@ class StructureMatcher(BaseMatcher):
     def describe_mismatch(self, value: Any) -> str:
         if not isinstance(value, dict):
             return f"was not a dict: <{value}>"
-        error = self._match_recursive(value, self._spec, "")
+        error = self._match_recursive(value, self._spec, "", set())
         if error:
             return error
         return f"was <{value}>"
 
-    def _match_recursive(self, value: dict, spec: dict, path: str) -> str | None:
+    def _match_recursive(self, value: dict, spec: dict, path: str, seen: set[tuple[int, int]]) -> str | None:
+        pair_id = (id(value), id(spec))
+        if pair_id in seen:
+            return f"circular reference detected at <{path or 'root'}>"
+        seen.add(pair_id)
         for key, expected in spec.items():
             current_path = f"{path}.{key}" if path else str(key)
             if key not in value:
@@ -528,7 +552,7 @@ class StructureMatcher(BaseMatcher):
             elif isinstance(expected, dict):
                 if not isinstance(actual, dict):
                     return f"at <{current_path}>: expected a dict, but was <{actual}>"
-                error = self._match_recursive(actual, expected, current_path)
+                error = self._match_recursive(actual, expected, current_path, seen)
                 if error:
                     return error
             elif actual != expected:
@@ -547,6 +571,74 @@ class StructureMatcher(BaseMatcher):
         return f"{{{', '.join(parts)}}}"
 
 
+# --- Custom matcher registry ---
+
+_custom_matchers: dict[str, Callable[..., BaseMatcher]] = {}
+_custom_matchers_lock = threading.Lock()
+
+
+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")
+        with _custom_matchers_lock:
+            _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
+    """
+    with _custom_matchers_lock:
+        if name not in _custom_matchers:
+            raise KeyError(f"no custom matcher registered with name {name!r}")
+        del _custom_matchers[name]
+
+
+def clear_custom_matchers() -> None:
+    """Remove all registered custom matchers."""
+    with _custom_matchers_lock:
+        _custom_matchers.clear()
+
+
 # --- Namespace ---
 
 
@@ -705,5 +797,13 @@ class _MatchNamespace:
     def structure(spec: dict) -> StructureMatcher:
         return StructureMatcher(spec)
 
+    def __getattr__(self, name: str) -> Callable[..., BaseMatcher]:
+        with _custom_matchers_lock:
+            try:
+                factory = _custom_matchers[name]
+            except KeyError:
+                raise AttributeError(f"match has no matcher {name!r}") from None
+        return factory
+
 
 match = _MatchNamespace()

{assertpy2-2.3.2 → assertpy2-2.3.4}/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)