Work around Sphinx issues with postponed evaluation of annotations

With `from __future__ import annotations` in the code, Sphinx gets easily
confused. This applies to several areas like:
 * Type aliases
 * Things defined in `if typing.TYPE_CHECKING` blocks
 * Usage of the `typing_extensions` module

This PR aims to work around as many of those quirks as possible.

Author: robsdedude

docs/source/api.rst

@@ -248,11 +248,11 @@ Closing a driver will immediately shut down all connections in the pool.
         :param query_: cypher query to execute
         :type query_: typing.LiteralString
         :param parameters_: parameters to use in the query
-        :type parameters_: typing.Optional[typing.Dict[str, typing.Any]]
+        :type parameters_: typing.Dict[str, typing.Any] | None
         :param routing_:
             whether to route the query to a reader (follower/read replica) or
             a writer (leader) in the cluster. Default is to route to a writer.
-        :type routing_: neo4j.RoutingControl
+        :type routing_: RoutingControl
         :param database_:
             database to execute the query against.
 
@@ -264,7 +264,7 @@ Closing a driver will immediately shut down all connections in the pool.
                 as it will not have to resolve the default database first.
 
             See also the Session config :ref:`database-ref`.
-        :type database_: typing.Optional[str]
+        :type database_: str | None
         :param impersonated_user_:
             Name of the user to impersonate.
 
@@ -274,7 +274,7 @@ Closing a driver will immediately shut down all connections in the pool.
             permissions.
 
             See also the Session config :ref:`impersonated-user-ref`.
-        :type impersonated_user_: typing.Optional[str]
+        :type impersonated_user_: str | None
         :param auth_:
             Authentication information to use for this query.
 
@@ -286,8 +286,7 @@ Closing a driver will immediately shut down all connections in the pool.
             https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
 
             See also the Session config :ref:`session-auth-ref`.
-        :type auth_:
-            typing.Union[typing.Tuple[typing.Any, typing.Any], neo4j.Auth, None]
+        :type auth_: typing.Tuple[typing.Any, typing.Any] | Auth | None
         :param result_transformer_:
             A function that gets passed the :class:`neo4j.Result` object
             resulting from the query and converts it to a different type. The
@@ -349,7 +348,7 @@ Closing a driver will immediately shut down all connections in the pool.
                     )
 
         :type result_transformer_:
-            typing.Callable[[neo4j.Result], typing.Union[T]]
+            typing.Callable[[Result], T]
         :param bookmark_manager_:
             Specify a bookmark manager to use.
 
@@ -359,8 +358,7 @@ Closing a driver will immediately shut down all connections in the pool.
             Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
-        :type bookmark_manager_:
-            typing.Union[BookmarkManager, BookmarkManager, None]
+        :type bookmark_manager_: BookmarkManager | None
         :param kwargs: additional keyword parameters. None of these can end
             with a single underscore. This is to avoid collisions with the
             keyword configuration parameters of this method. If you need to
@@ -369,7 +367,7 @@ Closing a driver will immediately shut down all connections in the pool.
             ``parameters_``.
         :type kwargs: typing.Any
 
-        :returns: the result of the ``result_transformer``
+        :returns: the result of the ``result_transformer_``
         :rtype: T
 
         .. versionadded:: 5.5

docs/source/async_api.rst

@@ -235,11 +235,11 @@ Closing a driver will immediately shut down all connections in the pool.
         :param query_: cypher query to execute
         :type query_: typing.LiteralString
         :param parameters_: parameters to use in the query
-        :type parameters_: typing.Optional[typing.Dict[str, typing.Any]]
+        :type parameters_: typing.Dict[str, typing.Any] | None
         :param routing_:
             whether to route the query to a reader (follower/read replica) or
             a writer (leader) in the cluster. Default is to route to a writer.
-        :type routing_: neo4j.RoutingControl
+        :type routing_: RoutingControl
         :param database_:
             database to execute the query against.
 
@@ -251,7 +251,7 @@ Closing a driver will immediately shut down all connections in the pool.
                 as it will not have to resolve the default database first.
 
             See also the Session config :ref:`database-ref`.
-        :type database_: typing.Optional[str]
+        :type database_: str | None
         :param impersonated_user_:
             Name of the user to impersonate.
 
@@ -261,7 +261,7 @@ Closing a driver will immediately shut down all connections in the pool.
             permissions.
 
             See also the Session config :ref:`impersonated-user-ref`.
-        :type impersonated_user_: typing.Optional[str]
+        :type impersonated_user_: str | None
         :param auth_:
             Authentication information to use for this query.
 
@@ -273,8 +273,7 @@ Closing a driver will immediately shut down all connections in the pool.
             https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
 
             See also the Session config :ref:`session-auth-ref`.
-        :type auth_:
-            typing.Union[typing.Tuple[typing.Any, typing.Any], neo4j.Auth, None]
+        :type auth_: typing.Tuple[typing.Any, typing.Any] | Auth | None
         :param result_transformer_:
             A function that gets passed the :class:`neo4j.AsyncResult` object
             resulting from the query and converts it to a different type. The
@@ -336,7 +335,7 @@ Closing a driver will immediately shut down all connections in the pool.
                     )
 
         :type result_transformer_:
-            typing.Callable[[neo4j.AsyncResult], typing.Awaitable[T]]
+            typing.Callable[[AsyncResult], typing.Awaitable[T]]
         :param bookmark_manager_:
             Specify a bookmark manager to use.
 
@@ -346,8 +345,7 @@ Closing a driver will immediately shut down all connections in the pool.
             Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
-        :type bookmark_manager_:
-            typing.Union[AsyncBookmarkManager, BookmarkManager, None]
+        :type bookmark_manager_: AsyncBookmarkManager | BookmarkManager | None
         :param kwargs: additional keyword parameters. None of these can end
             with a single underscore. This is to avoid collisions with the
             keyword configuration parameters of this method. If you need to
@@ -356,7 +354,7 @@ Closing a driver will immediately shut down all connections in the pool.
             ``parameters_``.
         :type kwargs: typing.Any
 
-        :returns: the result of the ``result_transformer``
+        :returns: the result of the ``result_transformer_``
         :rtype: T
 
         .. versionadded:: 5.5

docs/source/conf.py

@@ -13,6 +13,7 @@
 
 import os
 import sys
+import typing
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -118,6 +119,17 @@
 # Don't include type hints in function signatures
 autodoc_typehints = "description"
 
+autodoc_type_aliases = {
+    # The code-base uses `import typing_extensions as te`.
+    # Re-write these to use `typing` instead, as Sphinx always resolves against
+    # the latest version of the `typing` module.
+    # This is a work-around to make Sphinx resolve type hints correctly, even
+    # though we're using `from __future__ import annotations`.
+    "te": typing,
+    # Type alias that's only defined and imported if `typing.TYPE_CHECKING`
+    # is `True`.
+    "_TAuth": "typing.Tuple[typing.Any, typing.Any] | Auth | None",
+}
 
 # -- Options for HTML output ----------------------------------------------
 

src/neo4j/_async/auth_management.py

@@ -16,10 +16,7 @@
 # limitations under the License.
 
 
-# from __future__ import annotations
-# work around for https://github.com/sphinx-doc/sphinx/pull/10880
-# make sure TAuth is resolved in the docs, else they're pretty useless
-
+from __future__ import annotations
 
 import typing as t
 from logging import getLogger
@@ -32,11 +29,10 @@
 )
 from .._meta import preview
 
-# work around for https://github.com/sphinx-doc/sphinx/pull/10880
-# make sure TAuth is resolved in the docs, else they're pretty useless
-# if t.TYPE_CHECKING:
-from ..api import _TAuth
-from ..exceptions import Neo4jError
+
+if t.TYPE_CHECKING:
+    from ..api import _TAuth
+    from ..exceptions import Neo4jError
 
 
 log = getLogger("neo4j")

src/neo4j/_async/driver.py

@@ -122,10 +122,7 @@ def driver(
             uri: str,
             *,
             auth: t.Union[
-                # work around https://github.com/sphinx-doc/sphinx/pull/10880
-                # make sure TAuth is resolved in the docs
-                # TAuth,
-                t.Union[t.Tuple[t.Any, t.Any], Auth, None],
+                _TAuth,
                 AsyncAuthManager,
             ] = ...,
             max_connection_lifetime: float = ...,
@@ -172,10 +169,7 @@ def driver(
         def driver(
             cls, uri: str, *,
             auth: t.Union[
-                # work around https://github.com/sphinx-doc/sphinx/pull/10880
-                # make sure TAuth is resolved in the docs
-                # TAuth,
-                t.Union[t.Tuple[t.Any, t.Any], Auth, None],
+                _TAuth,
                 AsyncAuthManager,
             ] = None,
             **config
@@ -716,7 +710,7 @@ async def example(driver: neo4j.AsyncDriver) -> int:
         :param routing_:
             whether to route the query to a reader (follower/read replica) or
             a writer (leader) in the cluster. Default is to route to a writer.
-        :type routing_: neo4j.RoutingControl
+        :type routing_: RoutingControl
         :param database_:
             database to execute the query against.
 
@@ -750,9 +744,7 @@ async def example(driver: neo4j.AsyncDriver) -> int:
             https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
 
             See also the Session config :ref:`session-auth-ref`.
-        :type auth_: typing.Union[
-            typing.Tuple[typing.Any, typing.Any], neo4j.Auth, None
-        ]
+        :type auth_: typing.Tuple[typing.Any, typing.Any] | Auth | None
         :param result_transformer_:
             A function that gets passed the :class:`neo4j.AsyncResult` object
             resulting from the query and converts it to a different type. The
@@ -814,7 +806,7 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
                     )
 
         :type result_transformer_:
-            typing.Callable[[neo4j.AsyncResult], typing.Awaitable[T]]
+            typing.Callable[[AsyncResult], typing.Awaitable[T]]
         :param bookmark_manager_:
             Specify a bookmark manager to use.
 
@@ -824,8 +816,7 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
             Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
-        :type bookmark_manager_:
-            typing.Union[AsyncBookmarkManager, BookmarkManager, None]
+        :type bookmark_manager_: AsyncBookmarkManager | BookmarkManager | None
         :param kwargs: additional keyword parameters. None of these can end
             with a single underscore. This is to avoid collisions with the
             keyword configuration parameters of this method. If you need to
@@ -834,7 +825,7 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
             ``parameters_``.
         :type kwargs: typing.Any
 
-        :returns: the result of the ``result_transformer``
+        :returns: the result of the ``result_transformer_``
         :rtype: T
 
         .. versionadded:: 5.5

src/neo4j/_async/work/result.py

@@ -430,6 +430,7 @@ async def single(self, strict: bool = False) -> t.Optional[Record]:
             instead of returning None if there is more than one record or
             warning if there are more than 1 record.
             :const:`False` by default.
+        :type strict: bool
 
         :returns: the next :class:`neo4j.Record` or :data:`None` if none remain
 

src/neo4j/_async/work/session.py

@@ -274,9 +274,12 @@ async def run(
         For more usage details, see :meth:`.AsyncTransaction.run`.
 
         :param query: cypher query
+        :type query: typing.LiteralString | Query
         :param parameters: dictionary of parameters
+        :type parameters: typing.Dict[str, typing.Any] | None
         :param kwargs: additional keyword parameters.
             These take precedence over parameters passed as ``parameters``.
+        :type kwargs: typing.Any
 
         :returns: a new :class:`neo4j.AsyncResult` object
 
@@ -608,10 +611,15 @@ async def get_two_tx(tx):
             argument and does work with the transaction.
             ``transaction_function(tx, *args, **kwargs)`` where ``tx`` is a
             :class:`.AsyncManagedTransaction`.
+        :type transaction_function:
+            typing.Callable[[AsyncManagedTransaction, P], typing.Awaitable[R]]
         :param args: additional arguments for the `transaction_function`
+        :type args: P
         :param kwargs: key word arguments for the `transaction_function`
+        :type kwargs: P
 
         :returns: whatever the given `transaction_function` returns
+        :rtype: R
 
         :raises SessionError: if the session has been closed.
 
@@ -640,10 +648,15 @@ async def read_transaction(
             argument and does work with the transaction.
             ``transaction_function(tx, *args, **kwargs)`` where ``tx`` is a
             :class:`.AsyncManagedTransaction`.
+        :type transaction_function:
+            typing.Callable[[AsyncManagedTransaction, P], typing.Awaitable[R]]
         :param args: additional arguments for the `transaction_function`
+        :type args: P
         :param kwargs: key word arguments for the `transaction_function`
+        :type kwargs: P
 
         :returns: a result as returned by the given unit of work
+        :rtype: R
 
         :raises SessionError: if the session has been closed.
 
@@ -690,10 +703,15 @@ async def create_node_tx(tx, name):
             argument and does work with the transaction.
             ``transaction_function(tx, *args, **kwargs)`` where ``tx`` is a
             :class:`.AsyncManagedTransaction`.
+        :type transaction_function:
+            typing.Callable[[AsyncManagedTransaction, P], typing.Awaitable[R]]
         :param args: additional arguments for the `transaction_function`
+        :type args: P
         :param kwargs: key word arguments for the `transaction_function`
+        :type kwargs: P
 
         :returns: a result as returned by the given unit of work
+        :rtype: R
 
         :raises SessionError: if the session has been closed.
 
@@ -722,10 +740,15 @@ async def write_transaction(
             argument and does work with the transaction.
             ``transaction_function(tx, *args, **kwargs)`` where ``tx`` is a
             :class:`.AsyncManagedTransaction`.
+        :type transaction_function:
+            typing.Callable[[AsyncManagedTransaction, P], typing.Awaitable[R]]
         :param args: additional arguments for the `transaction_function`
+        :type args: P
         :param kwargs: key word arguments for the `transaction_function`
+        :type kwargs: P
 
         :returns: a result as returned by the given unit of work
+        :rtype: R
 
         :raises SessionError: if the session has been closed.
 

src/neo4j/_async/work/transaction.py

@@ -127,9 +127,12 @@ async def run(
         :class:`list` properties must be homogenous.
 
         :param query: cypher query
+        :type query: typing.LiteralString
         :param parameters: dictionary of parameters
+        :type parameters: typing.Dict[str, typing.Any] | None
         :param kwparameters: additional keyword parameters.
             These take precedence over parameters passed as ``parameters``.
+        :type kwparameters: typing.Any
 
         :raise TransactionError: if the transaction is already closed
 
@@ -255,7 +258,7 @@ def _closed(self):
         """Indicate whether the transaction has been closed or cancelled.
 
         :returns:
-            :const:`True` if closed or cancelled, :const:`False` otherwise.
+            :data:`True` if closed or cancelled, :data:`False` otherwise.
         :rtype: bool
         """
         return self._closed_flag