New ConnectionAcquisitionTimeoutError instead of ClientError (#1169)

Raise a new `ConnectionAcquisitionTimeoutError` (subclass of `DriverError`)
instead of `ClientError` (subclass of `Neo4jError`) when the connection
acquisition timeout is exceeded.

This improves the differentiation between `DriverError` for client-side errors
and `Neo4jError` for server-side errors.

Signed-off-by: Rouven Bauer <[email protected]>
Co-authored-by: Andy Heap <[email protected]>

Author: robsdedude

CHANGELOG.md

@@ -30,7 +30,8 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
   - `Version`'s additional methods were undocumented and shouldn't have been used
 - Changed errors raised under certain circumstances
   - `ConfigurationError` if the passed `auth` parameters is not valid (instead of `AuthError`)
-    - This improves the differentiation between `DriverError` for client-side errors and `Neo4jError` for server-side errors.
+    - This improves the differentiation between `DriverError` for client-side errors and `Neo4jError` for server-side
+      errors.
   - `access_mode` configuration option
     - `ValueError` on invalid value (instead of `ClientError`)
     - Consistently check the value (also for non-routing drivers)
@@ -40,6 +41,10 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
   - `connection_acquisition_timeout` configuration option
     - `ValueError` on invalid values (instead of `ClientError`)
     - Consistently restrict the value to be strictly positive
+    - New `ConnectionAcquisitionTimeoutError` (subclass of `DriverError`) instead of `ClientError`
+      (subclass of `Neo4jError`) the timeout is exceeded.
+      - This improves the differentiation between `DriverError` for client-side errors and `Neo4jError` for server-side
+        errors.
   - `TypeError` instead of `ValueError` when passing a `Query` object to `Transaction.run`.
   - `TransactionError` (subclass of `DriverError`) instead of `ClientError` (subclass of `Neo4jError`) when calling
     `session.run()` while an explicit transaction is active on that session.

docs/source/api.rst

@@ -2119,6 +2119,10 @@ Client-side errors
 
     * :class:`neo4j.exceptions.CertificateConfigurationError`
 
+  * :class:`neo4j.exceptions.ConnectionPoolError`
+
+    * :class:`neo4j.exceptions.ConnectionAcquisitionTimeoutError`
+
 
 .. autoexception:: neo4j.exceptions.DriverError()
     :show-inheritance:

src/neo4j/_async/io/_pool.py

@@ -50,8 +50,8 @@
     READ_ACCESS,
 )
 from ...exceptions import (
-    ClientError,
     ConfigurationError,
+    ConnectionAcquisitionTimeoutError,
     DriverError,
     Neo4jError,
     ReadServiceUnavailable,
@@ -412,8 +412,7 @@ async def health_check(connection_, deadline_):
                     or not await self.cond.wait(timeout)
                 ):
                     log.debug("[#0000]  _: <POOL> acquisition timed out")
-                    # TODO: 6.0 - change this to be a DriverError (or subclass)
-                    raise ClientError(
+                    raise ConnectionAcquisitionTimeoutError(
                         "failed to obtain a connection from the pool within "
                         f"{deadline.original_timeout!r}s (timeout)"
                     )

src/neo4j/_sync/io/_pool.py

@@ -56,6 +56,8 @@
   + ConfigurationError
     + AuthConfigurationError
     + CertificateConfigurationError
+  + ConnectionPoolError
+    + ConnectionAcquisitionTimeoutError
 """
 
 from __future__ import annotations
@@ -77,6 +79,8 @@
     "CertificateConfigurationError",
     "ClientError",
     "ConfigurationError",
+    "ConnectionAcquisitionTimeoutError",
+    "ConnectionPoolError",
     "ConstraintError",
     "CypherSyntaxError",
     "CypherTypeError",
@@ -1190,3 +1194,18 @@ class AuthConfigurationError(ConfigurationError):
 # DriverError > ConfigurationError > CertificateConfigurationError
 class CertificateConfigurationError(ConfigurationError):
     """Raised when there is an error with the certificate configuration."""
+
+
+# DriverError > ConnectionPoolError
+class ConnectionPoolError(DriverError):
+    """Raised when the connection pool encounters an error."""
+
+
+# DriverError > ConnectionPoolError > ConnectionAcquisitionTimeoutError
+class ConnectionAcquisitionTimeoutError(ConnectionPoolError):
+    """
+    Raised when no connection became available in time.
+
+    The amount of time is determined by the connection acquisition timeout
+    configuration option.
+    """

src/neo4j/exceptions.py

@@ -27,7 +27,7 @@
 from neo4j._deadline import Deadline
 from neo4j.auth_management import AsyncAuthManagers
 from neo4j.exceptions import (
-    ClientError,
+    ConnectionAcquisitionTimeoutError,
     ServiceUnavailable,
 )
 
@@ -206,7 +206,7 @@ async def test_pool_max_conn_pool_size(async_fake_connection_generator):
         address = neo4j.Address(("127.0.0.1", 7687))
         await pool._acquire(address, None, Deadline(0), None)
         assert pool.in_use_connection_count(address) == 1
-        with pytest.raises(ClientError):
+        with pytest.raises(ConnectionAcquisitionTimeoutError):
             await pool._acquire(address, None, Deadline(0), None)
         assert pool.in_use_connection_count(address) == 1