GQL Compliant Errors

CHANGELOG.md

@@ -3,7 +3,9 @@
 See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
 
 ## NEXT RELEASE
-- No breaking or major changes.
+- Deprecated setting attributes on `Neo4jError` like `message` and `code`.
+- Deprecated undocumented method `Neo4jError.hydrate`.  
+  It's internal and should not be used by client code.
 
 
 ## Version 5.25

docs/source/api.rst

@@ -1989,6 +1989,17 @@ Errors
 ******
 
 
+GQL Errors
+==========
+.. autoexception:: neo4j.exceptions.GqlError()
+    :show-inheritance:
+    :members: gql_status, message, gql_status_description, gql_raw_classification, gql_classification, diagnostic_record, __cause__
+
+.. autoclass:: neo4j.exceptions.GqlErrorClassification()
+    :show-inheritance:
+    :members:
+
+
 Neo4j Errors
 ============
 

src/neo4j/_async/io/_bolt.py

@@ -217,6 +217,7 @@ def _to_auth_dict(cls, auth):
             try:
                 return vars(auth)
             except (KeyError, TypeError) as e:
+                # TODO: 6.0 - change this to be a DriverError (or subclass)
                 raise AuthError(
                     f"Cannot determine auth details from {auth!r}"
                 ) from e
@@ -306,6 +307,7 @@ def protocol_handlers(cls, protocol_version=None):
             AsyncBolt5x4,
             AsyncBolt5x5,
             AsyncBolt5x6,
+            AsyncBolt5x7,
         )
 
         handlers = {
@@ -322,6 +324,7 @@ def protocol_handlers(cls, protocol_version=None):
             AsyncBolt5x4.PROTOCOL_VERSION: AsyncBolt5x4,
             AsyncBolt5x5.PROTOCOL_VERSION: AsyncBolt5x5,
             AsyncBolt5x6.PROTOCOL_VERSION: AsyncBolt5x6,
+            AsyncBolt5x7.PROTOCOL_VERSION: AsyncBolt5x7,
         }
 
         if protocol_version is None:
@@ -458,7 +461,10 @@ async def open(
 
         # avoid new lines after imports for better readability and conciseness
         # fmt: off
-        if protocol_version == (5, 6):
+        if protocol_version == (5, 7):
+            from ._bolt5 import AsyncBolt5x7
+            bolt_cls = AsyncBolt5x7
+        elif protocol_version == (5, 6):
             from ._bolt5 import AsyncBolt5x6
             bolt_cls = AsyncBolt5x6
         elif protocol_version == (5, 5):
@@ -506,6 +512,7 @@ async def open(
             await AsyncBoltSocket.close_socket(s)
 
             supported_versions = cls.protocol_handlers().keys()
+            # TODO: 6.0 - raise public DriverError subclass instead
             raise BoltHandshakeError(
                 "The neo4j server does not support communication with this "
                 "driver. This driver has support for Bolt protocols "
@@ -909,6 +916,16 @@ def goodbye(self, dehydration_hooks=None, hydration_hooks=None):
     def new_hydration_scope(self):
         return self.hydration_handler.new_hydration_scope()
 
+    def _default_hydration_hooks(self, dehydration_hooks, hydration_hooks):
+        if dehydration_hooks is not None and hydration_hooks is not None:
+            return dehydration_hooks, hydration_hooks
+        hydration_scope = self.new_hydration_scope()
+        if dehydration_hooks is None:
+            dehydration_hooks = hydration_scope.dehydration_hooks
+        if hydration_hooks is None:
+            hydration_hooks = hydration_scope.hydration_hooks
+        return dehydration_hooks, hydration_hooks
+
     def _append(
         self, signature, fields=(), response=None, dehydration_hooks=None
     ):

src/neo4j/_async/io/_bolt3.py

@@ -215,6 +215,9 @@ async def hello(self, dehydration_hooks=None, hydration_hooks=None):
             or self.notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         headers = self.get_base_headers()
         headers.update(self.auth_dict)
         logged_headers = dict(headers)
@@ -275,6 +278,9 @@ async def route(
                 f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
                 f"{imp_user!r}."
             )
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
 
         metadata = {}
         records = []
@@ -337,6 +343,9 @@ def run(
             or notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         if not parameters:
             parameters = {}
         extra = {}
@@ -379,6 +388,9 @@ def discard(
         **handlers,
     ):
         # Just ignore n and qid, it is not supported in the Bolt 3 Protocol.
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: DISCARD_ALL", self.local_port)
         self._append(
             b"\x2f",
@@ -396,6 +408,9 @@ def pull(
         **handlers,
     ):
         # Just ignore n and qid, it is not supported in the Bolt 3 Protocol.
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: PULL_ALL", self.local_port)
         self._append(
             b"\x3f",
@@ -435,6 +450,9 @@ def begin(
             or notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         extra = {}
         if mode in {READ_ACCESS, "r"}:
             # It will default to mode "w" if nothing is specified
@@ -464,6 +482,9 @@ def begin(
         )
 
     def commit(self, dehydration_hooks=None, hydration_hooks=None, **handlers):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: COMMIT", self.local_port)
         self._append(
             b"\x12",
@@ -475,6 +496,9 @@ def commit(self, dehydration_hooks=None, hydration_hooks=None, **handlers):
     def rollback(
         self, dehydration_hooks=None, hydration_hooks=None, **handlers
     ):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: ROLLBACK", self.local_port)
         self._append(
             b"\x13",
@@ -490,6 +514,9 @@ async def reset(self, dehydration_hooks=None, hydration_hooks=None):
         Add a RESET message to the outgoing queue, send it and consume all
         remaining messages.
         """
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: RESET", self.local_port)
         response = ResetResponse(self, "reset", hydration_hooks)
         self._append(
@@ -499,6 +526,9 @@ async def reset(self, dehydration_hooks=None, hydration_hooks=None):
         await self.fetch_all()
 
     def goodbye(self, dehydration_hooks=None, hydration_hooks=None):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: GOODBYE", self.local_port)
         self._append(b"\x02", (), dehydration_hooks=dehydration_hooks)
 

src/neo4j/_async/io/_bolt4.py

@@ -131,6 +131,9 @@ async def hello(self, dehydration_hooks=None, hydration_hooks=None):
             or self.notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         headers = self.get_base_headers()
         headers.update(self.auth_dict)
         logged_headers = dict(headers)
@@ -184,6 +187,9 @@ async def route(
                 f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
                 f"{imp_user!r}."
             )
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         metadata = {}
         records = []
 
@@ -244,6 +250,9 @@ def run(
             or notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         if not parameters:
             parameters = {}
         extra = {}
@@ -292,6 +301,9 @@ def discard(
         hydration_hooks=None,
         **handlers,
     ):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         extra = {"n": n}
         if qid != -1:
             extra["qid"] = qid
@@ -311,6 +323,9 @@ def pull(
         hydration_hooks=None,
         **handlers,
     ):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         extra = {"n": n}
         if qid != -1:
             extra["qid"] = qid
@@ -347,6 +362,9 @@ def begin(
             or notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         extra = {}
         if mode in {READ_ACCESS, "r"}:
             # It will default to mode "w" if nothing is specified
@@ -379,6 +397,9 @@ def begin(
         )
 
     def commit(self, dehydration_hooks=None, hydration_hooks=None, **handlers):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: COMMIT", self.local_port)
         self._append(
             b"\x12",
@@ -390,6 +411,9 @@ def commit(self, dehydration_hooks=None, hydration_hooks=None, **handlers):
     def rollback(
         self, dehydration_hooks=None, hydration_hooks=None, **handlers
     ):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: ROLLBACK", self.local_port)
         self._append(
             b"\x13",
@@ -405,6 +429,9 @@ async def reset(self, dehydration_hooks=None, hydration_hooks=None):
         Add a RESET message to the outgoing queue, send it and consume all
         remaining messages.
         """
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: RESET", self.local_port)
         response = ResetResponse(self, "reset", hydration_hooks)
         self._append(
@@ -414,6 +441,9 @@ async def reset(self, dehydration_hooks=None, hydration_hooks=None):
         await self.fetch_all()
 
     def goodbye(self, dehydration_hooks=None, hydration_hooks=None):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         log.debug("[#%04X]  C: GOODBYE", self.local_port)
         self._append(b"\x02", (), dehydration_hooks=dehydration_hooks)
 
@@ -547,6 +577,9 @@ async def route(
                 f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
                 f"{imp_user!r}."
             )
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
 
         routing_context = self.routing_context or {}
         log.debug(
@@ -576,6 +609,9 @@ async def hello(self, dehydration_hooks=None, hydration_hooks=None):
             or self.notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
 
         def on_success(metadata):
             self.configuration_hints.update(metadata.pop("hints", {}))
@@ -635,6 +671,9 @@ async def route(
         dehydration_hooks=None,
         hydration_hooks=None,
     ):
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         routing_context = self.routing_context or {}
         db_context = {}
         if database is not None:
@@ -683,6 +722,9 @@ def run(
             or notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         if not parameters:
             parameters = {}
         extra = {}
@@ -744,6 +786,9 @@ def begin(
             or notifications_disabled_classifications is not None
         ):
             self.assert_notification_filtering_support()
+        dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
+            dehydration_hooks, hydration_hooks
+        )
         extra = {}
         if mode in {READ_ACCESS, "r"}:
             # It will default to mode "w" if nothing is specified