Merge pull request #1195 from robsdedude/mark-imports-private

Mark indirectly exposed items from imports as private
(e.g. `collections.abc.Mapping` as `neo4j.graph.Mapping`).

Affected packages/modules:
 * `neo4j.exceptions`
 * `neo4j.graph`
 * `neo4j.addressing`
 * `neo4j.api`.

Author: robsdedude

CHANGELOG.md

@@ -98,6 +98,7 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
     - `ERROR_REWRITE_MAP`
     - `client_errors`
     - `transient_errors`
+    - all other indirectly exposed items from imports (e.g. `typing` as `neo4j.exceptions.t`)
   - `neo4j.time`
     - `DATE_ISO_PATTERN`
     - `TIME_ISO_PATTERN`
@@ -128,6 +129,8 @@ 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.api`
+    - indirectly exposed items from imports (e.g. `collections.abc.Mapping` as `neo4j.graph.Mapping`).
   - `BoltDriver` and `Neo4jDriver`
     - `.open`
     - `.parse_target`

src/neo4j/addressing.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 
 
-from __future__ import annotations
+from __future__ import annotations as _
 
 from ._addressing import (
     Address,

src/neo4j/api.py

@@ -16,15 +16,17 @@
 
 """Base classes and helpers."""
 
-from __future__ import annotations
+from __future__ import annotations as _
 
-import abc
+import abc as _abc
 
 from . 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:
-    from ._addressing import Address
     from ._typing import Protocol as _Protocol
 else:
     _Protocol = object
@@ -279,13 +281,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
 
@@ -314,7 +316,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.
 
@@ -355,7 +357,7 @@ 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],
@@ -371,7 +373,7 @@ def update_bookmarks(
         """
         ...
 
-    @abc.abstractmethod
+    @_abc.abstractmethod
     def get_bookmarks(self) -> _t.Collection[str]:
         """
         Return the bookmarks stored in the bookmark manager.
@@ -381,7 +383,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.
 
@@ -396,7 +398,7 @@ 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],
@@ -405,7 +407,7 @@ async def update_bookmarks(
 
     update_bookmarks.__doc__ = BookmarkManager.update_bookmarks.__doc__
 
-    @abc.abstractmethod
+    @_abc.abstractmethod
     async def get_bookmarks(self) -> _t.Collection[str]: ...
 
     get_bookmarks.__doc__ = BookmarkManager.get_bookmarks.__doc__

src/neo4j/exceptions.py

@@ -60,7 +60,7 @@
     + ConnectionAcquisitionTimeoutError
 """
 
-from __future__ import annotations
+from __future__ import annotations as _
 
 from copy import deepcopy as _deepcopy
 from enum import Enum as _Enum
@@ -71,26 +71,26 @@
 
 if _t.TYPE_CHECKING:
     from ._async.work import (
-        AsyncManagedTransaction,
-        AsyncResult,
-        AsyncSession,
-        AsyncTransaction,
+        AsyncManagedTransaction as _AsyncManagedTransaction,
+        AsyncResult as _AsyncResult,
+        AsyncSession as _AsyncSession,
+        AsyncTransaction as _AsyncTransaction,
     )
     from ._sync.work import (
-        ManagedTransaction,
-        Result,
-        Session,
-        Transaction,
+        ManagedTransaction as _ManagedTransaction,
+        Result as _Result,
+        Session as _Session,
+        Transaction as _Transaction,
     )
 
     _TTransaction: _t.TypeAlias = (
-        AsyncManagedTransaction
-        | AsyncTransaction
-        | ManagedTransaction
-        | Transaction
+        _AsyncManagedTransaction
+        | _AsyncTransaction
+        | _ManagedTransaction
+        | _Transaction
     )
-    _TResult: _t.TypeAlias = AsyncResult | Result
-    _TSession: _t.TypeAlias = AsyncSession | Session
+    _TResult: _t.TypeAlias = _AsyncResult | _Result
+    _TSession: _t.TypeAlias = _AsyncSession | _Session
     _T = _t.TypeVar("_T")
 
 

src/neo4j/graph/__init__.py

@@ -16,17 +16,17 @@
 
 """Graph data types as returned by the DBMS."""
 
-from __future__ import annotations
+from __future__ import annotations as _
 
-from collections.abc import Mapping
+from collections.abc import Mapping as _Mapping
 
 from .. import _typing as _t
 
 
 if _t.TYPE_CHECKING:
-    from typing_extensions import deprecated
+    from typing_extensions import deprecated as _deprecated
 else:
-    from .._warnings import deprecated
+    from .._warnings import deprecated as _deprecated
 
 
 __all__ = [
@@ -151,7 +151,7 @@ def graph(self) -> Graph:
         return self._graph
 
     @property  # type: ignore
-    @deprecated("`id` is deprecated, use `element_id` instead")
+    @_deprecated("`id` is deprecated, use `element_id` instead")
     def id(self) -> int:
         """
         The legacy identity of this entity in its container :class:`.Graph`.
@@ -200,7 +200,7 @@ def items(self) -> _t.ItemsView[str, _t.Any]:
         return self._properties.items()
 
 
-class EntitySetView(Mapping, _t.Generic[_T]):
+class EntitySetView(_Mapping, _t.Generic[_T]):
     """View of a set of :class:`.Entity` instances within a :class:`.Graph`."""
 
     def __init__(