From 430fa36cfc70145959191060991b67891811b651 Mon Sep 17 00:00:00 2001
From: Alexander Kuzmik <alexander.kuzmik99@gmail.com>
Date: Tue, 4 Nov 2025 12:14:46 +0100
Subject: [PATCH] Cleanup the traceback in pytest_deepassert.equals, propagate
 verbosity level to the API

---
 src/pytest_deepassert/api.py                   | 18 +++++++++++++++---
 .../diff_report/report_generator.py            | 10 +++++-----
 src/pytest_deepassert/plugin/hook.py           |  2 +-
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/src/pytest_deepassert/api.py b/src/pytest_deepassert/api.py
index 77cccd2..f67ebb6 100644
--- a/src/pytest_deepassert/api.py
+++ b/src/pytest_deepassert/api.py
@@ -1,9 +1,11 @@
 from typing import Any
 
+import pytest
+
 from pytest_deepassert import diff_report
 
 
-def equal(left: Any, right: Any) -> None:
+def equal(left: Any, right: Any, verbose_level: int = 2) -> None:
     """
     Assert that two objects are equal.
     In case of inequality, a detailed diff report is generated for an assertion.
@@ -11,7 +13,17 @@ def equal(left: Any, right: Any) -> None:
     Args:
         left: The left object.
         right: The right object.
+        verbose_level: The level of verbosity for the diff report.
     """
-    assert left == right, diff_report.format_diff_report_lines(
-        diff_report.generate_diff_report_lines(left, right) or []
+    __tracebackhide__ = True
+
+    if left == right or right == left:
+        # Check the equality from both sides to avoid unnecessary diff report generation
+        # when one of the objects a special comparison helper type, for example mock.ANY or pytest.approx(...) instance.
+        return None
+
+    diff_message = diff_report.format_diff_report_lines(
+        diff_report.generate_diff_report_lines(left, right, verbose_level=verbose_level)
+        or []
     )
+    pytest.fail(diff_message)
diff --git a/src/pytest_deepassert/diff_report/report_generator.py b/src/pytest_deepassert/diff_report/report_generator.py
index c97b8fc..ea8b5dd 100644
--- a/src/pytest_deepassert/diff_report/report_generator.py
+++ b/src/pytest_deepassert/diff_report/report_generator.py
@@ -1,4 +1,4 @@
-from typing import Any, Optional, List
+from typing import Any, List
 
 from . import compare_helpers_deepdiff_operator
 import deepdiff
@@ -9,8 +9,8 @@
 
 
 def generate_diff_report_lines(
-    expected: Any, actual: Any, **kwargs: Any
-) -> Optional[List[str]]:
+    expected: Any, actual: Any, verbose_level: int = 2, **kwargs: Any
+) -> List[str]:
     try:
         custom_operator = (
             compare_helpers_deepdiff_operator.COMPARE_HELPERS_DEEPDIFF_OPERATOR
@@ -20,14 +20,14 @@ def generate_diff_report_lines(
             expected,
             actual,
             custom_operators=[custom_operator],
-            verbose_level=2,
+            verbose_level=verbose_level,
             **kwargs,
         )
 
         return diff.pretty().split("\n")
     except Exception:
         LOGGER.debug("Failed to generate diff report", exc_info=True)
-        return None
+        return []
 
 
 def format_diff_report_lines(diff_report_lines: List[str]) -> str:
diff --git a/src/pytest_deepassert/plugin/hook.py b/src/pytest_deepassert/plugin/hook.py
index 1662fd5..b87e26f 100644
--- a/src/pytest_deepassert/plugin/hook.py
+++ b/src/pytest_deepassert/plugin/hook.py
@@ -42,7 +42,7 @@ def pytest_assertrepr_compare(
 
     diff_lines = diff_report.generate_diff_report_lines(expected=left, actual=right)
 
-    if diff_lines is None or len(diff_lines) == 0:
+    if len(diff_lines) == 0:
         return None
 
     result = []