Merge branch '6.x' into errors/value-error-on-invalid-acquisition-timeout

Author: robsdedude

CHANGELOG.md

@@ -6,7 +6,37 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
 - Python 3.7, 3.8, and 3.9 support has been dropped.
 - Remove deprecated package alias `neo4j-driver`. Use `pip install neo4j` instead.
 - Remove `setup.py`. Please use a recent enough packaging/build tool that supports `pyproject.toml`
+- Remove deprecated modules:
+  - `neo4j.conf`
+  - `neo4j.data`
+  - `neo4j.meta`
+  - `neo4j.packstream`
+  - `neo4j.routing`
+  - `neo4j.time.arithmetic`
+  - `neo4j.time.clock_implementation`
+  - `neo4j.time.hydration`
+  - `neo4j.time.metaclasses`
+  - `neo4j.work`
+  - `neo4j.work.query`
+  - `neo4j.work.summary`
+- 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).
   - `connection_acquisition_timeout` configuration option
     - `ValueError` on invalid values (instead of `ClientError`)
     - Consistently restrict the value to be strictly positive

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

@@ -15,7 +15,6 @@
 
 
 import typing as _t
-from logging import getLogger as _getLogger
 
 from ._api import (  # noqa: F401 dynamic attributes
     NotificationCategory,
@@ -37,26 +36,19 @@
     AsyncSession,
     AsyncTransaction,
 )
-from ._conf import (  # noqa: F401 dynamic attribute
-    Config as _Config,
-    SessionConfig as _SessionConfig,
+from ._conf import (
     TrustAll,
     TrustCustomCAs,
     TrustSystemCAs,
-    WorkspaceConfig as _WorkspaceConfig,
 )
 from ._data import Record
 from ._meta import (
-    deprecation_warn as _deprecation_warn,
     ExperimentalWarning,
     get_user_agent,
     preview_warn as _preview_warn,
     PreviewWarning,
     version as __version__,
 )
-from ._sync.config import (  # noqa: F401 dynamic attribute
-    PoolConfig as _PoolConfig,
-)
 from ._sync.driver import (
     BoltDriver,
     Driver,
@@ -87,7 +79,6 @@
     from ._work import (
         GqlStatusObject,  # noqa: TCH004 false positive (dynamic attribute)
         NotificationClassification,  # noqa: TCH004 false positive (dynamic attribute)
-        SummaryInputPosition as SummaryNotificationPosition,  # noqa: TCH004 false positive (dynamic attribute)
     )
 
 from .addressing import (
@@ -112,7 +103,6 @@
     SYSTEM_DATABASE,
     TRUST_ALL_CERTIFICATES,
     TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
-    Version,
     WRITE_ACCESS,
 )
 
@@ -138,7 +128,6 @@
     "BoltDriver",
     "Bookmark",
     "Bookmarks",
-    "Config",  # noqa: F822 dynamic attribute
     "Driver",
     "EagerResult",
     "ExperimentalWarning",
@@ -154,7 +143,6 @@
     "NotificationDisabledClassification",
     "NotificationMinimumSeverity",
     "NotificationSeverity",
-    "PoolConfig",  # noqa: F822 dynamic attribute
     "PreviewWarning",
     "Query",
     "Record",
@@ -163,53 +151,25 @@
     "RoutingControl",
     "ServerInfo",
     "Session",
-    "SessionConfig",  # noqa: F822 dynamic attribute
     "SummaryCounters",
     "SummaryInputPosition",
     "SummaryNotification",
-    "SummaryNotificationPosition",
     "Transaction",
     "TrustAll",
     "TrustCustomCAs",
     "TrustSystemCAs",
-    "Version",
-    "WorkspaceConfig",  # noqa: F822 dynamic attribute
     "__version__",
     "basic_auth",
     "bearer_auth",
     "custom_auth",
     "get_user_agent",
     "kerberos_auth",
-    "log",  # noqa: F822 dynamic attribute
     "unit_of_work",
 ]
 
 
-_log = _getLogger("neo4j")
-
-
 def __getattr__(name) -> _t.Any:
     # TODO: 6.0 - remove this
-    if name in {
-        "log",
-        "Config",
-        "PoolConfig",
-        "SessionConfig",
-        "WorkspaceConfig",
-    }:
-        _deprecation_warn(
-            f"Importing {name} from neo4j is deprecated without replacement. "
-            "It's internal and will be removed in a future version.",
-            stack_level=2,
-        )
-        return globals()[f"_{name}"]
-    if name == "SummaryNotificationPosition":
-        _deprecation_warn(
-            "SummaryNotificationPosition is deprecated. "
-            "Use SummaryInputPosition instead.",
-            stack_level=2,
-        )
-        return SummaryInputPosition
     if name in {
         "NotificationClassification",
         "GqlStatusObject",

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 (