Fixing documentation and type hints (#927)

* When renaming some of the re-auth APIs before stabilizing them in 5.8,
   some references in the docs were missed.
 * The docs for `ExpiringAuth` was completely missing becuase the `@preview`
   decorator broke sphinx.
 * Fix typing change in `datetime.replace` breaking us (arguments were changed
   from type `int` to `SupportsIndex`). As a virtual subclass, our custom
   temporal types should follow this change.
 * Fix broken layout of `execute_query` parameter docs.

Author: robsdedude

docs/source/api.rst

@@ -160,11 +160,11 @@ Closing a driver will immediately shut down all connections in the pool.
     query, use :meth:`neo4j.Driver.verify_connectivity`.
 
 .. autoclass:: neo4j.Driver()
-    :members: session, query_bookmark_manager, encrypted, close,
+    :members: session, execute_query_bookmark_manager, encrypted, close,
               verify_connectivity, get_server_info, verify_authentication,
               supports_session_auth, supports_multi_db
 
-    .. method:: execute_query(query, parameters_=None,routing_=neo4j.RoutingControl.WRITE, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=Result.to_eager_result, **kwargs)
+    .. method:: execute_query(query, parameters_=None,routing_=neo4j.RoutingControl.WRITE, database_=None, impersonated_user_=None, bookmark_manager_=self.execute_query_bookmark_manager, result_transformer_=Result.to_eager_result, **kwargs)
 
         Execute a query in a transaction function and return all results.
 
@@ -283,9 +283,8 @@ 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.Union[typing.Tuple[typing.Any, typing.Any], neo4j.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
@@ -354,12 +353,11 @@ Closing a driver will immediately shut down all connections in the pool.
             If present, the bookmark manager is used to keep the query causally
             consistent with all work executed using the same bookmark manager.
 
-            Defaults to the driver's :attr:`.query_bookmark_manager`.
+            Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
         :type bookmark_manager_:
-            typing.Union[neo4j.BookmarkManager, neo4j.BookmarkManager,
-                         None]
+            typing.Union[BookmarkManager, 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

docs/source/async_api.rst

@@ -149,11 +149,11 @@ Closing a driver will immediately shut down all connections in the pool.
     query, use :meth:`neo4j.AsyncDriver.verify_connectivity`.
 
 .. autoclass:: neo4j.AsyncDriver()
-    :members: session, query_bookmark_manager, encrypted, close,
+    :members: session, execute_query_bookmark_manager, encrypted, close,
               verify_connectivity, get_server_info, verify_authentication,
               supports_session_auth, supports_multi_db
 
-    .. method:: execute_query(query, parameters_=None, routing_=neo4j.RoutingControl.WRITE, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=AsyncResult.to_eager_result, **kwargs)
+    .. method:: execute_query(query, parameters_=None, routing_=neo4j.RoutingControl.WRITE, database_=None, impersonated_user_=None, bookmark_manager_=self.execute_query_bookmark_manager, result_transformer_=AsyncResult.to_eager_result, **kwargs)
         :async:
 
         Execute a query in a transaction function and return all results.
@@ -273,9 +273,8 @@ 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.Union[typing.Tuple[typing.Any, typing.Any], neo4j.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
@@ -344,12 +343,11 @@ Closing a driver will immediately shut down all connections in the pool.
             If present, the bookmark manager is used to keep the query causally
             consistent with all work executed using the same bookmark manager.
 
-            Defaults to the driver's :attr:`.query_bookmark_manager`.
+            Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
         :type bookmark_manager_:
-            typing.Union[neo4j.AsyncBookmarkManager, neo4j.BookmarkManager,
-                         None]
+            typing.Union[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

src/neo4j/_async/driver.py

@@ -805,12 +805,11 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
             If present, the bookmark manager is used to keep the query causally
             consistent with all work executed using the same bookmark manager.
 
-            Defaults to the driver's :attr:`.query_bookmark_manager`.
+            Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
         :type bookmark_manager_:
-            typing.Union[neo4j.AsyncBookmarkManager, neo4j.BookmarkManager,
-                         None]
+            typing.Union[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
@@ -875,7 +874,7 @@ def execute_query_bookmark_manager(self) -> AsyncBookmarkManager:
             async def example(driver: neo4j.AsyncDriver) -> None:
                 await driver.execute_query("<QUERY 1>")
                 async with driver.session(
-                    bookmark_manager=driver.query_bookmark_manager
+                    bookmark_manager=driver.execute_query_bookmark_manager
                 ) as session:
                     # every query inside this session will be causally chained
                     # (i.e., can read what was written by <QUERY 1>)

src/neo4j/_auth_management.py

@@ -34,8 +34,8 @@
 class ExpiringAuth:
     """Represents potentially expiring authentication information.
 
-    This class is used with :meth:`.AuthManagers.temporal` and
-    :meth:`.AsyncAuthManagers.temporal`.
+    This class is used with :meth:`.AuthManagers.expiration_based` and
+    :meth:`.AsyncAuthManagers.expiration_based`.
 
     :param auth: The authentication information.
     :param expires_in: The number of seconds until the authentication
@@ -47,7 +47,8 @@ class ExpiringAuth:
     See also https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
 
     .. seealso::
-        :meth:`.AuthManagers.temporal`, :meth:`.AsyncAuthManagers.temporal`
+        :meth:`.AuthManagers.expiration_based`,
+        :meth:`.AsyncAuthManagers.expiration_based`
 
     .. versionadded:: 5.8
     """

src/neo4j/_meta.py

@@ -16,10 +16,13 @@
 # limitations under the License.
 
 
+from __future__ import annotations
+
 import asyncio
 import tracemalloc
 import typing as t
 from functools import wraps
+from inspect import isclass
 from warnings import warn
 
 
@@ -67,23 +70,7 @@ def foo(x):
             pass
 
     """
-    def decorator(f):
-        if asyncio.iscoroutinefunction(f):
-            @wraps(f)
-            async def inner(*args, **kwargs):
-                deprecation_warn(message, stack_level=2)
-                return await f(*args, **kwargs)
-
-            return inner
-        else:
-            @wraps(f)
-            def inner(*args, **kwargs):
-                deprecation_warn(message, stack_level=2)
-                return f(*args, **kwargs)
-
-            return inner
-
-    return decorator
+    return _make_warning_decorator(message, deprecation_warn)
 
 
 def deprecated_property(message: str):
@@ -104,20 +91,6 @@ def experimental_warn(message, stack_level=1):
     warn(message, category=ExperimentalWarning, stacklevel=stack_level + 1)
 
 
-class PreviewWarning(Warning):
-    """ Base class for warnings about experimental features.
-    """
-
-
-def preview_warn(message, stack_level=1):
-    message += (
-        " It might be changed without following the deprecation policy. "
-        "See also "
-        "https://github.com/neo4j/neo4j-python-driver/wiki/preview-features."
-    )
-    warn(message, category=PreviewWarning, stacklevel=stack_level + 1)
-
-
 def experimental(message) -> t.Callable[[_FuncT], _FuncT]:
     """ Decorator for tagging experimental functions and methods.
 
@@ -147,7 +120,21 @@ def inner(*args, **kwargs):
 
             return inner
 
-    return decorator
+    return _make_warning_decorator(message, experimental_warn)
+
+
+class PreviewWarning(Warning):
+    """ Base class for warnings about experimental features.
+    """
+
+
+def preview_warn(message, stack_level=1):
+    message += (
+        " It might be changed without following the deprecation policy. "
+        "See also "
+        "https://github.com/neo4j/neo4j-python-driver/wiki/preview-features."
+    )
+    warn(message, category=PreviewWarning, stacklevel=stack_level + 1)
 
 
 def preview(message) -> t.Callable[[_FuncT], _FuncT]:
@@ -158,18 +145,47 @@ def preview(message) -> t.Callable[[_FuncT], _FuncT]:
         def foo(x):
             pass
     """
+
+    return _make_warning_decorator(message, preview_warn)
+
+
+if t.TYPE_CHECKING:
+    class _WarningFunc(t.Protocol):
+        def __call__(self, message: str, stack_level: int = 1) -> None:
+            ...
+else:
+    _WarningFunc = object
+
+
+def _make_warning_decorator(
+    message: str,
+    warning_func: _WarningFunc,
+) -> t.Callable[[_FuncT], _FuncT]:
     def decorator(f):
         if asyncio.iscoroutinefunction(f):
             @wraps(f)
             async def inner(*args, **kwargs):
-                preview_warn(message, stack_level=2)
+                warning_func(message, stack_level=2)
                 return await f(*args, **kwargs)
 
             return inner
+        if isclass(f):
+            if hasattr(f, "__init__"):
+                original_init = f.__init__
+                @wraps(original_init)
+                def inner(*args, **kwargs):
+                    warning_func(message, stack_level=2)
+                    return original_init(*args, **kwargs)
+
+                f.__init__ = inner
+                return f
+            raise TypeError(
+                "Cannot decorate class without __init__"
+            )
         else:
             @wraps(f)
             def inner(*args, **kwargs):
-                preview_warn(message, stack_level=2)
+                warning_func(message, stack_level=2)
                 return f(*args, **kwargs)
 
             return inner

src/neo4j/_sync/driver.py

@@ -804,12 +804,11 @@ def example(driver: neo4j.Driver) -> neo4j.Record::
             If present, the bookmark manager is used to keep the query causally
             consistent with all work executed using the same bookmark manager.
 
-            Defaults to the driver's :attr:`.query_bookmark_manager`.
+            Defaults to the driver's :attr:`.execute_query_bookmark_manager`.
 
             Pass :data:`None` to disable causal consistency.
         :type bookmark_manager_:
-            typing.Union[neo4j.BookmarkManager, neo4j.BookmarkManager,
-                         None]
+            typing.Union[BookmarkManager, 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
@@ -874,7 +873,7 @@ def execute_query_bookmark_manager(self) -> BookmarkManager:
             def example(driver: neo4j.Driver) -> None:
                 driver.execute_query("<QUERY 1>")
                 with driver.session(
-                    bookmark_manager=driver.query_bookmark_manager
+                    bookmark_manager=driver.execute_query_bookmark_manager
                 ) as session:
                     # every query inside this session will be causally chained
                     # (i.e., can read what was written by <QUERY 1>)