Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 2, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 19 additions & 14 deletions src/neo4j/_async/auth_management.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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::

Expand All @@ -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::

Expand All @@ -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

Expand All @@ -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::
Expand All @@ -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::

Expand Down Expand Up @@ -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
Expand Down
24 changes: 19 additions & 5 deletions src/neo4j/_auth_management.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -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
Expand All @@ -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.
"""
...

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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]]
Expand Down Expand Up @@ -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
"""

Expand Down
33 changes: 19 additions & 14 deletions src/neo4j/_sync/auth_management.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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::

Expand All @@ -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::

Expand All @@ -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

Expand All @@ -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::
Expand All @@ -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::

Expand Down Expand Up @@ -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
Expand Down