django-explain-errors 0.9.3__tar.gz → 0.10.0__tar.gz

{django_explain_errors-0.9.3/django_explain_errors.egg-info → django_explain_errors-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.9.3
+Version: 0.10.0
 Summary: Django middleware that explains unhandled exceptions in DEBUG using an LLM, optionally grounded in your own project source via a local vector index. Works with OpenAI, Claude, or any OpenAI-compatible endpoint including local models.
 Home-page: https://github.com/topunix/django-explain-errors
 Author: topunix
@@ -289,6 +289,7 @@ developer is actually investigating.
 | `EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS` | No | When `True`, skips the built-in secret/token/email redaction patterns entirely and redacts only what `EXPLAIN_ERRORS_REDACT_PATTERNS` specifies. Turning this on removes the default protection against leaking secrets and PII in tracebacks. Defaults to `False`. |
 | `EXPLAIN_ERRORS_REDACT_REPLACEMENT` | No | Replacement string substituted for anything matched by the redaction patterns. Defaults to `"[REDACTED]"`. |
 | `EXPLAIN_ERRORS_LANGUAGE` | No | Language the explanation prose is written in, as a plain name or code (for example `"Spanish"` or `"es"`). Defaults to `None`, meaning English. Exception names, identifiers, code, file paths, and tracebacks always stay in English regardless of this setting. |
+| `EXPLAIN_ERRORS_DEDUP` | No | When `True` (the default), a repeat of an error already explained in this process replays the earlier explanation instead of calling the model or using a throttle slot. Two errors are identical when they have the same exception type, the same exception message, and the same innermost project line (file, line number, and that line's source text); editing the line makes it a new error. Keeps the last 128 distinct errors per worker (least recently used entries are evicted first) and entries never expire on a timer. Set to `False` to explain every error. |
 
 ## Using local models (Ollama)
 

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0}/README.md

@@ -239,6 +239,7 @@ developer is actually investigating.
 | `EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS` | No | When `True`, skips the built-in secret/token/email redaction patterns entirely and redacts only what `EXPLAIN_ERRORS_REDACT_PATTERNS` specifies. Turning this on removes the default protection against leaking secrets and PII in tracebacks. Defaults to `False`. |
 | `EXPLAIN_ERRORS_REDACT_REPLACEMENT` | No | Replacement string substituted for anything matched by the redaction patterns. Defaults to `"[REDACTED]"`. |
 | `EXPLAIN_ERRORS_LANGUAGE` | No | Language the explanation prose is written in, as a plain name or code (for example `"Spanish"` or `"es"`). Defaults to `None`, meaning English. Exception names, identifiers, code, file paths, and tracebacks always stay in English regardless of this setting. |
+| `EXPLAIN_ERRORS_DEDUP` | No | When `True` (the default), a repeat of an error already explained in this process replays the earlier explanation instead of calling the model or using a throttle slot. Two errors are identical when they have the same exception type, the same exception message, and the same innermost project line (file, line number, and that line's source text); editing the line makes it a new error. Keeps the last 128 distinct errors per worker (least recently used entries are evicted first) and entries never expire on a timer. Set to `False` to explain every error. |
 
 ## Using local models (Ollama)
 

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0/django_explain_errors.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.9.3
+Version: 0.10.0
 Summary: Django middleware that explains unhandled exceptions in DEBUG using an LLM, optionally grounded in your own project source via a local vector index. Works with OpenAI, Claude, or any OpenAI-compatible endpoint including local models.
 Home-page: https://github.com/topunix/django-explain-errors
 Author: topunix
@@ -289,6 +289,7 @@ developer is actually investigating.
 | `EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS` | No | When `True`, skips the built-in secret/token/email redaction patterns entirely and redacts only what `EXPLAIN_ERRORS_REDACT_PATTERNS` specifies. Turning this on removes the default protection against leaking secrets and PII in tracebacks. Defaults to `False`. |
 | `EXPLAIN_ERRORS_REDACT_REPLACEMENT` | No | Replacement string substituted for anything matched by the redaction patterns. Defaults to `"[REDACTED]"`. |
 | `EXPLAIN_ERRORS_LANGUAGE` | No | Language the explanation prose is written in, as a plain name or code (for example `"Spanish"` or `"es"`). Defaults to `None`, meaning English. Exception names, identifiers, code, file paths, and tracebacks always stay in English regardless of this setting. |
+| `EXPLAIN_ERRORS_DEDUP` | No | When `True` (the default), a repeat of an error already explained in this process replays the earlier explanation instead of calling the model or using a throttle slot. Two errors are identical when they have the same exception type, the same exception message, and the same innermost project line (file, line number, and that line's source text); editing the line makes it a new error. Keeps the last 128 distinct errors per worker (least recently used entries are evicted first) and entries never expire on a timer. Set to `False` to explain every error. |
 
 ## Using local models (Ollama)
 

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0}/django_explain_errors.egg-info/SOURCES.txt

@@ -24,12 +24,14 @@ explain_errors/rag/store.py
 tests/test_build_error_index.py
 tests/test_client.py
 tests/test_debug_page.py
+tests/test_dedup.py
 tests/test_eval_fixtures.py
 tests/test_eval_judge.py
 tests/test_eval_run.py
 tests/test_language.py
 tests/test_middleware.py
 tests/test_print_stdout.py
+tests/test_process_exception_split.py
 tests/test_rag.py
 tests/test_sanitize.py
 tests/test_signals.py

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0}/explain_errors/middleware.py

@@ -1,5 +1,7 @@
 import asyncio
 import logging
+import threading
+from collections import OrderedDict
 
 from django.conf import settings
 from django.http import JsonResponse
@@ -9,13 +11,16 @@ from .client import get_openai_client
 from .debug_page import ExplainErrorsExceptionReporter
 from .sanitize import sanitize_traceback
 from .throttle import SlidingWindowThrottle
-from .tracebacks import format_traceback
+from .tracebacks import exception_dedup_key, format_traceback
 from .rag.retriever import format_chunks_for_prompt, retrieve_chunks
 
 DEFAULT_EXCEPTION_REPORTER_PATH = "django.views.debug.ExceptionReporter"
 
 logger = logging.getLogger(__name__)
 
+# Max distinct errors whose explanations are kept for replay (LRU, no TTL).
+DEDUP_CACHE_SIZE = 128
+
 EXPLANATION_WORD_BUDGET = 200
 # Generous ceiling, not a target. Billing follows tokens generated, so unused
 # headroom is free. The prompt controls length; this only stops runaway
@@ -68,8 +73,12 @@ class ExplainErrorsMiddleware:
         self._is_async = asyncio.iscoroutinefunction(get_response)
         self.openai_client = None
         self.throttle = None
+        self.dedup_enabled = False
+        self._explanation_cache = OrderedDict()
+        self._explanation_cache_lock = threading.Lock()
 
         if settings.DEBUG:
+            self.dedup_enabled = getattr(settings, "EXPLAIN_ERRORS_DEDUP", True)
             max_calls = getattr(settings, "EXPLAIN_ERRORS_MAX_CALLS", 5)
             window_seconds = getattr(settings, "EXPLAIN_ERRORS_WINDOW_SECONDS", 60)
             self.throttle = SlidingWindowThrottle(max_calls, window_seconds)
@@ -129,6 +138,10 @@ class ExplainErrorsMiddleware:
         try:
             response = await self.get_response(request)
         except Exception as exception:
+            # Skip the thread-pool round-trip entirely when inert in production.
+            # process_exception keeps its own guard for the sync path.
+            if not settings.DEBUG:
+                raise
             # process_exception performs blocking model API I/O, so run it in
             # a thread to keep the event loop free.
             response = await sync_to_async(self.process_exception)(request, exception)
@@ -142,70 +155,22 @@ class ExplainErrorsMiddleware:
             return None
 
         explanation = None
-        if self.throttle.allow():
-            # Get the exception traceback, keeping application frames over
-            # library internals to cap token usage and stay within the
-            # model's context window.
-            max_tb_chars = getattr(settings, "OPENAI_MAX_TRACEBACK_CHARS", 3000)
-            tb = format_traceback(exception, max_tb_chars)
-            # Sanitize the exact payload that ships, after truncation so we
-            # don't waste work redacting frames that get discarded.
-            tb = sanitize_traceback(tb)
-
-            # Construct the prompt
-            prompt = f"Explain the following Django error in simple terms:\n\n{tb}"
-
-            # RAG: ground the explanation in the user's own project source.
-            # Opt-in and must never break the traceback-only path, so any
-            # failure here is logged and swallowed.
-            if getattr(settings, "EXPLAIN_ERRORS_RAG_ENABLED", False):
-                try:
-                    chunks = retrieve_chunks(exception)
-                    max_prompt_chars = getattr(
-                        settings, "EXPLAIN_ERRORS_RAG_MAX_PROMPT_CHARS", 6000
-                    )
-                    remaining_chars = max(max_prompt_chars - len(tb), 0)
-                    rag_section = format_chunks_for_prompt(chunks, remaining_chars)
-                    if rag_section:
-                        prompt += f"\n\n{rag_section}"
-                except Exception as exc:
-                    logger.warning(
-                        "explain_errors: RAG retrieval failed, falling back to "
-                        "traceback-only prompt: %s",
-                        exc,
-                    )
-
-            try:
-                # Call model API
-                response = self.openai_client.chat.completions.create(
-                    model=self.model,
-                    messages=[
-                        {"role": "system", "content": self.system_prompt},
-                        {"role": "user", "content": prompt},
-                    ],
-                    max_tokens=self.max_tokens,
-                )
-                explanation = response.choices[0].message.content
-                usage = getattr(response, "usage", None)
-                logger.debug(
-                    "explain_errors: token usage prompt_tokens=%s completion_tokens=%s",
-                    getattr(usage, "prompt_tokens", None),
-                    getattr(usage, "completion_tokens", None),
-                )
-                if response.choices[0].finish_reason == "length":
-                    logger.warning(
-                        "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=%s",
-                        self.max_tokens,
-                    )
-
-                if getattr(settings, "EXPLAIN_ERRORS_PRINT_STDOUT", True):
-                    print(f"Error explanation ({self.model}):\n", explanation)
-            except Exception as e:
-                # If the model API call fails, surface the failure but still
-                # return a 500 so the request lifecycle completes cleanly.
-                print("Failed to get an explanation from the model API:", e)
+        key = self._dedup_key(exception)
+        cached = self._cache_get(key) if key is not None else None
+        if cached is not None:
+            # Repeat of an error already explained: no throttle slot, no
+            # model call. Still shown on the debug page.
+            explanation = cached
+            if getattr(settings, "EXPLAIN_ERRORS_PRINT_STDOUT", True):
+                print("Error explanation: same error as an earlier one, replaying it.")
+            self._inject_debug_page(request, explanation)
+        elif self.throttle.allow():
+            prompt = self._build_prompt(exception)
+            explanation = self._generate_explanation(prompt)
 
             if explanation is not None:
+                if key is not None:
+                    self._cache_put(key, explanation)
                 self._inject_debug_page(request, explanation)
 
         if getattr(settings, "EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE", True):
@@ -215,6 +180,104 @@ class ExplainErrorsMiddleware:
             {"error": "An error occurred.", "message": explanation}, status=500
         )
 
+    def _dedup_key(self, exception):
+        """Key for the replay cache, or None (a miss). Fails open."""
+        if not self.dedup_enabled:
+            return None
+        try:
+            return exception_dedup_key(exception)
+        except Exception:
+            logger.debug("explain_errors: dedup key computation failed", exc_info=True)
+            return None
+
+    def _cache_get(self, key):
+        with self._explanation_cache_lock:
+            explanation = self._explanation_cache.get(key)
+            if explanation is not None:
+                self._explanation_cache.move_to_end(key)
+            return explanation
+
+    def _cache_put(self, key, explanation):
+        with self._explanation_cache_lock:
+            self._explanation_cache[key] = explanation
+            self._explanation_cache.move_to_end(key)
+            while len(self._explanation_cache) > DEDUP_CACHE_SIZE:
+                self._explanation_cache.popitem(last=False)
+
+    def _build_prompt(self, exception):
+        """Build the user prompt: sanitized traceback, plus RAG context if enabled."""
+        # Get the exception traceback, keeping application frames over
+        # library internals to cap token usage and stay within the
+        # model's context window.
+        max_tb_chars = getattr(settings, "OPENAI_MAX_TRACEBACK_CHARS", 3000)
+        tb = format_traceback(exception, max_tb_chars)
+        # Sanitize the exact payload that ships, after truncation so we
+        # don't waste work redacting frames that get discarded.
+        tb = sanitize_traceback(tb)
+
+        # Construct the prompt
+        prompt = f"Explain the following Django error in simple terms:\n\n{tb}"
+
+        # RAG: ground the explanation in the user's own project source.
+        # Opt-in and must never break the traceback-only path, so any
+        # failure here is logged and swallowed.
+        if getattr(settings, "EXPLAIN_ERRORS_RAG_ENABLED", False):
+            try:
+                chunks = retrieve_chunks(exception)
+                max_prompt_chars = getattr(
+                    settings, "EXPLAIN_ERRORS_RAG_MAX_PROMPT_CHARS", 6000
+                )
+                remaining_chars = max(max_prompt_chars - len(tb), 0)
+                rag_section = format_chunks_for_prompt(chunks, remaining_chars)
+                if rag_section:
+                    prompt += f"\n\n{rag_section}"
+            except Exception as exc:
+                logger.warning(
+                    "explain_errors: RAG retrieval failed, falling back to "
+                    "traceback-only prompt: %s",
+                    exc,
+                )
+
+        return prompt
+
+    def _generate_explanation(self, prompt):
+        """Call the model and return the explanation text, or None on failure.
+
+        Never raises: a failed or malformed response is reported on stdout and
+        yields None (or the text already extracted, if a later step failed).
+        """
+        explanation = None
+        try:
+            # Call model API
+            response = self.openai_client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": self.system_prompt},
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=self.max_tokens,
+            )
+            explanation = response.choices[0].message.content
+            usage = getattr(response, "usage", None)
+            logger.debug(
+                "explain_errors: token usage prompt_tokens=%s completion_tokens=%s",
+                getattr(usage, "prompt_tokens", None),
+                getattr(usage, "completion_tokens", None),
+            )
+            if response.choices[0].finish_reason == "length":
+                logger.warning(
+                    "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=%s",
+                    self.max_tokens,
+                )
+
+            if getattr(settings, "EXPLAIN_ERRORS_PRINT_STDOUT", True):
+                print(f"Error explanation ({self.model}):\n", explanation)
+        except Exception as e:
+            # If the model API call fails, surface the failure but still
+            # return a 500 so the request lifecycle completes cleanly.
+            print("Failed to get an explanation from the model API:", e)
+        return explanation
+
     def _inject_debug_page(self, request, explanation):
         """Wire the explanation into the debug page, if all conditions hold.
 

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0}/explain_errors/tracebacks.py

@@ -5,6 +5,7 @@ a character budget, instead of slicing the last N characters of the raw
 traceback.
 """
 import functools
+import hashlib
 import os
 import sysconfig
 import traceback
@@ -103,3 +104,37 @@ def format_traceback(exc: BaseException, max_chars: int) -> str:
             break
 
     return best
+
+
+def exception_dedup_key(exc: BaseException):
+    """Return a stable hash identifying "the same error" for replay purposes,
+    or None when the exception carries no traceback to key on.
+
+    The key covers the exception type's qualified name, the exception
+    message, and the innermost project frame's filename, line number and
+    stripped source text. The message is included, so "id 41 not found" and
+    "id 42 not found" at one site are different errors. With no project frames the
+    innermost frame is used. traceback.extract_tb refreshes linecache, so
+    editing the offending line yields a new key. Built from the raw exception,
+    not the sanitized traceback.
+    """
+    tb = exc.__traceback__
+    if tb is None:
+        return None
+    frames = traceback.extract_tb(tb)
+    if not frames:
+        return None
+    frame = frames[-1]
+    for candidate in reversed(frames):
+        if not _is_library_frame(candidate.filename):
+            frame = candidate
+            break
+    exc_type = type(exc)
+    parts = (
+        f"{exc_type.__module__}.{exc_type.__qualname__}",
+        str(exc),
+        frame.filename,
+        str(frame.lineno),
+        (frame.line or "").strip(),
+    )
+    return hashlib.sha256("\0".join(parts).encode("utf-8", "replace")).hexdigest()

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0}/setup.py

@@ -10,7 +10,7 @@ with open('README.md', encoding='utf-8') as f:
 
 setup(
     name='django-explain-errors',
-    version='0.9.3',
+    version='0.10.0',
     packages=find_packages(exclude=['tests', 'tests.*', 'evals', 'evals.*']),
     description='Django middleware that explains unhandled exceptions in DEBUG using an LLM, optionally grounded in your own project source via a local vector index. Works with OpenAI, Claude, or any OpenAI-compatible endpoint including local models.',
     long_description_content_type='text/markdown',

django_explain_errors-0.10.0/tests/test_dedup.py

@@ -0,0 +1,271 @@
+import os
+import tempfile
+from io import StringIO
+from unittest.mock import MagicMock, patch
+
+from django.test import RequestFactory, SimpleTestCase, override_settings
+
+from explain_errors.middleware import ExplainErrorsMiddleware
+from explain_errors.tracebacks import exception_dedup_key
+
+
+def _raise_value(message="boom"):
+    raise ValueError(message)
+
+
+def _raise_value_elsewhere(message="boom"):
+    raise ValueError(message)
+
+
+def _raise_key(message="boom"):
+    raise KeyError(message)
+
+
+def _raise_two_lines(message="boom"):
+    x = 1
+    raise ValueError(message + str(x))
+
+
+def _caught(fn, *args):
+    try:
+        fn(*args)
+    except Exception as exc:
+        return exc
+
+
+def _response(content="Cached explanation."):
+    choice = MagicMock(finish_reason="stop")
+    choice.message.content = content
+    return MagicMock(choices=[choice])
+
+
+def _setup(test, **kwargs):
+    """Build a middleware with a mocked OpenAI client; return (mw, create)."""
+    with patch("openai.OpenAI") as mock_cls:
+        client = MagicMock()
+        client.chat.completions.create.return_value = _response()
+        mock_cls.return_value = client
+        mw = ExplainErrorsMiddleware(lambda r: None)
+    return mw, client.chat.completions.create
+
+
+@override_settings(
+    DEBUG=True,
+    OPENAI_API_KEY="test-key",
+    EXPLAIN_ERRORS_PRINT_STDOUT=False,
+)
+class DedupTest(SimpleTestCase):
+    def setUp(self):
+        self.factory = RequestFactory()
+        self.mw, self.create = _setup(self)
+
+    def _handle(self, exc):
+        request = self.factory.get("/")
+        result = self.mw.process_exception(request, exc)
+        return request, result
+
+    def test_repeat_skips_model_and_throttle_and_injects(self):
+        _, _ = self._handle(_caught(_raise_value))
+        self.assertEqual(self.create.call_count, 1)
+
+        with patch.object(self.mw.throttle, "allow") as allow:
+            request, result = self._handle(_caught(_raise_value))
+        allow.assert_not_called()
+        self.assertEqual(self.create.call_count, 1)
+        self.assertIsNone(result)
+        self.assertEqual(request._explain_errors_explanation, "Cached explanation.")
+        self.assertIsNotNone(request.exception_reporter_class)
+
+    def test_repeat_does_not_consume_throttle(self):
+        for _ in range(10):
+            self._handle(_caught(_raise_value))
+        self.assertEqual(len(self.mw.throttle._calls), 1)
+
+    def test_different_exception_type_is_miss(self):
+        self._handle(_caught(_raise_value))
+        self._handle(_caught(_raise_key))
+        self.assertEqual(self.create.call_count, 2)
+
+    def test_different_frame_is_miss(self):
+        self._handle(_caught(_raise_value))
+        self._handle(_caught(_raise_value_elsewhere))
+        self.assertEqual(self.create.call_count, 2)
+
+    def test_different_line_text_is_miss(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "dedup_edit_target.py")
+
+            def run(source):
+                with open(path, "w") as f:
+                    f.write(source)
+                namespace = {}
+                exec(compile(source, path, "exec"), namespace)
+                return _caught(namespace["go"])
+
+            first = run("def go():\n    raise ValueError('a')\n")
+            first_key = exception_dedup_key(first)
+            self._handle(first)
+            second = run("def go():\n    raise ValueError('a')  # edited\n")
+            second_key = exception_dedup_key(second)
+            self._handle(second)
+        self.assertNotEqual(first_key, second_key)
+        self.assertEqual(self.create.call_count, 2)
+
+    def test_different_line_number_is_miss(self):
+        self.assertNotEqual(
+            exception_dedup_key(_caught(_raise_value)),
+            exception_dedup_key(_caught(_raise_two_lines)),
+        )
+
+    def test_different_message_same_line_is_miss(self):
+        self._handle(_caught(_raise_value, "first"))
+        self._handle(_caught(_raise_value, "second"))
+        self.assertEqual(self.create.call_count, 2)
+
+    def test_same_message_same_line_is_hit(self):
+        self._handle(_caught(_raise_value, "same"))
+        self._handle(_caught(_raise_value, "same"))
+        self.assertEqual(self.create.call_count, 1)
+
+    def test_failed_generation_is_not_cached(self):
+        self.create.side_effect = RuntimeError("api down")
+        with patch("builtins.print"):
+            self._handle(_caught(_raise_value))
+        self.assertEqual(len(self.mw._explanation_cache), 0)
+
+        self.create.side_effect = None
+        self.create.return_value = _response("Recovered.")
+        request, _ = self._handle(_caught(_raise_value))
+        self.assertEqual(self.create.call_count, 2)
+        self.assertEqual(request._explain_errors_explanation, "Recovered.")
+
+    def test_eviction_at_capacity(self):
+        with patch("explain_errors.middleware.DEDUP_CACHE_SIZE", 2):
+            self._handle(_caught(_raise_value))  # A
+            self._handle(_caught(_raise_key))  # B
+            self._handle(_caught(_raise_value))  # A hit, A now most recent
+            self.assertEqual(self.create.call_count, 2)
+            self._handle(_caught(_raise_value_elsewhere))  # C evicts B
+            self.assertEqual(self.create.call_count, 3)
+            self.assertEqual(len(self.mw._explanation_cache), 2)
+            self._handle(_caught(_raise_value))  # A still cached
+            self.assertEqual(self.create.call_count, 3)
+            self._handle(_caught(_raise_key))  # B was evicted
+            self.assertEqual(self.create.call_count, 4)
+
+    def test_key_failure_falls_through_to_miss(self):
+        with patch(
+            "explain_errors.middleware.exception_dedup_key",
+            side_effect=RuntimeError("bad key"),
+        ):
+            _, result = self._handle(_caught(_raise_value))
+            self._handle(_caught(_raise_value))
+        self.assertIsNone(result)
+        self.assertEqual(self.create.call_count, 2)
+        self.assertEqual(len(self.mw._explanation_cache), 0)
+
+    def test_exception_without_traceback_is_miss(self):
+        self._handle(ValueError("never raised"))
+        self._handle(ValueError("never raised"))
+        self.assertEqual(self.create.call_count, 2)
+
+    def test_cached_error_replays_after_throttle_exhausted(self):
+        self._handle(_caught(_raise_value))
+        self.mw.throttle.max_calls = 1  # window is now full
+        self.assertFalse(self.mw.throttle.allow())
+
+        self._handle(_caught(_raise_key))  # new error: denied by throttle
+        self.assertEqual(self.create.call_count, 1)
+
+        request, _ = self._handle(_caught(_raise_value))  # cached: replays
+        self.assertEqual(self.create.call_count, 1)
+        self.assertEqual(request._explain_errors_explanation, "Cached explanation.")
+
+    def test_json_500_path_returns_cached_explanation(self):
+        with override_settings(EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE=False):
+            self._handle(_caught(_raise_value))
+            _, response = self._handle(_caught(_raise_value))
+        self.assertEqual(response.status_code, 500)
+        self.assertIn(b"Cached explanation.", response.content)
+        self.assertEqual(self.create.call_count, 1)
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class DedupStdoutTest(SimpleTestCase):
+    def test_hit_prints_one_line_not_full_reprint(self):
+        mw, create = _setup(self)
+        request = RequestFactory().get("/")
+        with patch("sys.stdout", new_callable=StringIO) as out:
+            mw.process_exception(request, _caught(_raise_value))
+            first = out.getvalue()
+            out.truncate(0)
+            out.seek(0)
+            mw.process_exception(request, _caught(_raise_value))
+            second = out.getvalue()
+        self.assertIn("Cached explanation.", first)
+        self.assertNotIn("Cached explanation.", second)
+        self.assertEqual(len(second.strip().splitlines()), 1)
+
+    @override_settings(EXPLAIN_ERRORS_PRINT_STDOUT=False)
+    def test_hit_prints_nothing_when_stdout_disabled(self):
+        mw, create = _setup(self)
+        request = RequestFactory().get("/")
+        mw.process_exception(request, _caught(_raise_value))
+        with patch("sys.stdout", new_callable=StringIO) as out:
+            mw.process_exception(request, _caught(_raise_value))
+        self.assertEqual(out.getvalue(), "")
+
+
+@override_settings(
+    DEBUG=True,
+    OPENAI_API_KEY="test-key",
+    EXPLAIN_ERRORS_PRINT_STDOUT=False,
+    EXPLAIN_ERRORS_DEDUP=False,
+)
+class DedupDisabledTest(SimpleTestCase):
+    def test_disabled_always_calls_model(self):
+        mw, create = _setup(self)
+        request = RequestFactory().get("/")
+        with patch("explain_errors.middleware.exception_dedup_key") as key:
+            for _ in range(3):
+                mw.process_exception(request, _caught(_raise_value))
+        key.assert_not_called()
+        self.assertEqual(create.call_count, 3)
+        self.assertEqual(len(mw._explanation_cache), 0)
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class DedupDebugOffTest(SimpleTestCase):
+    def test_debug_false_computes_nothing(self):
+        mw, create = _setup(self)
+        with override_settings(DEBUG=False), patch(
+            "explain_errors.middleware.exception_dedup_key"
+        ) as key:
+            result = mw.process_exception(RequestFactory().get("/"), _caught(_raise_value))
+        self.assertIsNone(result)
+        key.assert_not_called()
+        create.assert_not_called()
+        self.assertEqual(len(mw._explanation_cache), 0)
+
+
+@override_settings(
+    DEBUG=True,
+    OPENAI_API_KEY="test-key",
+    EXPLAIN_ERRORS_PRINT_STDOUT=False,
+)
+class DedupAsyncTest(SimpleTestCase):
+    async def test_async_path_replays(self):
+        async def failing(request):
+            _raise_value()
+
+        with patch("openai.OpenAI") as mock_cls:
+            client = MagicMock()
+            client.chat.completions.create.return_value = _response()
+            mock_cls.return_value = client
+            mw = ExplainErrorsMiddleware(failing)
+
+        for _ in range(3):
+            with self.assertRaises(ValueError):
+                await mw(RequestFactory().get("/"))
+        self.assertEqual(client.chat.completions.create.call_count, 1)
+        self.assertEqual(len(mw.throttle._calls), 1)

{django_explain_errors-0.9.3 → django_explain_errors-0.10.0}/tests/test_middleware.py

@@ -192,7 +192,11 @@ class ExplainErrorsMiddlewareAsyncTest(SimpleTestCase):
         with self.assertRaises(ValueError):
             await mw(self.factory.get("/"))
 
-    @override_settings(EXPLAIN_ERRORS_MAX_CALLS=1, EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE=False)
+    @override_settings(
+        EXPLAIN_ERRORS_MAX_CALLS=1,
+        EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE=False,
+        EXPLAIN_ERRORS_DEDUP=False,
+    )
     async def test_async_path_respects_throttle(self):
         async def boom(r):
             raise ValueError("async boom")
@@ -216,6 +220,16 @@ class ExplainErrorsMiddlewareDebugOffTest(SimpleTestCase):
         mw = ExplainErrorsMiddleware(lambda r: None)
         self.assertIsNone(mw.process_exception(factory.get("/"), Exception("x")))
 
+    async def test_async_debug_false_does_not_dispatch_to_thread(self):
+        async def boom(r):
+            raise ValueError("async boom")
+
+        mw = ExplainErrorsMiddleware(boom)
+        with patch("explain_errors.middleware.sync_to_async") as mock_sync_to_async:
+            with self.assertRaises(ValueError):
+                await mw(AsyncRequestFactory().get("/"))
+        mock_sync_to_async.assert_not_called()
+
     def test_debug_false_handler_reraises(self):
         factory = RequestFactory()
 

django_explain_errors-0.10.0/tests/test_process_exception_split.py

@@ -0,0 +1,156 @@
+from io import StringIO
+from unittest.mock import MagicMock, patch
+
+from django.test import SimpleTestCase, override_settings
+
+from explain_errors.middleware import ExplainErrorsMiddleware
+
+
+def _exception():
+    try:
+        raise ValueError("split boom")
+    except ValueError as exc:
+        return exc
+
+
+def _middleware():
+    with patch("openai.OpenAI"):
+        return ExplainErrorsMiddleware(lambda r: None)
+
+
+def _response(content="Mocked explanation.", finish_reason="stop"):
+    choice = MagicMock(finish_reason=finish_reason)
+    choice.message.content = content
+    return MagicMock(choices=[choice])
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class BuildPromptTest(SimpleTestCase):
+
+    @override_settings(EXPLAIN_ERRORS_RAG_ENABLED=False)
+    def test_rag_off_is_traceback_only_and_skips_retrieval(self):
+        mw = _middleware()
+        with patch("explain_errors.middleware.retrieve_chunks") as retrieve:
+            prompt = mw._build_prompt(_exception())
+        retrieve.assert_not_called()
+        self.assertTrue(
+            prompt.startswith("Explain the following Django error in simple terms:\n\n")
+        )
+        self.assertIn("split boom", prompt)
+
+    @override_settings(EXPLAIN_ERRORS_RAG_ENABLED=False)
+    def test_prompt_uses_module_level_sanitize_traceback(self):
+        mw = _middleware()
+        with patch(
+            "explain_errors.middleware.sanitize_traceback", return_value="SANITIZED"
+        ) as sanitize:
+            prompt = mw._build_prompt(_exception())
+        sanitize.assert_called_once()
+        self.assertTrue(prompt.endswith("\n\nSANITIZED"))
+
+    @override_settings(EXPLAIN_ERRORS_RAG_ENABLED=True)
+    def test_rag_on_appends_section(self):
+        mw = _middleware()
+        with patch(
+            "explain_errors.middleware.retrieve_chunks", return_value=["chunk"]
+        ), patch(
+            "explain_errors.middleware.format_chunks_for_prompt",
+            return_value="RAG SECTION",
+        ):
+            prompt = mw._build_prompt(_exception())
+        self.assertIn("split boom", prompt)
+        self.assertTrue(prompt.endswith("\n\nRAG SECTION"))
+
+    @override_settings(EXPLAIN_ERRORS_RAG_ENABLED=True)
+    def test_rag_empty_section_leaves_prompt_unchanged(self):
+        mw = _middleware()
+        exc = _exception()
+        with patch("explain_errors.middleware.retrieve_chunks", return_value=[]), patch(
+            "explain_errors.middleware.format_chunks_for_prompt", return_value=""
+        ):
+            with_rag = mw._build_prompt(exc)
+        with override_settings(EXPLAIN_ERRORS_RAG_ENABLED=False):
+            without_rag = mw._build_prompt(exc)
+        self.assertEqual(with_rag, without_rag)
+
+    @override_settings(EXPLAIN_ERRORS_RAG_ENABLED=True)
+    def test_rag_failure_degrades_to_traceback_only(self):
+        mw = _middleware()
+        exc = _exception()
+        with override_settings(EXPLAIN_ERRORS_RAG_ENABLED=False):
+            expected = mw._build_prompt(exc)
+        with patch(
+            "explain_errors.middleware.retrieve_chunks", side_effect=RuntimeError("no index")
+        ), patch("explain_errors.middleware.logger.warning") as warning:
+            prompt = mw._build_prompt(exc)
+        self.assertEqual(prompt, expected)
+        warning.assert_called_once()
+        self.assertIn("RAG retrieval failed", warning.call_args[0][0])
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class GenerateExplanationTest(SimpleTestCase):
+
+    def _generate(self, mw, prompt="p"):
+        with patch("sys.stdout", new_callable=StringIO) as out:
+            result = mw._generate_explanation(prompt)
+        return result, out.getvalue()
+
+    def test_success_returns_text_and_prints(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.return_value = _response("Fix it.")
+        result, out = self._generate(mw, "my prompt")
+        self.assertEqual(result, "Fix it.")
+        self.assertIn("Fix it.", out)
+        kwargs = mw.openai_client.chat.completions.create.call_args.kwargs
+        self.assertEqual(kwargs["messages"][1], {"role": "user", "content": "my prompt"})
+        self.assertEqual(kwargs["messages"][0]["content"], mw.system_prompt)
+
+    @override_settings(EXPLAIN_ERRORS_PRINT_STDOUT=False)
+    def test_stdout_suppressed_when_print_disabled(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.return_value = _response("Fix it.")
+        result, out = self._generate(mw)
+        self.assertEqual(result, "Fix it.")
+        self.assertEqual(out, "")
+
+    def test_api_error_returns_none_and_prints_failure(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.side_effect = RuntimeError("api down")
+        result, out = self._generate(mw)
+        self.assertIsNone(result)
+        self.assertIn("Failed to get an explanation from the model API:", out)
+        self.assertIn("api down", out)
+
+    @override_settings(EXPLAIN_ERRORS_PRINT_STDOUT=False)
+    def test_api_error_message_prints_even_with_stdout_disabled(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.side_effect = RuntimeError("api down")
+        result, out = self._generate(mw)
+        self.assertIsNone(result)
+        self.assertIn("api down", out)
+
+    def test_truncation_warns_and_still_returns_text(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.return_value = _response(
+            "Cut off", finish_reason="length"
+        )
+        with patch("explain_errors.middleware.logger.warning") as warning:
+            result, _ = self._generate(mw)
+        self.assertEqual(result, "Cut off")
+        warning.assert_called_once()
+        self.assertIn("truncated", warning.call_args[0][0])
+
+    def test_non_length_finish_reason_does_not_warn(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.return_value = _response("ok")
+        with patch("explain_errors.middleware.logger.warning") as warning:
+            self._generate(mw)
+        warning.assert_not_called()
+
+    def test_empty_choices_fails_open(self):
+        mw = _middleware()
+        mw.openai_client.chat.completions.create.return_value = MagicMock(choices=[])
+        result, out = self._generate(mw)
+        self.assertIsNone(result)
+        self.assertIn("Failed to get an explanation from the model API:", out)