diff --git a/src/neo4j/_async/auth_management.py b/src/neo4j/_async/auth_management.py index baab82172..be4d309ff 100644 --- a/src/neo4j/_async/auth_management.py +++ b/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` + 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` + 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 diff --git a/src/neo4j/_auth_management.py b/src/neo4j/_auth_management.py index 8552c906c..b4411a042 100644 --- a/src/neo4j/_auth_management.py +++ b/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` + 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` + 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 """ diff --git a/src/neo4j/_sync/auth_management.py b/src/neo4j/_sync/auth_management.py index dcae6c351..665fbdb07 100644 --- a/src/neo4j/_sync/auth_management.py +++ b/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` + 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` + 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