Adopt cause in favor of original_error

Python has no native Error.cause: the cause is stored as a dedicated
``cause`` attribute and additionally exposed as ``__cause__`` when it is an
exception, while an exception cause is still surfaced as ``original_error``
for backward compatibility.

Replicates graphql/graphql-js@550e511,
           graphql/graphql-js@d2bad2a,
           graphql/graphql-js@4c9d754

Author: Cito

docs/conf.py

@@ -100,7 +100,7 @@
 # be nitpicky
 nitpicky = True
 # but not too nitpicky
-suppress_warnings = ["ref.class", "ref.obj", "ref.python"]
+suppress_warnings = ["ref.attr", "ref.class", "ref.obj", "ref.python"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

src/graphql/error/graphql_error.py

@@ -5,6 +5,8 @@
 from sys import exc_info
 from typing import TYPE_CHECKING, Any, TypeAlias, TypedDict
 
+from ..pyutils import Undefined
+
 if TYPE_CHECKING:
     from collections.abc import Collection
 
@@ -108,12 +110,26 @@ class GraphQLError(Exception):
     """
 
     original_error: Exception | None
-    """The original error thrown from a field resolver during execution"""
+    """Original error that caused this GraphQLError, if one exists
+
+    .. deprecated:: 3.3
+        Use :attr:`cause` instead to better align with the standard exception
+        :attr:`~BaseException.__cause__`.
+    """
+
+    cause: Any
+    """The cause of this error, if one exists
+
+    The value passed as the ``cause`` when creating this error. Adopts the
+    convention of the standard exception cause and is also exposed as the
+    :attr:`~BaseException.__cause__` when it is an exception.
+    """
 
     extensions: GraphQLErrorExtensions | None
     """Extension fields to add to the formatted error"""
 
     __slots__ = (
+        "cause",
         "extensions",
         "locations",
         "message",
@@ -135,15 +151,27 @@ def __init__(
         path: Collection[str | int] | None = None,
         original_error: Exception | None = None,
         extensions: GraphQLErrorExtensions | None = None,
+        cause: Any = Undefined,
     ) -> None:
         """Initialize a GraphQLError."""
         super().__init__(message)
         self.message = message
 
+        # The cause defaults to the (deprecated) original error when not given.
+        has_cause = cause is not Undefined
+        self.cause = cause if has_cause else original_error
+
         if path and not isinstance(path, list):
             path = list(path)
         self.path = path or None  # type: ignore
-        self.original_error = original_error
+
+        # An Error provided as the cause is also exposed as the original error
+        # for backward compatibility.
+        cause_value = cause if has_cause else None
+        underlying_error = original_error
+        if underlying_error is None and isinstance(cause_value, Exception):
+            underlying_error = cause_value
+        self.original_error = underlying_error
 
         # Compute list of blame nodes.
         if nodes and not isinstance(nodes, list):
@@ -170,16 +198,25 @@ def __init__(
             locations = [loc.source.get_location(loc.start) for loc in node_locations]
         self.locations = locations or None
 
+        # Adopt the cause as the standard exception cause when it is one, so
+        # that the cause chain is reported without duplicating the traceback.
+        if isinstance(cause_value, BaseException):
+            self.__cause__ = cause_value
+
+        # Preserve the traceback of an explicit original error. The traceback of
+        # a cause is not copied over, since Python already reports cause chains.
         if original_error:
             self.__traceback__ = original_error.__traceback__
-            if original_error.__cause__:
-                self.__cause__ = original_error.__cause__
-            elif original_error.__context__:
-                self.__context__ = original_error.__context__
-            if extensions is None:
-                original_extensions = getattr(original_error, "extensions", None)
-                if isinstance(original_extensions, dict):
-                    extensions = original_extensions
+            if not self.__cause__:
+                if original_error.__cause__:
+                    self.__cause__ = original_error.__cause__
+                elif original_error.__context__:
+                    self.__context__ = original_error.__context__
+
+        if extensions is None and underlying_error is not None:
+            original_extensions = getattr(underlying_error, "extensions", None)
+            if isinstance(original_extensions, dict):
+                extensions = original_extensions
         self.extensions = extensions or {}
         if not self.__traceback__:
             self.__traceback__ = exc_info()[2]
@@ -217,15 +254,15 @@ def __eq__(self, other: object) -> bool:
             and all(
                 getattr(self, slot) == getattr(other, slot)
                 for slot in self.__slots__
-                if slot != "original_error"
+                if slot not in ("cause", "original_error")
             )
         ) or (
             isinstance(other, dict)
             and "message" in other
             and all(
                 slot in self.__slots__ and getattr(self, slot) == other.get(slot)
                 for slot in other
-                if slot != "original_error"
+                if slot not in ("cause", "original_error")
             )
         )
 

tests/error/test_graphql_error.py

@@ -77,6 +77,7 @@ def formatted_dict_has_only_keys_prescribed_in_the_spec():
             ["a", "b", "c"],
             Exception("test"),
             {"foo": "bar"},
+            cause=Exception("test"),
         )
         assert set(e.formatted) == {"message", "path", "locations", "extensions"}
 
@@ -128,6 +129,67 @@ def creates_new_stack_if_original_error_has_no_stack():
         assert e.original_error is original
         assert str(e.original_error) == "original"
 
+    def does_not_add_a_cause_without_a_cause():
+        e = GraphQLError("msg")
+        assert e.cause is None
+
+    def does_not_copy_over_the_traceback_of_cause():
+        try:
+            raise RuntimeError("cause")
+        except RuntimeError as runtime_error:
+            cause = runtime_error
+        e = GraphQLError("msg", cause=cause)
+        assert e.cause is cause
+        assert e.__cause__ is cause
+        assert cause.__traceback__ is not None
+        assert e.__traceback__ is not cause.__traceback__
+
+    def uses_an_error_cause_as_the_original_error_for_compatibility():
+        class CustomError(Exception):
+            def __init__(self, message: str) -> None:
+                super().__init__(message)
+                self.extensions = {"original": "extensions"}
+
+        cause = CustomError("cause")
+        e = GraphQLError("msg", cause=cause)
+        assert e.message == "msg"
+        assert e.cause is cause
+        assert e.original_error is cause
+        assert e.__cause__ is cause
+        assert e.extensions == {"original": "extensions"}
+
+    def preserves_a_non_error_cause_without_setting_original_error():
+        e = GraphQLError("msg", cause="cause")
+        assert e.cause == "cause"
+        assert e.original_error is None
+        assert e.__cause__ is None
+
+    def prefers_cause_and_original_error_separately():
+        try:
+            raise RuntimeError("original")
+        except RuntimeError as runtime_error:
+            original_error = runtime_error
+        cause = ValueError("cause")
+        e = GraphQLError("msg", original_error=original_error, cause=cause)
+        assert e.cause is cause
+        assert e.original_error is original_error
+        assert e.__cause__ is cause
+        assert e.__traceback__ is original_error.__traceback__
+
+    def creates_new_stack_if_cause_has_no_stack():
+        try:
+            raise RuntimeError
+        except RuntimeError as runtime_error:
+            current_traceback = runtime_error.__traceback__
+            cause = RuntimeError("cause")
+            e = GraphQLError("msg", cause=cause)
+        assert cause.__traceback__ is None
+        assert current_traceback is not None
+        assert e.__traceback__ is current_traceback
+        assert e.message == "msg"
+        assert e.cause is cause
+        assert e.original_error is cause
+
     def converts_nodes_to_positions_and_locations():
         e = GraphQLError("msg", [field_node])
         assert e.nodes == [field_node]
@@ -188,6 +250,25 @@ def defaults_to_original_error_extension_only_if_arg_is_not_passed():
         assert own_empty_error.original_error is original_error
         assert own_empty_error.extensions == {}
 
+    def defaults_to_cause_extension_only_if_arg_is_not_passed():
+        original_extensions = {"original": "extensions"}
+        cause = GraphQLError("original", extensions=original_extensions)
+        inherited_error = GraphQLError("InheritedError", cause=cause)
+        assert inherited_error.message == "InheritedError"
+        assert inherited_error.cause is cause
+        assert inherited_error.extensions is original_extensions
+
+        own_extensions = {"own": "extensions"}
+        own_error = GraphQLError("OwnError", cause=cause, extensions=own_extensions)
+        assert own_error.message == "OwnError"
+        assert own_error.cause is cause
+        assert own_error.extensions is own_extensions
+
+        own_empty_error = GraphQLError("OwnEmptyError", cause=cause, extensions={})
+        assert own_empty_error.message == "OwnEmptyError"
+        assert own_empty_error.cause is cause
+        assert own_empty_error.extensions == {}
+
     def serializes_to_include_message():
         e = GraphQLError("msg")
         assert str(e) == "msg"