Improve error reporting on routing discovery (#870)

Routing drivers (`neo4j[+s[sc]]://` scheme) retry fetching a routing table on
many different errors that are considered not retryable in the context of
transactions. This is to overall improve the driver's stability when connecting
to clusters.

However, this poses the risk of hiding user-input errors (e.g., selecting a
database name that is invalid or doesn't exist). Hence, the driver blacklists a
handful of selected error codes upon which the discovery process is terminated
prematurely, raising the raw error to the user.

We expand the list to include more errors:
 * `Neo.ClientError.Statement.TypeError`, e.g., when  trying to impersonate an
   integer.
 * `Neo.ClientError.Statement.ArgumentError`, e.g., when trying to impersonate
   without the required permissions.
 * `Neo.ClientError.Request.Invalid`, e.g., when trying to select an integer
   database.

Also adding tests for discovery retries and fast failure.

Author: robsdedude

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 '