neo4j.api remove indirectly exposed items from imports

Author: robsdedude

CHANGELOG.md

@@ -104,7 +104,7 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
     - `.default_host`
     - `.default_port`
     - `.default_target`
-  - `neo4j.graph`, `neo4j.addressing`
+  - `neo4j.graph`, `neo4j.addressing`, `neo4j.api`
     - indirectly exposed items from imports (e.g. `collections.abc.Mapping` as `neo4j.graph.Mapping`).
 - Raise `ConfigurationError` instead of ignoring the routing context (URI query parameters) when creating a direct
   driver ("bolt[+s[sc]]://" scheme).

src/neo4j/api.py

@@ -16,22 +16,25 @@
 
 """Base classes and helpers."""
 
-from __future__ import annotations
+from __future__ import annotations as _
 
-import abc
-import typing as t
+import abc as _abc
+import typing as _t
 
+# ignore TCH001 to make sphinx not completely drop the ball
+from ._addressing import Address as _Address  # noqa: TCH001
 
-if t.TYPE_CHECKING:
-    import typing_extensions as te
+
+if _t.TYPE_CHECKING:
+    import typing_extensions as _te
     from typing_extensions import (
-        deprecated,
+        deprecated as _deprecated,
         Protocol as _Protocol,
     )
 
-    from ._addressing import Address
+
 else:
-    from ._warnings import deprecated
+    from ._warnings import deprecated as _deprecated
 
     _Protocol = object
 
@@ -61,21 +64,21 @@
 ]
 
 
-READ_ACCESS: te.Final[str] = "READ"
-WRITE_ACCESS: te.Final[str] = "WRITE"
+READ_ACCESS: _te.Final[str] = "READ"
+WRITE_ACCESS: _te.Final[str] = "WRITE"
 
-URI_SCHEME_BOLT: te.Final[str] = "bolt"
-URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE: te.Final[str] = "bolt+ssc"
-URI_SCHEME_BOLT_SECURE: te.Final[str] = "bolt+s"
+URI_SCHEME_BOLT: _te.Final[str] = "bolt"
+URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE: _te.Final[str] = "bolt+ssc"
+URI_SCHEME_BOLT_SECURE: _te.Final[str] = "bolt+s"
 
-URI_SCHEME_NEO4J: te.Final[str] = "neo4j"
-URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE: te.Final[str] = "neo4j+ssc"
-URI_SCHEME_NEO4J_SECURE: te.Final[str] = "neo4j+s"
+URI_SCHEME_NEO4J: _te.Final[str] = "neo4j"
+URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE: _te.Final[str] = "neo4j+ssc"
+URI_SCHEME_NEO4J_SECURE: _te.Final[str] = "neo4j+s"
 
-URI_SCHEME_BOLT_ROUTING: te.Final[str] = "bolt+routing"
+URI_SCHEME_BOLT_ROUTING: _te.Final[str] = "bolt+routing"
 
-SYSTEM_DATABASE: te.Final[str] = "system"
-DEFAULT_DATABASE: te.Final[None] = None  # Must be a non string hashable value
+SYSTEM_DATABASE: _te.Final[str] = "system"
+DEFAULT_DATABASE: _te.Final[None] = None  # Must be a non string hashable value
 
 
 # TODO: This class is not tested
@@ -103,7 +106,7 @@ def __init__(
         principal: str | None,
         credentials: str | None,
         realm: str | None = None,
-        **parameters: t.Any,
+        **parameters: _t.Any,
     ) -> None:
         self.scheme = scheme
         # Neo4j servers pre 4.4 require the principal field to always be
@@ -117,7 +120,7 @@ def __init__(
         if parameters:
             self.parameters = parameters
 
-    def __eq__(self, other: t.Any) -> bool:
+    def __eq__(self, other: _t.Any) -> bool:
         if not isinstance(other, Auth):
             return NotImplemented
         return vars(self) == vars(other)
@@ -126,8 +129,8 @@ def __eq__(self, other: t.Any) -> bool:
 # For backwards compatibility
 AuthToken = Auth
 
-if t.TYPE_CHECKING:
-    _TAuth: t.TypeAlias = tuple[str, str] | Auth | None
+if _t.TYPE_CHECKING:
+    _TAuth: _t.TypeAlias = tuple[str, str] | Auth | None
 
 
 def basic_auth(user: str, password: str, realm: str | None = None) -> Auth:
@@ -181,7 +184,7 @@ def custom_auth(
     credentials: str | None,
     realm: str | None,
     scheme: str | None,
-    **parameters: t.Any,
+    **parameters: _t.Any,
 ) -> Auth:
     """
     Generate a custom auth token.
@@ -253,7 +256,7 @@ def raw_values(self) -> frozenset[str]:
         return self._raw_values
 
     @classmethod
-    def from_raw_values(cls, values: t.Iterable[str]) -> Bookmarks:
+    def from_raw_values(cls, values: _t.Iterable[str]) -> Bookmarks:
         """
         Create a Bookmarks object from a list of raw bookmark string values.
 
@@ -286,13 +289,13 @@ def from_raw_values(cls, values: t.Iterable[str]) -> Bookmarks:
 class ServerInfo:
     """Represents a package of information relating to a Neo4j server."""
 
-    def __init__(self, address: Address, protocol_version: tuple[int, int]):
+    def __init__(self, address: _Address, protocol_version: tuple[int, int]):
         self._address = address
         self._protocol_version = protocol_version
         self._metadata: dict = {}
 
     @property
-    def address(self) -> Address:
+    def address(self) -> _Address:
         """Network address of the remote server."""
         return self._address
 
@@ -312,7 +315,7 @@ def agent(self) -> str:
         return str(self._metadata.get("server"))
 
     @property  # type: ignore
-    @deprecated(
+    @_deprecated(
         "The connection id is considered internal information "
         "and will no longer be exposed in future versions."
     )
@@ -330,7 +333,7 @@ def update(self, metadata: dict) -> None:
         self._metadata.update(metadata)
 
 
-class BookmarkManager(_Protocol, metaclass=abc.ABCMeta):
+class BookmarkManager(_Protocol, metaclass=_abc.ABCMeta):
     """
     Class to manage bookmarks throughout the driver's lifetime.
 
@@ -371,11 +374,11 @@ class BookmarkManager(_Protocol, metaclass=abc.ABCMeta):
     .. versionchanged:: 5.8 Stabilized from experimental.
     """
 
-    @abc.abstractmethod
+    @_abc.abstractmethod
     def update_bookmarks(
         self,
-        previous_bookmarks: t.Collection[str],
-        new_bookmarks: t.Collection[str],
+        previous_bookmarks: _t.Collection[str],
+        new_bookmarks: _t.Collection[str],
     ) -> None:
         """
         Handle bookmark updates.
@@ -387,8 +390,8 @@ def update_bookmarks(
         """
         ...
 
-    @abc.abstractmethod
-    def get_bookmarks(self) -> t.Collection[str]:
+    @_abc.abstractmethod
+    def get_bookmarks(self) -> _t.Collection[str]:
         """
         Return the bookmarks stored in the bookmark manager.
 
@@ -397,7 +400,7 @@ def get_bookmarks(self) -> t.Collection[str]:
         ...
 
 
-class AsyncBookmarkManager(_Protocol, metaclass=abc.ABCMeta):
+class AsyncBookmarkManager(_Protocol, metaclass=_abc.ABCMeta):
     """
     Same as :class:`.BookmarkManager` but with async methods.
 
@@ -412,16 +415,16 @@ class AsyncBookmarkManager(_Protocol, metaclass=abc.ABCMeta):
     .. versionchanged:: 5.8 Stabilized from experimental.
     """
 
-    @abc.abstractmethod
+    @_abc.abstractmethod
     async def update_bookmarks(
         self,
-        previous_bookmarks: t.Collection[str],
-        new_bookmarks: t.Collection[str],
+        previous_bookmarks: _t.Collection[str],
+        new_bookmarks: _t.Collection[str],
     ) -> None: ...
 
     update_bookmarks.__doc__ = BookmarkManager.update_bookmarks.__doc__
 
-    @abc.abstractmethod
-    async def get_bookmarks(self) -> t.Collection[str]: ...
+    @_abc.abstractmethod
+    async def get_bookmarks(self) -> _t.Collection[str]: ...
 
     get_bookmarks.__doc__ = BookmarkManager.get_bookmarks.__doc__