Introduce GqlError.find_by_gql_status

Return the first GqlError in the cause chain with the given GQL status.

This method traverses this GQLErorrs's :attr:`__cause__` chain,
starting with this error itself, and returns the first error that has
the given GQL status. If no error matches, :data:`None` is returned.

Example:

```python
def invalid_syntax(err: GqlError) -> bool:
    return err.find_by_gql_status("42001") is not None
```

Author: robsdedude

docs/source/api.rst

@@ -1960,7 +1960,9 @@ GQL Errors
 ==========
 .. autoexception:: neo4j.exceptions.GqlError()
     :show-inheritance:
-    :members: gql_status, message, gql_status_description, gql_raw_classification, gql_classification, diagnostic_record, __cause__
+    :members:
+        gql_status, message, gql_status_description, gql_raw_classification, gql_classification, diagnostic_record,
+        find_by_gql_status, __cause__
 
 .. autoclass:: neo4j.exceptions.GqlErrorClassification()
     :show-inheritance:
@@ -2002,7 +2004,7 @@ Server-side errors
 
 .. autoexception:: neo4j.exceptions.Neo4jError()
     :show-inheritance:
-    :members: message, code, is_retriable, is_retryable
+    :members: message, code, is_retryable
 
 .. autoexception:: neo4j.exceptions.ClientError()
     :show-inheritance:

src/neo4j/exceptions.py

@@ -219,6 +219,14 @@ class GqlError(Exception):
     Instead, only subclasses are raised.
     Further, it is used as the :attr:`__cause__` of GqlError subclasses.
 
+    Sometimes it is helpful or necessary to traverse the cause chain of
+    GQLErrors to fully understand or appropriately handle the error. In such
+    cases, users can either traverse the :attr:`__cause__` attribute of the
+    error(s) or use the helper method :meth:`.find_by_gql_status`. Note that
+    :attr:`__cause__` is a standard attribute of all Python
+    :class:`Exception`s. Therefore, the cause chain may also contain other
+    types besides GqlError.
+
     .. versionadded: 5.26
 
     .. versionchanged:: 6.0 Stabilized from preview.
@@ -427,6 +435,36 @@ def _get_status_diagnostic_record(self) -> dict[str, _t.Any]:
         self._status_diagnostic_record = dict(_UNKNOWN_GQL_DIAGNOSTIC_RECORD)
         return self._status_diagnostic_record
 
+    def find_by_gql_status(self, status: str) -> GqlError | None:
+        """
+        Return the first GqlError in the cause chain with the given GQL status.
+
+        This method traverses this GQLErorrs's :attr:`__cause__` chain,
+        starting with this error itself, and returns the first error that has
+        the given GQL status. If no error matches, :data:`None` is returned.
+
+        Example::
+
+            def invalid_syntax(err: GqlError) -> bool:
+                return err.find_by_gql_status("42001") is not None
+
+        :param status: The GQL status to search for.
+
+        :returns: The first matching error or :data:`None`.
+
+        .. versionadded:: 6.0
+        """
+        if self.gql_status == status:
+            return self
+
+        cause = self.__cause__
+        while cause is not None:
+            if isinstance(cause, GqlError) and cause.gql_status == status:
+                return cause
+            cause = getattr(cause, "__cause__", None)
+
+        return None
+
     def __str__(self):
         return (
             f"{{gql_status: {self.gql_status}}} "

tests/unit/common/test_exceptions.py

@@ -868,3 +868,33 @@ def test_deprecated_setter(attr):
         setattr(error, attr, obj)
 
     assert getattr(error, attr) is not obj
+
+
+@pytest.mark.parametrize("insert_after", range(-1, 3))
+def test_find_by_gql_status(insert_after: int) -> None:
+    error_to_find = _make_test_gql_error("12345")
+
+    root = None
+    if insert_after == -1:
+        root = error_to_find = _make_test_gql_error("12345")
+    for i in range(3):
+        root = _make_test_gql_error(f"{i + 2}2345", cause=root)
+        if i == insert_after:
+            root = error_to_find = _make_test_gql_error("12345", cause=root)
+
+    if root is None:
+        raise RuntimeError("unreachable, loop is not empty")
+
+    assert root.find_by_gql_status("12345") is error_to_find
+
+
+def test_find_by_gql_status_no_match() -> None:
+    root = None
+    for i in range(3):
+        root = _make_test_gql_error(f"{i + 1}2345", cause=root)
+
+    if root is None:
+        raise RuntimeError("unreachable, loop is not empty")
+
+    for status in ("2345", "02345", "42345", "54321"):
+        assert root.find_by_gql_status(status) is None