rejig kernel api

bjlittle · bjlittle · commit 5eb088b5efcc · 2022-05-18T17:58:08.000+01:00
diff --git a/pytest_mpl/kernels.py b/pytest_mpl/kernels.py
@@ -2,16 +2,25 @@
 This module contains the supported hashing kernel implementations.
 
 """
-from PIL import Image
-from abc import ABC, abstractmethod
 import hashlib
+from abc import ABC, abstractmethod
+
 import imagehash
+from PIL import Image
+
+#: The default hamming distance bit tolerance for "similar" imagehash hashes.
+DEFAULT_HAMMING_TOLERANCE = 2
 
+#: The default imagehash hash size (N), resulting in a hash of N**2 bits.
+DEFAULT_HASH_SIZE = 16
 
+#: Registered kernel names.
 KERNEL_SHA256 = "sha256"
 KERNEL_PHASH = "phash"
 
 __all__ = [
+    "DEFAULT_HAMMING_TOLERANCE",
+    "DEFAULT_HASH_SIZE",
     "KERNEL_PHASH",
     "KERNEL_SHA256",
     "KernelPHash",
@@ -22,13 +31,37 @@
 
 class Kernel(ABC):
     """
-    Kernel abstract base class (ABC) which defines a common kernel API.
+    Kernel abstract base class (ABC) which defines a simple common kernel API.
 
     """
 
     def __init__(self, plugin):
+        # Containment (read-only) of the plugin allows the kernel to cherry-pick state that it requires
         self._plugin = plugin
 
+    @abstractmethod
+    def equivalent_hash(self, actual, expected, marker=None):
+        """
+        Determine whether the kernel considers the provided actual and
+        expected hashes as similar.
+
+        Parameters
+        ----------
+        actual : str
+            The hash of the test image.
+        expected : str
+            The hash of the baseline image.
+        marker : pytest.Mark
+            The test marker, which may contain kwarg options to be
+            applied to the equivalence test.
+
+        Returns
+        -------
+        bool
+            Whether the actual and expected hashes are deemed similar.
+
+        """
+
     @abstractmethod
     def generate_hash(self, buffer):
         """
@@ -47,28 +80,22 @@ def generate_hash(self, buffer):
 
         """
 
-    @abstractmethod
-    def equivalent_hash(self, actual, expected, marker=None):
+    def update_status(self, message):
         """
-        Determine whether the kernel considers the provided actual and
-        expected hashes as similar.
+        Append the kernel status message to the provided message.
 
         Parameters
         ----------
-        actual : str
-            The hash of the test image.
-        expected : str
-            The hash of the baseline image.
-        marker : pytest.Mark
-            The test marker, which may contain kwarg options to be
-            applied to the equivalence test.
+        message : str
+            The existing status message.
 
         Returns
         -------
-        bool
-            Whether the actual and expected hashes are deemed similar.
+        str
+            The updated status message.
 
         """
+        return message
 
     def update_summary(self, summary):
         """
@@ -81,7 +108,7 @@ def update_summary(self, summary):
         Returns
         -------
         dict
-            The image comparison summary.
+            The updated image comparison summary.
 
         """
         return summary
@@ -104,23 +131,34 @@ def __init__(self, plugin):
         # py.test marker kwarg
         self.option = "hamming_tolerance"
         # value may be overridden by py.test marker kwarg
-        self.hamming_tolerance = self._plugin.hamming_tolerance
+        self.hamming_tolerance = self._plugin.hamming_tolerance or DEFAULT_HAMMING_TOLERANCE
         # keep state of hash hamming distance (whole number) result
         self.hamming_distance = None
-
-    def generate_hash(self, buffer):
-        buffer.seek(0)
-        data = Image.open(buffer)
-        phash = imagehash.phash(data, hash_size=self.hash_size)
-        return str(phash)
+        # keep state of equivalence result
+        self.equivalent = None
 
     def equivalent_hash(self, actual, expected, marker=None):
         if marker:
             self.hamming_tolerance = int(marker.kwargs.get(self.option))
         actual = imagehash.hex_to_hash(actual)
         expected = imagehash.hex_to_hash(expected)
         self.hamming_distance = actual - expected
-        return self.hamming_distance <= self.hamming_tolerance
+        self.equivalent = self.hamming_distance <= self.hamming_tolerance
+        return self.equivalent
+
+    def generate_hash(self, buffer):
+        buffer.seek(0)
+        data = Image.open(buffer)
+        phash = imagehash.phash(data, hash_size=self.hash_size)
+        return str(phash)
+
+    def update_status(self, message):
+        result = str() if message is None else str(message)
+        if self.equivalent is False:
+            msg = (f"Hash hamming distance of {self.hamming_distance} bits > "
+                   f"hamming tolerance of {self.hamming_tolerance} bits.")
+            result = f"{message} {msg}" if len(result) else msg
+        return result
 
     def update_summary(self, summary):
         summary["hamming_distance"] = self.hamming_distance
@@ -136,16 +174,16 @@ class KernelSHA256(Kernel):
 
     name = KERNEL_SHA256
 
+    def equivalent_hash(self, actual, expected, marker=None):
+        return actual == expected
+
     def generate_hash(self, buffer):
         buffer.seek(0)
         data = buffer.read()
         hasher = hashlib.sha256()
         hasher.update(data)
         return hasher.hexdigest()
 
-    def equivalent_hash(self, actual, expected, marker=None):
-        return actual == expected
-
 
 #: Registry of available hashing kernel factories.
 kernel_factory = {
diff --git a/pytest_mpl/plugin.py b/pytest_mpl/plugin.py
@@ -43,7 +43,7 @@
 
 import pytest
 
-from .kernels import KERNEL_SHA256, kernel_factory
+from .kernels import DEFAULT_HAMMING_TOLERANCE, DEFAULT_HASH_SIZE, KERNEL_SHA256, kernel_factory
 from .summary.html import generate_summary_basic_html, generate_summary_html
 
 SUPPORTED_FORMATS = {'html', 'json', 'basic-html'}
@@ -57,12 +57,6 @@
 #: The default matplotlib backend.
 DEFAULT_BACKEND = "agg"
 
-#: The default hamming distance bit tolerance for "similar" imagehash hashes.
-DEFAULT_HAMMING_TOLERANCE = 2
-
-#: The default imagehash hash size (N), resulting in a hash of N**2 bits.
-DEFAULT_HASH_SIZE = 16
-
 #: The default algorithm to use for image hashing.
 DEFAULT_KERNEL = KERNEL_SHA256
 
@@ -307,7 +301,7 @@ def __init__(self,
                                 DEFAULT_HAMMING_TOLERANCE)
         self.hamming_tolerance = hamming_tolerance
 
-        # Configure the hashing kernel.
+        # Configure the hashing kernel - must be done *after* kernel options.
         option = "mpl-kernel"
         kernel = config.getoption(f"--{option}") or config.getini(option)
         if kernel:
@@ -318,7 +312,7 @@ def __init__(self,
             kernel = requested
         else:
             kernel = DEFAULT_KERNEL
-        print(f"{kernel_factory=}")
+        # Create the kernel.
         self.kernel = kernel_factory[kernel](self)
 
         # Generate the containing dir for all test results
@@ -599,8 +593,10 @@ def compare_image_to_hash_library(self, item, fig, result_dir, summary=None):
         if baseline_hash is None:  # hash-missing
             summary['status'] = 'failed'
             summary['hash_status'] = 'missing'
-            summary['status_msg'] = (f"Hash for test '{hash_name}' not found in {hash_library_filename}. "
-                                     f"Generated hash is {test_hash}.")
+            msg = (f'Hash for test {hash_name!r} not found in '
+                   f'{hash_library_filename!r}. Generated hash is '
+                   f'{test_hash!r}.')
+            summary['status_msg'] = msg
         elif self.kernel.equivalent_hash(test_hash, baseline_hash):  # hash-match
             hash_comparison_pass = True
             summary['status'] = 'passed'
@@ -610,9 +606,10 @@ def compare_image_to_hash_library(self, item, fig, result_dir, summary=None):
         else:  # hash-diff
             summary['status'] = 'failed'
             summary['hash_status'] = 'diff'
-            summary['status_msg'] = (f"Hash {test_hash} doesn't match hash "
-                                     f"{baseline_hash} in library "
-                                     f"{hash_library_filename} for test {hash_name}.")
+            msg = (f"Test hash {test_hash!r} doesn't match baseline hash "
+                   f'{baseline_hash!r} in library {str(hash_library_filename)!r} '
+                   f'for test {hash_name!r}.')
+            summary['status_msg'] = self.kernel.update_status(msg)
             self.kernel.update_summary(summary)
 
         # Save the figure for later summary (will be removed later if not needed)
