- finish support for FassertInterface

- extend readme
- fix and extend tests

Author: RootLUG

README.md

@@ -1,3 +1,7 @@
+[![PyPI version](https://badge.fury.io/py/fassert.svg)](https://badge.fury.io/py/fassert)
+![No dependencies](https://img.shields.io/badge/ZERO-Dependencies-blue)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
 ^fassert$: Fuzzy assert
 ---------------------
 
@@ -38,7 +42,9 @@ try:
     fassert([1, 2, 3], [4])
     fassert("string", b"string")  # bytes != string in fassert
 except AssertionError:
-    pass  # All the examples within the try block above will raise this exception
+    pass
+else:
+    raise RuntimeError("All examples within the try block must raise the AssertionError")
 ```
 
 In fassert, you can define a template to match your data against.
@@ -90,3 +96,36 @@ Bellow is an overview of the configurable options and their default values
 | regex_allowed                 | True          | Enable matching regexes from template agains strings in the data                       |
 | fuzzy_sequence_types          | False         | Ignore types of similar sequence types when matching the template (e.g. tuple vs list) |
 | check_minimum_sequence_length | True          | Check that the data has a minimum length of greater or equal to the template           |
+
+
+You can also define custom data types such as following:
+
+```
+from fassert import fassert, FassertInterface, FuzzyAssert
+
+class IsNumberEvenOrEqual(FassertInterface):
+    def __init__(self, value):
+        self.value = value
+
+    def __fassert__(self, other: Any, matcher: FuzzyAssert, as_template: bool) -> Literal[True]:
+        if self.value == other:
+            return True
+        elif isinstance(other, (int, float)) and int(other) % 2 == 0:
+            return True
+        
+        raise AssertionError("Data does not match the template")
+
+
+# In these examples the parameter `as_template` would be set to True as the data type is used as a template for matching
+fassert(10, IsNumberEvenOrEqual(15))
+fassert(15, IsNumberEvenOrEqual(15))
+fassert(42.0, IsNumberEvenOrEqual(15))
+
+try:
+    fassert(15, IsNumberEvenOrEqual(17))
+    fassert("some_string", IsNumberEvenOrEqual(15))
+except AssertionError:
+    pass
+else:
+    raise RuntimeError("All examples within the try block must raise the AssertionError")
+```

fassert/__init__.py

@@ -1,8 +1,8 @@
 import inspect
 from abc import ABC, abstractmethod
-from typing import Pattern, Sequence, Literal
+from typing import Pattern, Sequence, Literal, Any
 
-__version__ = "0.2"
+__version__ = "0.3"
 
 
 class FuzzyAssert:
@@ -12,7 +12,7 @@ def __init__(self):
         self.check_minimum_sequence_length = True
         self.fuzzy_sequence_types = False
 
-    def match(self, data, template) -> Literal[True]:
+    def match(self, data: Any, template: Any) -> Literal[True]:
         """
         Attempt to match the template onto the data.
         Each item in a `template` must have a match in the `data`.
@@ -24,7 +24,12 @@ def match(self, data, template) -> Literal[True]:
         :return: True if `template` matches the `data`
         :rtype: Literal[True]
         """
-        if inspect.isfunction(template):
+        if isinstance(template, FassertInterface):
+            return template.__fassert__(other=data, matcher=self, as_template=True)
+        elif isinstance(data, FassertInterface):
+            return data.__fassert__(other=template, matcher=self, as_template=False)
+
+        elif inspect.isfunction(template):
             if self.eval_functions and template(data):
                 return True
             raise AssertionError("Template function does not match the data")
@@ -41,8 +46,10 @@ def match(self, data, template) -> Literal[True]:
                 return True
             else:
                 raise AssertionError("Template does not match the data")
-        elif isinstance(data, Sequence) and isinstance(template, Sequence) and (
-                self.fuzzy_sequence_types or (type(data) == type(template))
+        elif (
+            isinstance(data, Sequence)
+            and isinstance(template, Sequence)
+            and (self.fuzzy_sequence_types or (type(data) == type(template)))
         ):
             if self.check_minimum_sequence_length and len(template) > len(data):
                 raise AssertionError(
@@ -69,7 +76,9 @@ def match(self, data, template) -> Literal[True]:
             return True
 
         if type(data) != type(template):
-            raise AssertionError(f"Template type `{type(template)}` does not match the type of data `{type(data)}`")
+            raise AssertionError(
+                f"Template type `{type(template)}` does not match the type of data `{type(data)}`"
+            )
         elif isinstance(data, dict):
             for template_key, template_value in template.items():
                 for data_key, data_value in data.items():
@@ -99,9 +108,21 @@ def match(self, data, template) -> Literal[True]:
 
 class FassertInterface(ABC):
     @abstractmethod
-    def __fassert__(self, other, matcher: FuzzyAssert) -> bool:
+    def __fassert__(
+        self, other: Any, matcher: FuzzyAssert, as_template: bool
+    ) -> Literal[True]:
+        """
+        Add a support for matching custom defined types in a recursive way
+
+        :param other: other data structure to match against
+        :param matcher: An instance of the FuzzyAssert object
+        :param as_template: Flag to indicate if you are (self) the template matching the data or the other way around
+        :raises AssertionError: When `self` does not match the `other`
+        :return: True if data is matching otherwise an AssertionError is raised
+        :rtype Literal[True]:
+        """
         ...
 
 
-def fassert(data, template) -> bool:
+def fassert(data: Any, template: Any) -> Literal[True]:
     return FuzzyAssert().match(data, template)

setup.cfg

@@ -4,6 +4,7 @@ version = attr: fassert.__version__
 author = Martin Carnogursky
 author_email = admin@sourcecode.ai
 long_description = file: README.md
+long_description_content_type = text/markdown
 url = https://github.com/SourceCode-AI/fassert
 classifiers =
     Intended Audience :: Developers

tests/test_configuration.py

@@ -37,12 +37,11 @@ def test_fuzzy_sequence_types(self):
     def test_check_minimum_sequence_length(self):
         test_data = (
             ([""], ["", ""]),
-            (["test"], [re.compile(".{4}"), "test", re.compile("^test$")])
+            (["test"], [re.compile(".{4}"), "test", re.compile("^test$")]),
         )
 
         fasserter = FuzzyAssert()
 
-
         for data, template in test_data:
             with self.subTest(data=data, template=template):
                 fasserter.check_minimum_sequence_length = True
@@ -51,13 +50,12 @@ def test_check_minimum_sequence_length(self):
                 fasserter.check_minimum_sequence_length = False
                 self.assertIs(fasserter.match(data, template), True)
 
-
     def test_regex_allowed(self):
         test_data = (
             ("", re.compile("")),
             ("test", re.compile("^test$")),
             ("test", re.compile("test")),
-            ("test", re.compile(".{4}"))
+            ("test", re.compile(".{4}")),
         )
 
         fasserter = FuzzyAssert()

tests/test_custom_types.py

@@ -0,0 +1,57 @@
+import unittest
+
+from fassert import fassert, FuzzyAssert, FassertInterface
+
+
+class ByteStringMatcher(FassertInterface):
+    def __init__(self, value):
+        self.value = value
+
+    def __fassert__(self, other, matcher, as_template):
+        if isinstance(self.value, bytes) and isinstance(other, str):
+            if self.value == other.encode():
+                return True
+        elif isinstance(self.value, str) and isinstance(other, bytes):
+            if self.value.encode() == other:
+                return True
+        elif self.value == other:
+            return True
+
+        raise AssertionError("Data does not match the template")
+
+    def __repr__(self):
+        return f"<ByteStringMatcher({repr(self.value)})>"
+
+
+class CheckIsTemplate(FassertInterface):
+    def __fassert__(self, other, matcher, as_template):
+        if as_template is not True:
+            raise AssertionError("This must be matched as template")
+        return True
+
+
+class CustomTypesTest(unittest.TestCase):
+    def test_byte_string_matcher(self):
+        test_data = (
+            (b"test", "test"),
+            (b"", ""),
+        )
+
+        for data, template in test_data:
+            with self.subTest(data=data, template=template):
+                # Normally these types would not match
+                self.assertRaises(AssertionError, fassert, data, template)
+                # Our custom interface fuzzy matches the bytes to string
+                self.assertIs(fassert(ByteStringMatcher(data), template), True)
+
+            with self.subTest(data=template, template=data):
+                self.assertRaises(AssertionError, fassert, template, data)
+                self.assertIs(fassert(ByteStringMatcher(template), data), True)
+
+    def test_check_is_template(self):
+        checker = CheckIsTemplate()
+
+        for data in ("", [], {}, 42, b"test", set()):
+            with self.subTest(data=data):
+                self.assertIs(fassert(data, checker), True)
+                self.assertRaises(AssertionError, fassert, checker, data)

tests/test_iterables.py

@@ -16,7 +16,7 @@ def test_exact_list(self):
             ("a", "42", None),
             set(),
             {"a"},
-            {"a", 42, None}
+            {"a", 42, None},
         )
         for data in test_data:
             with self.subTest(data=data):

tests/test_misc.py

@@ -1,43 +1,81 @@
 import re
 import unittest
+from typing import Literal, Any
 
 
 class ReadmeTest(unittest.TestCase):
     # Copy-paste the example code from README into this test
     def test_readme_main_example(self):
         from fassert import fassert
 
-
         # Usage: fassert(<data>, <template>)
 
         fassert("This is expected", "This is expected")
 
         fassert("This matches as well", re.compile(r"[thismachewl ]+", re.I))
 
         fassert(
-            {"key": "value", "key2": "value2"},
-            {"key": "value"}
+            {"key": "value", "key2": "value2"}, {"key": "value"}
         )  # key2: value2 is ignored as it's not defined in the template
 
         fassert(
             {"key": "value", "abc": "value"},
             # You can nest and combine the fuzzy matching types in containers
-            {re.compile(r"[a-z]{3}"): "value"}
+            {re.compile(r"[a-z]{3}"): "value"},
         )
 
         fassert(
             [1, {"very": {"nested": {"dictionary": "data"}}}, {"not": "this"}],
             # Isn't this cool?
-            [{"very": {re.compile(".{6}"): {"dictionary": lambda x: len(x) == 4}}}]
+            [{"very": {re.compile(".{6}"): {"dictionary": lambda x: len(x) == 4}}}],
         )
 
         # Template can contain callables as well
         fassert("value", lambda x: x == "value")
 
         try:
             fassert("expected", "to not match")
-            fassert({"a": "b"}, {"c": "d"})  # This will fail, {"c":"d"} is not in the target data
+            fassert(
+                {"a": "b"}, {"c": "d"}
+            )  # This will fail, {"c":"d"} is not in the target data
             fassert([1, 2, 3], [4])
             fassert("string", b"string")  # bytes != string in fassert
         except AssertionError:
-            pass  # All the examples within the try block above will raise this exception
+            pass
+        else:
+            raise RuntimeError(
+                "All examples within the try block must raise the AssertionError"
+            )
+
+    # Copy paste the custom type example in the advanced usage section over here
+    def test_advanced_custom_type_example(self):
+        from fassert import fassert, FassertInterface, FuzzyAssert
+
+        class IsNumberEvenOrEqual(FassertInterface):
+            def __init__(self, value):
+                self.value = value
+
+            def __fassert__(
+                self, other: Any, matcher: FuzzyAssert, as_template: bool
+            ) -> Literal[True]:
+                if self.value == other:
+                    return True
+                elif isinstance(other, (int, float)) and int(other) % 2 == 0:
+                    return True
+
+                raise AssertionError("Data does not match the template")
+
+        # In these examples the parameter `as_template` would be set to True as the data type is used as a template for matching
+        fassert(10, IsNumberEvenOrEqual(15))
+        fassert(15, IsNumberEvenOrEqual(15))
+        fassert(42.0, IsNumberEvenOrEqual(15))
+
+        try:
+            fassert(15, IsNumberEvenOrEqual(17))
+            fassert("some_string", IsNumberEvenOrEqual(15))
+        except AssertionError:
+            pass
+        else:
+            raise RuntimeError(
+                "All examples within the try block must raise the AssertionError"
+            )

tests/test_primitives.py

@@ -44,7 +44,6 @@ def test_same_type_different_value_not_matching(self):
             with self.subTest(data=data, template=template):
                 self.assertRaises(AssertionError, fassert, data, template)
 
-
     def test_different_types_not_matching(self):
         test_data = (
             ("", ()),