Revamp UnsupportedServerProduct exception (#1164)

* Revamp `UnsupportedServerProduct` exception
  * Make it a subclass of `ServiceUnavailable`
  * Raise it (instead of internal `neo4j._exceptions.BoltHandshakeError`) when
    no common Bolt version could be negotiated.
* Drop public Version for internal BoltProtocolVersion

Author: robsdedude

CHANGELOG.md

@@ -22,12 +22,21 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
 - Remove deprecated exports from `neo4j`:
   - `log`, `Config`, `PoolConfig`, `SessionConfig`, `WorkspaceConfig` (internal - no replacement)
   - `SummaryNotificationPosition` (use `SummaryInputPosition` instead)
+- `api.Version` has been removed as it's unused now.  
+  `ServerInfo.protocol_version` now is a `tuple[int, int]` insteadof a `api.Version`.
+  This should be drop-in replacement is most cases:
+  - `Version` was a sup-type of `tuple[int, int]`
+  - `ServerInfo.protocol_version` was already documented and typed as `tuple[int, int]`
+  - `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.
   - `access_mode` configuration option
     - `ValueError` on invalid value (instead of `ClientError`)
     - Consistently check the value (also for non-routing drivers)
+  - `neo4j.exceptions.UnsupportedServerProduct` if no common bolt protocol version could be negotiated with the server
+   (instead of internal `neo4j._exceptions.BoltHandshakeError`).  
+    `UnsupportedServerProduct` is now a subclass of `ServiceUnavailable` (instead of `Exception` directly).
 
 
 ## Version 5.28

docs/source/api.rst

@@ -2109,6 +2109,8 @@ Client-side errors
 
     * :class:`neo4j.exceptions.ReadServiceUnavailable`
 
+    * :class:`neo4j.exceptions.UnsupportedServerProduct`
+
     * :class:`neo4j.exceptions.IncompleteCommit`
 
   * :class:`neo4j.exceptions.ConfigurationError`
@@ -2164,6 +2166,9 @@ Client-side errors
 .. autoexception:: neo4j.exceptions.ReadServiceUnavailable()
     :show-inheritance:
 
+.. autoexception:: neo4j.exceptions.UnsupportedServerProduct()
+    :show-inheritance:
+
 .. autoexception:: neo4j.exceptions.IncompleteCommit()
     :show-inheritance:
 

src/neo4j/__init__.py

@@ -103,7 +103,6 @@
     SYSTEM_DATABASE,
     TRUST_ALL_CERTIFICATES,
     TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
-    Version,
     WRITE_ACCESS,
 )
 
@@ -159,7 +158,6 @@
     "TrustAll",
     "TrustCustomCAs",
     "TrustSystemCAs",
-    "Version",
     "__version__",
     "basic_auth",
     "bearer_auth",

src/neo4j/_async/io/_bolt.py

@@ -35,19 +35,18 @@
     BoltError,
     BoltHandshakeError,
 )
+from ..._io import BoltProtocolVersion
 from ..._meta import USER_AGENT
 from ..._sync.config import PoolConfig
 from ...addressing import ResolvedAddress
-from ...api import (
-    ServerInfo,
-    Version,
-)
+from ...api import ServerInfo
 from ...exceptions import (
     ConfigurationError,
     DriverError,
     IncompleteCommit,
     ServiceUnavailable,
     SessionExpired,
+    UnsupportedServerProduct,
 )
 from ..config import AsyncPoolConfig
 from ._bolt_socket import AsyncBoltSocket
@@ -109,7 +108,7 @@ class AsyncBolt:
 
     MAGIC_PREAMBLE = b"\x60\x60\xb0\x17"
 
-    PROTOCOL_VERSION: Version = None  # type: ignore[assignment]
+    PROTOCOL_VERSION: BoltProtocolVersion = None  # type: ignore[assignment]
 
     # flag if connection needs RESET to go back to READY state
     is_reset = False
@@ -159,7 +158,7 @@ def __init__(
             ResolvedAddress(
                 sock.getpeername(), host_name=unresolved_address.host
             ),
-            self.PROTOCOL_VERSION,
+            self.PROTOCOL_VERSION.version,
         )
         self.connection_hints = {}
         self.patch = {}
@@ -244,7 +243,7 @@ def assert_re_auth_support(self):
         if not self.supports_re_auth:
             raise ConfigurationError(
                 "User switching is not supported for Bolt "
-                f"Protocol {self.PROTOCOL_VERSION!r}. Server Agent "
+                f"Protocol {self.PROTOCOL_VERSION}. Server Agent "
                 f"{self.server_info.agent!r}"
             )
 
@@ -257,11 +256,13 @@ def assert_notification_filtering_support(self):
         if not self.supports_notification_filtering:
             raise ConfigurationError(
                 "Notification filtering is not supported for the Bolt "
-                f"Protocol {self.PROTOCOL_VERSION!r}. Server Agent "
+                f"Protocol {self.PROTOCOL_VERSION}. Server Agent "
                 f"{self.server_info.agent!r}"
             )
 
-    protocol_handlers: t.ClassVar[dict[Version, type[AsyncBolt]]] = {}
+    protocol_handlers: t.ClassVar[
+        dict[BoltProtocolVersion, type[AsyncBolt]]
+    ] = {}
 
     def __init_subclass__(cls: type[te.Self], **kwargs: t.Any) -> None:
         if cls.SKIP_REGISTRATION:
@@ -272,14 +273,10 @@ def __init_subclass__(cls: type[te.Self], **kwargs: t.Any) -> None:
             raise ValueError(
                 "AsyncBolt subclasses must define PROTOCOL_VERSION"
             )
-        if not (
-            isinstance(protocol_version, Version)
-            and len(protocol_version) == 2
-            and all(isinstance(i, int) for i in protocol_version)
-        ):
+        if not isinstance(protocol_version, BoltProtocolVersion):
             raise TypeError(
-                "PROTOCOL_VERSION must be a 2-tuple of integers, not "
-                f"{protocol_version!r}"
+                "PROTOCOL_VERSION must be a BoltProtocolVersion, found "
+                f"{type(protocol_version)} for {cls.__name__}"
             )
         if protocol_version in AsyncBolt.protocol_handlers:
             cls_conflict = AsyncBolt.protocol_handlers[protocol_version]
@@ -336,16 +333,15 @@ async def ping(cls, address, *, deadline=None, pool_config=None):
             await AsyncBoltSocket.close_socket(s)
             return protocol_version
 
-    @classmethod
+    @staticmethod
     async def open(
-        cls,
         address,
         *,
         auth_manager=None,
         deadline=None,
         routing_context=None,
         pool_config=None,
-    ):
+    ) -> AsyncBolt:
         """
         Open a new Bolt connection to a given server address.
 
@@ -366,7 +362,7 @@ async def open(
         if deadline is None:
             deadline = Deadline(None)
 
-        s, protocol_version, handshake, data = await AsyncBoltSocket.connect(
+        s, protocol_version = await AsyncBoltSocket.connect(
             address,
             tcp_timeout=pool_config.connection_timeout,
             deadline=deadline,
@@ -381,15 +377,10 @@ async def open(
         if bolt_cls is None:
             log.debug("[#%04X]  C: <CLOSE>", s.getsockname()[1])
             await AsyncBoltSocket.close_socket(s)
-
-            # TODO: 6.0 - raise public DriverError subclass instead
-            raise BoltHandshakeError(
+            raise UnsupportedServerProduct(
                 "The neo4j server does not support communication with this "
                 "driver. This driver has support for Bolt protocols "
-                f"{tuple(map(str, AsyncBolt.protocol_handlers.keys()))}.",
-                address=address,
-                request_data=handshake,
-                response_data=data,
+                f"{tuple(map(str, AsyncBolt.protocol_handlers))}.",
             )
 
         try:

src/neo4j/_async/io/_bolt3.py

@@ -22,10 +22,8 @@
 from ssl import SSLSocket
 
 from ..._exceptions import BoltProtocolError
-from ...api import (
-    READ_ACCESS,
-    Version,
-)
+from ..._io import BoltProtocolVersion
+from ...api import READ_ACCESS
 from ...exceptions import (
     ConfigurationError,
     DatabaseUnavailable,
@@ -146,7 +144,7 @@ class AsyncBolt3(AsyncBolt):
     This is supported by Neo4j versions 3.5, 4.0, 4.1, 4.2, 4.3, and 4.4.
     """
 
-    PROTOCOL_VERSION = Version(3, 0)
+    PROTOCOL_VERSION = BoltProtocolVersion(3, 0)
 
     ssr_enabled = False
 
@@ -270,14 +268,14 @@ async def route(
         if database is not None:
             raise ConfigurationError(
                 "Database name parameter for selecting database is not "
-                f"supported in Bolt Protocol {self.PROTOCOL_VERSION!r}. "
+                f"supported in Bolt Protocol {self.PROTOCOL_VERSION}. "
                 f"Database name {database!r}. "
                 f"Server Agent {self.server_info.agent!r}"
             )
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
@@ -332,13 +330,13 @@ def run(
         if db is not None:
             raise ConfigurationError(
                 "Database name parameter for selecting database is not "
-                f"supported in Bolt Protocol {self.PROTOCOL_VERSION!r}. "
+                f"supported in Bolt Protocol {self.PROTOCOL_VERSION}. "
                 f"Database name {db!r}."
             )
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         if (
@@ -439,13 +437,13 @@ def begin(
         if db is not None:
             raise ConfigurationError(
                 "Database name parameter for selecting database is not "
-                f"supported in Bolt Protocol {self.PROTOCOL_VERSION!r}. "
+                f"supported in Bolt Protocol {self.PROTOCOL_VERSION}. "
                 f"Database name {db!r}."
             )
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         if (

src/neo4j/_async/io/_bolt4.py

@@ -19,10 +19,10 @@
 
 from ..._api import TelemetryAPI
 from ..._exceptions import BoltProtocolError
+from ..._io import BoltProtocolVersion
 from ...api import (
     READ_ACCESS,
     SYSTEM_DATABASE,
-    Version,
 )
 from ...exceptions import (
     ConfigurationError,
@@ -62,7 +62,7 @@ class AsyncBolt4x0(AsyncBolt):
     This is supported by Neo4j versions 4.0-4.4.
     """
 
-    PROTOCOL_VERSION = Version(4, 0)
+    PROTOCOL_VERSION = BoltProtocolVersion(4, 0)
 
     ssr_enabled = False
 
@@ -188,7 +188,7 @@ async def route(
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
@@ -247,7 +247,7 @@ def run(
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         if (
@@ -359,7 +359,7 @@ def begin(
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         if (
@@ -529,7 +529,7 @@ class AsyncBolt4x1(AsyncBolt4x0):
     This is supported by Neo4j versions 4.1 - 4.4.
     """
 
-    PROTOCOL_VERSION = Version(4, 1)
+    PROTOCOL_VERSION = BoltProtocolVersion(4, 1)
 
     def get_base_headers(self):
         # Bolt 4.1 passes the routing context, originally taken from
@@ -551,7 +551,7 @@ class AsyncBolt4x2(AsyncBolt4x1):
     This is supported by Neo4j version 4.2 - 4.4.
     """
 
-    PROTOCOL_VERSION = Version(4, 2)
+    PROTOCOL_VERSION = BoltProtocolVersion(4, 2)
 
     SKIP_REGISTRATION = False
 
@@ -563,7 +563,7 @@ class AsyncBolt4x3(AsyncBolt4x2):
     This is supported by Neo4j version 4.3 - 4.4.
     """
 
-    PROTOCOL_VERSION = Version(4, 3)
+    PROTOCOL_VERSION = BoltProtocolVersion(4, 3)
 
     def get_base_headers(self):
         headers = super().get_base_headers()
@@ -581,7 +581,7 @@ async def route(
         if imp_user is not None:
             raise ConfigurationError(
                 "Impersonation is not supported in Bolt Protocol "
-                f"{self.PROTOCOL_VERSION!r}. Trying to impersonate "
+                f"{self.PROTOCOL_VERSION}. Trying to impersonate "
                 f"{imp_user!r}."
             )
         dehydration_hooks, hydration_hooks = self._default_hydration_hooks(
@@ -668,7 +668,7 @@ class AsyncBolt4x4(AsyncBolt4x3):
     This is supported by Neo4j version 4.4.
     """
 
-    PROTOCOL_VERSION = Version(4, 4)
+    PROTOCOL_VERSION = BoltProtocolVersion(4, 4)
 
     async def route(
         self,