feat: add compose_matchers utility for composing 1 or more matchers (#952)

(cherry picked from commit 190a63d)

Author: noahnu

README.md

@@ -162,6 +162,28 @@ It should return the replacement value to be serialized or the original unmutate
 
 **NOTE:** Do not mutate the value received as it could cause unintended side effects.
 
+##### Composing Matchers
+
+Multiple matchers can be composed together using `matchers`, e.g.:
+
+```py
+from syrupy.matchers import compose_matchers
+
+def test_multiple_matchers(snapshot):
+    data = {
+        "number": 1,
+        "datetime": datetime.datetime.now(),
+        "float": 1.3
+    }
+
+    assert data == snapshot(
+        matcher=compose_matchers(
+            path_type(types=(int, float), replacer=lambda *_: "MATCHER_1"),
+            path_type(types=(datetime.datetime,), replacer=lambda *_: "MATCHER_2"),
+        ),
+    )
+```
+
 ##### Built-In Matchers
 
 Syrupy comes with built-in helpers that can be used to make easy work of using property matchers.

src/syrupy/matchers.py

@@ -33,6 +33,10 @@ class PathTypeError(TypeError):
     pass
 
 
+class StrictPathTypeError(PathTypeError):
+    pass
+
+
 def path_type(
     mapping: Optional[Dict[str, Tuple["PropertyValueType", ...]]] = None,
     *,
@@ -63,7 +67,7 @@ def path_type_matcher(
                         if isinstance(data, type_to_match):
                             return replacer(data, matches)
                     if strict:
-                        raise PathTypeError(
+                        raise StrictPathTypeError(
                             gettext(
                                 "{} at '{}' of type {} does not "
                                 "match any of the expected types: {}"
@@ -107,3 +111,23 @@ def _path_match(path: str, pattern: str, is_regex: bool) -> "MatchResult":
     if not is_regex:
         pattern = re.escape(pattern)
     return re.fullmatch(pattern, path)
+
+
+def compose_matchers(*matchers: "PropertyMatcher") -> "PropertyMatcher":
+    """
+    Composes 1 or more matchers into a single matcher.
+    """
+
+    def _matcher(
+        *, data: "SerializableData", path: "PropertyPath"
+    ) -> Optional["SerializableData"]:
+        for matcher in matchers:
+            try:
+                data = matcher(data=data, path=path)
+            except StrictPathTypeError:
+                # ignore strict mode when composing matchers
+                pass
+
+        return data
+
+    return _matcher

tests/syrupy/extensions/amber/__snapshots__/test_amber_matchers.ambr

@@ -54,6 +54,13 @@
     'specific_number': 5,
   })
 # ---
+# name: test_multiple_matchers
+  dict({
+    'datetime': 'MATCHER_2',
+    'float': 'MATCHER_1',
+    'number': 'MATCHER_1',
+  })
+# ---
 # name: test_raises_unexpected_type
   dict({
     'date_created': datetime,

tests/syrupy/extensions/amber/test_amber_matchers.py

@@ -9,6 +9,7 @@
 )
 from syrupy.matchers import (
     PathTypeError,
+    compose_matchers,
     path_type,
     path_value,
 )
@@ -128,3 +129,15 @@ def replacer(data, match):
         "dir": str(tmp_path),
     }
     assert actual == snapshot(matcher=my_matcher)
+
+
+def test_multiple_matchers(snapshot):
+    data = {"number": 1, "datetime": datetime.datetime.now(), "float": 1.3}
+
+    assert data == snapshot(
+        matcher=compose_matchers(
+            path_type(types=(list,), replacer=lambda *_: "DO_NOT_MATCH"),
+            path_type(types=(int, float), replacer=lambda *_: "MATCHER_1"),
+            path_type(types=(datetime.datetime,), replacer=lambda *_: "MATCHER_2"),
+        ),
+    )