Docs: Fix typos, add details in auth management features (#1054)

 * Fix typos.
 * Improved cross references.
 * Completed version history of stabilized auth manager APIs.
 * Amend preview remark to some mTLS APIs that already emitted an preview
   warning, but weren't clearly marked as preview in the API docs.
 * Extend details around the static and basic auth provider implementations.

Author: robsdedude

src/neo4j/_async/auth_management.py

@@ -126,6 +126,8 @@ class AsyncAuthManagers:
     def static(auth: _TAuth) -> AsyncAuthManager:
         """Create a static auth manager.
 
+        The manager will always return the auth info provided at its creation.
+
         Example::
 
             # NOTE: this example is for illustration purposes only.
@@ -164,9 +166,13 @@ def basic(
         """Create an auth manager handling basic auth password rotation.
 
         This factory wraps the provider function in an auth manager
-        implementation that caches the provides auth info until either the
-        server notifies the driver that the auth info is expired (by returning
-        an error that indicates that basic auth has changed).
+        implementation that caches the provided auth info until the server
+        notifies the driver that the auth info has expired (by returning
+        an error that indicates that the password is invalid).
+
+        Note that this implies that the provider function will be called again
+        if it provides wrong auth info, potentially deferring failure due to a
+        wrong password or username.
 
         .. warning::
 
@@ -176,8 +182,8 @@ def basic(
             The provider function must only ever return auth information
             belonging to the same identity.
             Switching identities is undefined behavior.
-            You may use session-level authentication for such use-cases
-            :ref:`session-auth-ref`.
+            You may use :ref:`session-level authentication<session-auth-ref>`
+            for such use-cases.
 
         Example::
 
@@ -201,13 +207,13 @@ async def auth_provider():
                 ...  # do stuff
 
         :param provider:
-            A callable that provides a :class:`.ExpiringAuth` instance.
+            A callable that provides new auth info whenever the server notifies
+            the driver that the previous auth info is invalid.
 
         :returns:
             An instance of an implementation of :class:`.AsyncAuthManager` that
             returns auth info from the given provider and refreshes it, calling
-            the provider again, when the auth info expires (because the server
-            flagged it as expired).
+            the provider again, when the auth info was rejected by the server.
 
         .. versionadded:: 5.12
 
@@ -227,9 +233,9 @@ def bearer(
         """Create an auth manager for potentially expiring bearer auth tokens.
 
         This factory wraps the provider function in an auth manager
-        implementation that caches the provides auth info until either the
-        :attr:`.ExpiringAuth.expires_at` is exceeded the server notifies the
-        driver that the auth info is expired (by returning an error that
+        implementation that caches the provided auth info until either the
+        :attr:`.ExpiringAuth.expires_at` exceeded or the server notified the
+        driver that the auth info has expired (by returning an error that
         indicates that the bearer auth token has expired).
 
         .. warning::
@@ -240,8 +246,8 @@ def bearer(
             The provider function must only ever return auth information
             belonging to the same identity.
             Switching identities is undefined behavior.
-            You may use session-level authentication for such use-cases
-            :ref:`session-auth-ref`.
+            You may use :ref:`session-level authentication<session-auth-ref>`
+            for such use-cases.
 
         Example::
 
@@ -364,7 +370,6 @@ class AsyncRotatingClientCertificateProvider(AsyncClientCertificateProvider):
     :param initial_cert: The certificate to use initially.
 
     .. versionadded:: 5.19
-
     """
     def __init__(self, initial_cert: ClientCertificate) -> None:
         self._cert: t.Optional[ClientCertificate] = initial_cert

src/neo4j/_auth_management.py

@@ -113,8 +113,8 @@ class AuthManager(metaclass=abc.ABCMeta):
 
         The token returned must always belong to the same identity.
         Switching identities using the `AuthManager` is undefined behavior.
-        You may use session-level authentication for such use-cases
-        :ref:`session-auth-ref`.
+        You may use :ref:`session-level authentication<session-auth-ref>`
+        for such use-cases.
 
     .. seealso:: :class:`.AuthManagers`
 
@@ -123,9 +123,11 @@ class AuthManager(metaclass=abc.ABCMeta):
     .. versionchanged:: 5.12
         ``on_auth_expired`` was removed from the interface and replaced by
         :meth:`handle_security_exception`. The new method is called when the
-        server returns any `Neo.ClientError.Security.*` error. It's signature
+        server returns any `Neo.ClientError.Security.*` error. Its signature
         differs in that it additionally receives the error returned by the
         server and returns a boolean indicating whether the error was handled.
+
+    .. versionchanged:: 5.14 Stabilized from preview.
     """
 
     @abc.abstractmethod
@@ -140,8 +142,8 @@ def get_auth(self) -> _TAuth:
             The method must only ever return auth information belonging to the
             same identity.
             Switching identities using the `AuthManager` is undefined behavior.
-            You may use session-level authentication for such use-cases
-            :ref:`session-auth-ref`.
+            You may use :ref:`session-level authentication<session-auth-ref>`
+            for such use-cases.
         """
         ...
 
@@ -181,6 +183,8 @@ class AsyncAuthManager(_Protocol, metaclass=abc.ABCMeta):
     .. versionchanged:: 5.12
         ``on_auth_expired`` was removed from the interface and replaced by
          :meth:`handle_security_exception`. See :class:`.AuthManager`.
+
+    .. versionchanged:: 5.14 Stabilized from preview.
     """
 
     @abc.abstractmethod
@@ -211,6 +215,11 @@ class ClientCertificate:
     The attributes are the same as the arguments to
     :meth:`ssl.SSLContext.load_cert_chain()`.
 
+    **This is a preview** (see :ref:`filter-warnings-ref`).
+    It might be changed without following the deprecation policy.
+    See also
+    https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
     .. versionadded:: 5.19
     """
     certfile: t.Union[str, bytes, PathLike[str], PathLike[bytes]]
@@ -248,6 +257,11 @@ class ClientCertificateProvider(_Protocol, metaclass=abc.ABCMeta):
         The provider **must not** interact with the driver in any way as this
         can cause deadlocks and undefined behaviour.
 
+    **This is a preview** (see :ref:`filter-warnings-ref`).
+    It might be changed without following the deprecation policy.
+    See also
+    https://github.com/neo4j/neo4j-python-driver/wiki/preview-features
+
     .. versionadded:: 5.19
     """
 

src/neo4j/_sync/auth_management.py

@@ -126,6 +126,8 @@ class AuthManagers:
     def static(auth: _TAuth) -> AuthManager:
         """Create a static auth manager.
 
+        The manager will always return the auth info provided at its creation.
+
         Example::
 
             # NOTE: this example is for illustration purposes only.
@@ -164,9 +166,13 @@ def basic(
         """Create an auth manager handling basic auth password rotation.
 
         This factory wraps the provider function in an auth manager
-        implementation that caches the provides auth info until either the
-        server notifies the driver that the auth info is expired (by returning
-        an error that indicates that basic auth has changed).
+        implementation that caches the provided auth info until the server
+        notifies the driver that the auth info has expired (by returning
+        an error that indicates that the password is invalid).
+
+        Note that this implies that the provider function will be called again
+        if it provides wrong auth info, potentially deferring failure due to a
+        wrong password or username.
 
         .. warning::
 
@@ -176,8 +182,8 @@ def basic(
             The provider function must only ever return auth information
             belonging to the same identity.
             Switching identities is undefined behavior.
-            You may use session-level authentication for such use-cases
-            :ref:`session-auth-ref`.
+            You may use :ref:`session-level authentication<session-auth-ref>`
+            for such use-cases.
 
         Example::
 
@@ -201,13 +207,13 @@ def auth_provider():
                 ...  # do stuff
 
         :param provider:
-            A callable that provides a :class:`.ExpiringAuth` instance.
+            A callable that provides new auth info whenever the server notifies
+            the driver that the previous auth info is invalid.
 
         :returns:
             An instance of an implementation of :class:`.AuthManager` that
             returns auth info from the given provider and refreshes it, calling
-            the provider again, when the auth info expires (because the server
-            flagged it as expired).
+            the provider again, when the auth info was rejected by the server.
 
         .. versionadded:: 5.12
 
@@ -227,9 +233,9 @@ def bearer(
         """Create an auth manager for potentially expiring bearer auth tokens.
 
         This factory wraps the provider function in an auth manager
-        implementation that caches the provides auth info until either the
-        :attr:`.ExpiringAuth.expires_at` is exceeded the server notifies the
-        driver that the auth info is expired (by returning an error that
+        implementation that caches the provided auth info until either the
+        :attr:`.ExpiringAuth.expires_at` exceeded or the server notified the
+        driver that the auth info has expired (by returning an error that
         indicates that the bearer auth token has expired).
 
         .. warning::
@@ -240,8 +246,8 @@ def bearer(
             The provider function must only ever return auth information
             belonging to the same identity.
             Switching identities is undefined behavior.
-            You may use session-level authentication for such use-cases
-            :ref:`session-auth-ref`.
+            You may use :ref:`session-level authentication<session-auth-ref>`
+            for such use-cases.
 
         Example::
 
@@ -364,7 +370,6 @@ class RotatingClientCertificateProvider(ClientCertificateProvider):
     :param initial_cert: The certificate to use initially.
 
     .. versionadded:: 5.19
-
     """
     def __init__(self, initial_cert: ClientCertificate) -> None:
         self._cert: t.Optional[ClientCertificate] = initial_cert