Traceback serialization (#75)

Author: ksamuel

.gitignore

@@ -174,3 +174,6 @@ poetry.toml
 pyrightconfig.json
 
 # End of https://www.toptal.com/developers/gitignore/api/python
+
+# Editor config files
+.vscode

README.md

@@ -158,7 +158,15 @@ If a task raised an exception, its `.result` will be the exception raised:
 assert isinstance(result.result, ValueError)
 ```
 
-As part of the serialization process for exceptions, some information, such as the traceback information, is lost. If the exception could not be serialized, the `.result` is `None`.
+As part of the serialization process for exceptions, some information is lost. The traceback information is reduced to a string that you can print to help debugging:
+
+```python
+assert isinstance(result.traceback, str)
+```
+
+The stack frames, `globals()` and `locals()` are not available.
+
+If the exception could not be serialized, the `.result` is `None`.
 
 ### Backend introspecting
 

django_tasks/task.py

@@ -21,7 +21,7 @@
 from typing_extensions import ParamSpec, Self
 
 from .exceptions import ResultDoesNotExist
-from .utils import exception_from_dict, get_module_path
+from .utils import SerializedExceptionDict, exception_from_dict, get_module_path
 
 if TYPE_CHECKING:
     from .backends.base import BaseTaskBackend
@@ -226,21 +226,33 @@ class TaskResult(Generic[T]):
     backend: str
     """The name of the backend the task will run on"""
 
-    _result: Optional[Union[T, dict]] = field(init=False, default=None)
+    _result: Optional[Union[T, SerializedExceptionDict]] = field(
+        init=False, default=None
+    )
 
     @property
     def result(self) -> Optional[Union[T, BaseException]]:
         if self.status == ResultStatus.COMPLETE:
             return cast(T, self._result)
         elif self.status == ResultStatus.FAILED:
             return (
-                exception_from_dict(cast(dict, self._result))
+                exception_from_dict(cast(SerializedExceptionDict, self._result))
                 if self._result is not None
                 else None
             )
 
         raise ValueError("Task has not finished yet")
 
+    @property
+    def traceback(self) -> Optional[str]:
+        """
+        Return the string representation of the traceback of the task if it failed
+        """
+        if self.status == ResultStatus.FAILED and self._result is not None:
+            return cast(SerializedExceptionDict, self._result)["exc_traceback"]
+
+        return None
+
     def get_result(self) -> Optional[T]:
         """
         A convenience method to get the result, or None if it's not ready yet or has failed.

django_tasks/utils.py

@@ -3,11 +3,25 @@
 import time
 from collections import deque
 from functools import wraps
-from typing import Any, Callable, TypeVar
+from traceback import format_exception
+from typing import Any, Callable, List, TypedDict, TypeVar
 
 from django.utils.module_loading import import_string
 from typing_extensions import ParamSpec
 
+
+class SerializedExceptionDict(TypedDict):
+    """Type for the dictionary holding exception informations in task result
+
+    The task result either stores the result of the task, or the serialized exception
+    information required to reconstitute part of the exception for debugging.
+    """
+
+    exc_type: str
+    exc_args: List[Any]
+    exc_traceback: str
+
+
 T = TypeVar("T")
 P = ParamSpec("P")
 
@@ -71,14 +85,15 @@ def get_module_path(val: Any) -> str:
     return f"{val.__module__}.{val.__qualname__}"
 
 
-def exception_to_dict(exc: BaseException) -> dict:
+def exception_to_dict(exc: BaseException) -> SerializedExceptionDict:
     return {
         "exc_type": get_module_path(type(exc)),
         "exc_args": json_normalize(exc.args),
+        "exc_traceback": "".join(format_exception(type(exc), exc, exc.__traceback__)),
     }
 
 
-def exception_from_dict(exc_data: dict) -> BaseException:
+def exception_from_dict(exc_data: SerializedExceptionDict) -> BaseException:
     exc_class = import_string(exc_data["exc_type"])
 
     if not inspect.isclass(exc_class) or not issubclass(exc_class, BaseException):

tests/tests/test_database_backend.py

@@ -343,7 +343,10 @@ def test_failing_task(self) -> None:
         self.assertGreaterEqual(result.started_at, result.enqueued_at)  # type: ignore
         self.assertGreaterEqual(result.finished_at, result.started_at)  # type: ignore
         self.assertEqual(result.status, ResultStatus.FAILED)
+
         self.assertIsInstance(result.result, ValueError)
+        assert result.traceback  # So that mypy knows the next line is allowed
+        self.assertTrue(result.traceback.endswith("ValueError: This task failed\n"))
 
         self.assertEqual(DBTaskResult.objects.ready().count(), 0)
 
@@ -364,7 +367,9 @@ def test_complex_exception(self) -> None:
         self.assertGreaterEqual(result.started_at, result.enqueued_at)  # type: ignore
         self.assertGreaterEqual(result.finished_at, result.started_at)  # type: ignore
         self.assertEqual(result.status, ResultStatus.FAILED)
+
         self.assertIsNone(result.result)
+        self.assertIsNone(result.traceback)
 
         self.assertEqual(DBTaskResult.objects.ready().count(), 0)
 

tests/tests/test_immediate_backend.py

@@ -58,6 +58,7 @@ def test_catches_exception(self) -> None:
         self.assertGreaterEqual(result.started_at, result.enqueued_at)
         self.assertGreaterEqual(result.finished_at, result.started_at)
         self.assertIsInstance(result.result, ValueError)
+        self.assertTrue(result.traceback.endswith("ValueError: This task failed\n"))
         self.assertIsNone(result.get_result())
         self.assertEqual(result.task, test_tasks.failing_task)
         self.assertEqual(result.args, [])
@@ -72,7 +73,10 @@ def test_complex_exception(self) -> None:
         self.assertIsNotNone(result.finished_at)
         self.assertGreaterEqual(result.started_at, result.enqueued_at)
         self.assertGreaterEqual(result.finished_at, result.started_at)
+
         self.assertIsNone(result.result)
+        self.assertIsNone(result.traceback)
+
         self.assertIsNone(result.get_result())
         self.assertEqual(result.task, test_tasks.complex_exception)
         self.assertEqual(result.args, [])

tests/tests/test_utils.py

@@ -1,5 +1,8 @@
 import datetime
+import hashlib
+import optparse
 import subprocess
+from typing import List
 from unittest.mock import Mock
 
 from django.core.exceptions import ImproperlyConfigured
@@ -101,20 +104,75 @@ def test_serialize_exceptions(self) -> None:
             with self.subTest(exc):
                 data = utils.exception_to_dict(exc)
                 self.assertEqual(utils.json_normalize(data), data)
-                self.assertEqual(set(data.keys()), {"exc_type", "exc_args"})
-                reconstructed = utils.exception_from_dict(data)
-                self.assertIsInstance(reconstructed, type(exc))
-                self.assertEqual(reconstructed.args, exc.args)
+                self.assertEqual(
+                    set(data.keys()), {"exc_type", "exc_args", "exc_traceback"}
+                )
+                exception = utils.exception_from_dict(data)
+                self.assertIsInstance(exception, type(exc))
+                self.assertEqual(exception.args, exc.args)
+
+                # Check that the exception traceback contains a minimal traceback
+                msg = str(exc.args[0]) if exc.args else ""
+                traceback = data["exc_traceback"]
+                self.assertIn(exc.__class__.__name__, traceback)
+                self.assertIn(msg, traceback)
+
+    def test_serialize_full_traceback(self) -> None:
+        try:
+            # Using optparse to generate an error because:
+            # - it's pure python
+            # - it's easy to trip down
+            # - it's unlikely to change ever
+            optparse.OptionParser(option_list=[1])  # type: ignore
+        except Exception as e:
+            traceback = utils.exception_to_dict(e)["exc_traceback"]
+            # The test is willingly fuzzy to ward against changes in the
+            # traceback formatting
+            self.assertIn("traceback", traceback.lower())
+            self.assertIn("line", traceback.lower())
+            self.assertIn(optparse.__file__, traceback)
+            self.assertTrue(
+                traceback.endswith("TypeError: not an Option instance: 1\n")
+            )
+
+    def test_serialize_traceback_from_c_module(self) -> None:
+        try:
+            # Same as test_serialize_full_traceback, but uses hashlib
+            # because it's in C, not in Python
+            hashlib.md5(1)  # type: ignore
+        except Exception as e:
+            traceback = utils.exception_to_dict(e)["exc_traceback"]
+            self.assertIn("traceback", traceback.lower())
+            self.assertTrue(
+                traceback.endswith(
+                    "TypeError: object supporting the buffer API required\n"
+                )
+            )
+            self.assertIn("hashlib.md5(1)", traceback)
 
     def test_cannot_deserialize_non_exception(self) -> None:
-        for data in [
-            {"exc_type": "subprocess.check_output", "exc_args": ["exit", "1"]},
-            {"exc_type": "True", "exc_args": []},
-            {"exc_type": "math.pi", "exc_args": []},
-            {"exc_type": __name__, "exc_args": []},
-            {"exc_type": utils.get_module_path(type(self)), "exc_args": []},
-            {"exc_type": utils.get_module_path(Mock), "exc_args": []},
-        ]:
+        serialized_exceptions: List[utils.SerializedExceptionDict] = [
+            {
+                "exc_type": "subprocess.check_output",
+                "exc_args": ["exit", "1"],
+                "exc_traceback": "",
+            },
+            {"exc_type": "True", "exc_args": [], "exc_traceback": ""},
+            {"exc_type": "math.pi", "exc_args": [], "exc_traceback": ""},
+            {"exc_type": __name__, "exc_args": [], "exc_traceback": ""},
+            {
+                "exc_type": utils.get_module_path(type(self)),
+                "exc_args": [],
+                "exc_traceback": "",
+            },
+            {
+                "exc_type": utils.get_module_path(Mock),
+                "exc_args": [],
+                "exc_traceback": "",
+            },
+        ]
+
+        for data in serialized_exceptions:
             with self.subTest(data):
                 with self.assertRaises((TypeError, ImportError)):
                     utils.exception_from_dict(data)