tidy + inject kernel name to summary

Author: bjlittle

pytest_mpl/kernels.py

@@ -40,20 +40,20 @@ class Kernel(ABC):
     """
 
     def __init__(self, plugin):
-        # Containment of the plugin allows the kernel to cherry-pick required state
+        # Containment of the plugin allows the kernel to cherry-pick required state.
         self._plugin = plugin
 
     @abstractmethod
-    def equivalent_hash(self, actual, expected, marker=None):
+    def equivalent_hash(self, result, baseline, marker=None):
         """
-        Determine whether the kernel considers the provided actual and
-        expected hashes as similar.
+        Determine whether the kernel considers the provided result (actual)
+        and baseline (expected) hashes as similar.
 
         Parameters
         ----------
-        actual : str
-            The hash of the test image.
-        expected : str
+        result : str
+            The hash of the image generated by the test.
+        baseline : str
             The hash of the baseline image.
         marker : pytest.Mark
             The test marker, which may contain kwarg options to be
@@ -62,7 +62,7 @@ def equivalent_hash(self, actual, expected, marker=None):
         Returns
         -------
         bool
-            Whether the actual and expected hashes are deemed similar.
+            Whether the result and baseline hashes are deemed similar.
 
         """
 
@@ -112,17 +112,16 @@ def update_summary(self, summary):
 
         Returns
         -------
-        dict
-            The updated image comparison summary.
+        None
 
         """
-        return summary
+        summary["kernel"] = self.name
 
 
 class KernelPHash(Kernel):
     """
     Kernel that calculates a perceptual hash of an image for the
-    specified hash size (N).
+    specified hash size (N) and high frequency factor.
 
     Where the resultant perceptual hash will be composed of N**2 bits.
 
@@ -132,31 +131,37 @@ class KernelPHash(Kernel):
 
     def __init__(self, plugin):
         super().__init__(plugin)
-        # keep state of equivalence result
+        # Keep state of the equivalence result.
         self.equivalent = None
-        # keep state of hash hamming distance (whole number) result
+        # Keep state of hash hamming distance (whole number) result.
         self.hamming_distance = None
-        # value may be overridden by py.test marker kwarg
+        # Value may be overridden by py.test marker kwarg.
         self.hamming_tolerance = (
             self._plugin.hamming_tolerance or DEFAULT_HAMMING_TOLERANCE
         )
-        # the hash-size (N) defines the resultant N**2 bits hash size
+        # The hash-size (N) defines the resultant N**2 bits hash size.
         self.hash_size = self._plugin.hash_size
-        # the level of image detail or structure represented by perceptual hash
+        # The level of image detail (high freq) or structure (low freq)
+        # represented in perceptual hash thru discrete cosine transform.
         self.high_freq_factor = (
             self._plugin.high_freq_factor or DEFAULT_HIGH_FREQUENCY_FACTOR
         )
-        # py.test marker kwarg
+        # py.test marker kwarg.
         self.option = "hamming_tolerance"
 
-    def equivalent_hash(self, actual, expected, marker=None):
+    def equivalent_hash(self, result, baseline, marker=None):
         if marker:
             value = marker.kwargs.get(self.option)
             if value is not None:
+                # Override with the decorator marker value.
                 self.hamming_tolerance = int(value)
-        actual = imagehash.hex_to_hash(actual)
-        expected = imagehash.hex_to_hash(expected)
-        self.hamming_distance = actual - expected
+        # Convert string hexdigest hashes to imagehash.ImageHash instances.
+        result = imagehash.hex_to_hash(result)
+        baseline = imagehash.hex_to_hash(baseline)
+        # Unlike cryptographic hashes, perceptual hashes can measure the
+        # degree of "similarity" through hamming distance bit differences
+        # between the hashes.
+        self.hamming_distance = result - baseline
         self.equivalent = self.hamming_distance <= self.hamming_tolerance
         return self.equivalent
 
@@ -170,6 +175,7 @@ def generate_hash(self, buffer):
 
     def update_status(self, message):
         result = str() if message is None else str(message)
+        # Only update the status message for non-equivalent hash comparisons.
         if self.equivalent is False:
             msg = (
                 f"Hash hamming distance of {self.hamming_distance} bits > "
@@ -179,9 +185,9 @@ def update_status(self, message):
         return result
 
     def update_summary(self, summary):
+        super().update_summary(summary)
         summary["hamming_distance"] = self.hamming_distance
         summary["hamming_tolerance"] = self.hamming_tolerance
-        return summary
 
 
 class KernelSHA256(Kernel):
@@ -192,8 +198,13 @@ class KernelSHA256(Kernel):
 
     name = KERNEL_SHA256
 
-    def equivalent_hash(self, actual, expected, marker=None):
-        return actual == expected
+    def equivalent_hash(self, result, baseline, marker=None):
+        # Simple cryptographic hash binary comparison. Interpretation of
+        # the comparison result is that the hashes are either identical or
+        # not identical. For non-identical hashes, it is not possible to
+        # determine a heuristic of hash "similarity" due to the nature of
+        # cryptographic hashes.
+        return result == baseline
 
     def generate_hash(self, buffer):
         buffer.seek(0)

pytest_mpl/plugin.py

@@ -181,12 +181,14 @@ def pytest_addoption(parser):
     parser.addini(option, help=msg)
 
     msg = 'The hash size (N) used to generate a N**2 bit image hash.'
-    group.addoption('--mpl-hash-size', help=msg, action='store')
-    parser.addini('mpl-hash-size', help=msg)
+    option = 'mpl-hash-size'
+    group.addoption(f'--{option}', help=msg, action='store')
+    parser.addini(option, help=msg)
 
     msg = 'Hamming distance bit tolerance for similar image hashes.'
-    group.addoption('--mpl-hamming-tolerance', help=msg, action='store')
-    parser.addini('mpl-hamming-tolerance', help=msg)
+    option = 'mpl-hamming-tolerance'
+    group.addoption(f'--{option}', help=msg, action='store')
+    parser.addini(option, help=msg)
 
 
 def pytest_configure(config):
@@ -620,17 +622,17 @@ def compare_image_to_hash_library(self, item, fig, result_dir, summary=None):
         baseline_hash = hash_library.get(hash_name, None)
         summary['baseline_hash'] = baseline_hash
 
-        test_hash = self.generate_image_hash(item, fig)
-        summary['result_hash'] = test_hash
+        result_hash = self.generate_image_hash(item, fig)
+        summary['result_hash'] = result_hash
 
         if baseline_hash is None:  # hash-missing
             summary['status'] = 'failed'
             summary['hash_status'] = 'missing'
             msg = (f'Hash for test {hash_name!r} not found in '
                    f'{hash_library_filename!r}. Generated hash is '
-                   f'{test_hash!r}.')
+                   f'{result_hash!r}.')
             summary['status_msg'] = msg
-        elif self.kernel.equivalent_hash(test_hash, baseline_hash):  # hash-match
+        elif self.kernel.equivalent_hash(result_hash, baseline_hash):  # hash-match
             hash_comparison_pass = True
             summary['status'] = 'passed'
             summary['hash_status'] = 'match'
@@ -639,7 +641,7 @@ def compare_image_to_hash_library(self, item, fig, result_dir, summary=None):
         else:  # hash-diff
             summary['status'] = 'failed'
             summary['hash_status'] = 'diff'
-            msg = (f'Result hash {test_hash!r} does not match baseline hash '
+            msg = (f'Result hash {result_hash!r} does not 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)