Improve error reporting on routing discovery

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 See also https://github.com/neo4j/neo4j-python-driver/wiki for more details.
 
+## Version 5.4
+- Undocumented helper methods `Neo4jError.is_fatal_during_discovery` and
+  `Neo4jError.invalidates_all_connections` have been deprecated and will be
+  removed without replacement in version 6.0.
+
+
 ## Version 5.3
 - Python 3.11 support added
 - Removed undocumented, unused `neo4j.data.map_type`

src/neo4j/__init__.py

@@ -150,7 +150,7 @@
 
 
 def __getattr__(name):
-    # TODO 6.0 - remove this
+    # TODO: 6.0 - remove this
     if name in (
         "log", "Config", "PoolConfig", "SessionConfig", "WorkspaceConfig"
     ):

src/neo4j/_async/driver.py

@@ -131,7 +131,7 @@ def driver(cls, uri, *, auth=None, **config) -> AsyncDriver:
 
             driver_type, security_type, parsed = parse_neo4j_uri(uri)
 
-            # TODO: 6.0 remove "trust" config option
+            # TODO: 6.0 - remove "trust" config option
             if "trust" in config.keys():
                 if config["trust"] not in (
                     TRUST_ALL_CERTIFICATES,
@@ -166,7 +166,7 @@ def driver(cls, uri, *, auth=None, **config) -> AsyncDriver:
                      or "ssl_context" in config.keys())):
                 from ..exceptions import ConfigurationError
 
-                # TODO: 6.0 remove "trust" from error message
+                # TODO: 6.0 - remove "trust" from error message
                 raise ConfigurationError(
                     'The config settings "encrypted", "trust", '
                     '"trusted_certificates", and "ssl_context" can only be '

src/neo4j/_async/io/_bolt3.py

@@ -377,7 +377,7 @@ async def _process_message(self, tag, fields):
                     self.pool.on_write_failure(address=self.unresolved_address)
                 raise
             except Neo4jError as e:
-                if self.pool and e.invalidates_all_connections():
+                if self.pool and e._invalidates_all_connections():
                     await self.pool.mark_all_stale()
                 raise
         else:

src/neo4j/_async/io/_bolt4.py

@@ -333,7 +333,7 @@ async def _process_message(self, tag, fields):
                     self.pool.on_write_failure(address=self.unresolved_address)
                 raise
             except Neo4jError as e:
-                if self.pool and e.invalidates_all_connections():
+                if self.pool and e._invalidates_all_connections():
                     await self.pool.mark_all_stale()
                 raise
         else:

src/neo4j/_async/io/_bolt5.py

@@ -324,7 +324,7 @@ async def _process_message(self, tag, fields):
                     self.pool.on_write_failure(address=self.unresolved_address)
                 raise
             except Neo4jError as e:
-                if self.pool and e.invalidates_all_connections():
+                if self.pool and e._invalidates_all_connections():
                     await self.pool.mark_all_stale()
                 raise
         else:

src/neo4j/_async/io/_pool.py

@@ -538,7 +538,7 @@ async def fetch_routing_table(
             # checks if the code is an error that is caused by the client. In
             # this case there is no sense in trying to fetch a RT from another
             # router. Hence, the driver should fail fast during discovery.
-            if e.is_fatal_during_discovery():
+            if e._is_fatal_during_discovery():
                 raise
         except (ServiceUnavailable, SessionExpired):
             pass

src/neo4j/_async/work/result.py

@@ -611,7 +611,7 @@ async def to_df(
 
         ::
 
-            res = await tx.run("UNWIND range(1, 10) AS n RETURN n, n+1 as m")
+            res = await tx.run("UNWIND range(1, 10) AS n RETURN n, n+1 AS m")
             df = await res.to_df()
 
         for instance will return a DataFrame with two columns: ``n`` and ``m``

src/neo4j/_async/work/session.py

@@ -591,7 +591,7 @@ async def get_two_tx(tx):
             READ_ACCESS, transaction_function, *args, **kwargs
         )
 
-    # TODO 6.0: Remove this method
+    # TODO: 6.0 - Remove this method
     @deprecated("read_transaction has been renamed to execute_read")
     async def read_transaction(
         self,
@@ -673,7 +673,7 @@ async def create_node_tx(tx, name):
             WRITE_ACCESS, transaction_function, *args, **kwargs
         )
 
-    # TODO 6.0: Remove this method
+    # TODO: 6.0 - Remove this method
     @deprecated("write_transaction has been renamed to execute_write")
     async def write_transaction(
         self,

src/neo4j/_sync/driver.py

@@ -128,7 +128,7 @@ def driver(cls, uri, *, auth=None, **config) -> Driver:
 
             driver_type, security_type, parsed = parse_neo4j_uri(uri)
 
-            # TODO: 6.0 remove "trust" config option
+            # TODO: 6.0 - remove "trust" config option
             if "trust" in config.keys():
                 if config["trust"] not in (
                     TRUST_ALL_CERTIFICATES,
@@ -163,7 +163,7 @@ def driver(cls, uri, *, auth=None, **config) -> Driver:
                      or "ssl_context" in config.keys())):
                 from ..exceptions import ConfigurationError
 
-                # TODO: 6.0 remove "trust" from error message
+                # TODO: 6.0 - remove "trust" from error message
                 raise ConfigurationError(
                     'The config settings "encrypted", "trust", '
                     '"trusted_certificates", and "ssl_context" can only be '

src/neo4j/_sync/io/_bolt3.py

@@ -377,7 +377,7 @@ def _process_message(self, tag, fields):
                     self.pool.on_write_failure(address=self.unresolved_address)
                 raise
             except Neo4jError as e:
-                if self.pool and e.invalidates_all_connections():
+                if self.pool and e._invalidates_all_connections():
                     self.pool.mark_all_stale()
                 raise
         else:

src/neo4j/_sync/io/_bolt4.py

@@ -333,7 +333,7 @@ def _process_message(self, tag, fields):
                     self.pool.on_write_failure(address=self.unresolved_address)
                 raise
             except Neo4jError as e:
-                if self.pool and e.invalidates_all_connections():
+                if self.pool and e._invalidates_all_connections():
                     self.pool.mark_all_stale()
                 raise
         else:

src/neo4j/_sync/io/_bolt5.py

@@ -324,7 +324,7 @@ def _process_message(self, tag, fields):
                     self.pool.on_write_failure(address=self.unresolved_address)
                 raise
             except Neo4jError as e:
-                if self.pool and e.invalidates_all_connections():
+                if self.pool and e._invalidates_all_connections():
                     self.pool.mark_all_stale()
                 raise
         else:

src/neo4j/_sync/io/_pool.py

@@ -538,7 +538,7 @@ def fetch_routing_table(
             # checks if the code is an error that is caused by the client. In
             # this case there is no sense in trying to fetch a RT from another
             # router. Hence, the driver should fail fast during discovery.
-            if e.is_fatal_during_discovery():
+            if e._is_fatal_during_discovery():
                 raise
         except (ServiceUnavailable, SessionExpired):
             pass

src/neo4j/_sync/work/result.py

@@ -611,7 +611,7 @@ def to_df(
 
         ::
 
-            res = tx.run("UNWIND range(1, 10) AS n RETURN n, n+1 as m")
+            res = tx.run("UNWIND range(1, 10) AS n RETURN n, n+1 AS m")
             df = res.to_df()
 
         for instance will return a DataFrame with two columns: ``n`` and ``m``

src/neo4j/_sync/work/session.py

@@ -591,7 +591,7 @@ def get_two_tx(tx):
             READ_ACCESS, transaction_function, *args, **kwargs
         )
 
-    # TODO 6.0: Remove this method
+    # TODO: 6.0 - Remove this method
     @deprecated("read_transaction has been renamed to execute_read")
     def read_transaction(
         self,
@@ -673,7 +673,7 @@ def create_node_tx(tx, name):
             WRITE_ACCESS, transaction_function, *args, **kwargs
         )
 
-    # TODO 6.0: Remove this method
+    # TODO: 6.0 - Remove this method
     @deprecated("write_transaction has been renamed to execute_write")
     def write_transaction(
         self,

src/neo4j/api.py

@@ -175,7 +175,7 @@ def custom_auth(
     return Auth(scheme, principal, credentials, realm, **parameters)
 
 
-# TODO 6.0 - remove this class
+# TODO: 6.0 - remove this class
 class Bookmark:
     """A Bookmark object contains an immutable list of bookmark string values.
 

src/neo4j/exceptions.py

@@ -199,7 +199,7 @@ def _extract_error_class(cls, classification, code):
         else:
             return cls
 
-    # TODO 6.0: Remove this alias
+    # TODO: 6.0 - Remove this alias
     @deprecated(
         "Neo4jError.is_retriable is deprecated and will be removed in a "
         "future version. Please use Neo4jError.is_retryable instead."
@@ -230,24 +230,41 @@ def is_retryable(self) -> bool:
         """
         return False
 
-    def invalidates_all_connections(self):
+    def _invalidates_all_connections(self) -> bool:
         return self.code == "Neo.ClientError.Security.AuthorizationExpired"
 
-    def is_fatal_during_discovery(self) -> bool:
+    # TODO: 6.0 - Remove this alias
+    invalidates_all_connections = deprecated(
+        "Neo4jError.invalidates_all_connections is deprecated and will be "
+        "removed in a future version. It is an internal method and not meant "
+        "for external use."
+    )(_invalidates_all_connections)
+
+    def _is_fatal_during_discovery(self) -> bool:
         # checks if the code is an error that is caused by the client. In this
         # case the driver should fail fast during discovery.
         if not isinstance(self.code, str):
             return False
         if self.code in ("Neo.ClientError.Database.DatabaseNotFound",
                          "Neo.ClientError.Transaction.InvalidBookmark",
-                         "Neo.ClientError.Transaction.InvalidBookmarkMixture"):
+                         "Neo.ClientError.Transaction.InvalidBookmarkMixture",
+                         "Neo.ClientError.Statement.TypeError",
+                         "Neo.ClientError.Statement.ArgumentError",
+                         "Neo.ClientError.Request.Invalid"):
             return True
         if (self.code.startswith("Neo.ClientError.Security.")
                 and self.code != "Neo.ClientError.Security."
                                  "AuthorizationExpired"):
             return True
         return False
 
+    # TODO: 6.0 - Remove this alias
+    is_fatal_during_discovery = deprecated(
+        "Neo4jError.is_fatal_during_discovery is deprecated and will be "
+        "removed in a future version. It is an internal method and not meant "
+        "for external use."
+    )(_is_fatal_during_discovery)
+
     def __str__(self):
         if self.code or self.message:
             return "{{code: {code}}} {{message: {message}}}".format(

src/neo4j/spatial/__init__.py

@@ -42,7 +42,7 @@
 )
 
 
-# TODO: 6.0 remove
+# TODO: 6.0 - remove
 @deprecated(
     "hydrate_point is considered an internal function and will be removed in "
     "a future version"
@@ -56,7 +56,7 @@ def hydrate_point(srid, *coordinates):
     return _hydration.hydrate_point(srid, *coordinates)
 
 
-# TODO: 6.0 remove
+# TODO: 6.0 - remove
 @deprecated(
     "hydrate_point is considered an internal function and will be removed in "
     "a future version"
@@ -72,7 +72,7 @@ def dehydrate_point(value):
     return _hydration.dehydrate_point(value)
 
 
-# TODO: 6.0 remove
+# TODO: 6.0 - remove
 @deprecated(
     "point_type is considered an internal function and will be removed in "
     "a future version"