Skip to content

Commit

Permalink
Stabilize re-auth feature from preview
Browse files Browse the repository at this point in the history
  • Loading branch information
@robsdedude
robsdedude committed Oct 24, 2023
1 parent 222b107 commit e7f75ea
Show file tree
Hide file tree
Showing 22 changed files with 114 additions and 225 deletions.
18 changes: 7 additions & 11 deletions docs/source/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -280,11 +280,6 @@ Closing a driver will immediately shut down all connections in the pool.

By default, the driver configuration is used.

**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

See also the Session config :ref:`session-auth-ref`.
:type auth_: typing.Tuple[typing.Any, typing.Any] | Auth | None
:param result_transformer_:
Expand Down Expand Up @@ -374,9 +369,12 @@ Closing a driver will immediately shut down all connections in the pool.

.. versionchanged:: 5.8

* Added the ``auth_`` parameter.
* Added ``auth_`` parameter in preview.
* Stabilized from experimental.

.. versionchanged:: 5.14
Stabilized ``auth_`` parameter from preview.


.. _driver-configuration-ref:

Expand Down Expand Up @@ -1044,7 +1042,7 @@ See :class:`.BookmarkManager` for more information.

.. versionadded:: 5.0

.. versionchanged:: 5.8 stabilized from experimental
.. versionchanged:: 5.8 Stabilized from experimental.


.. _session-auth-ref:
Expand All @@ -1060,15 +1058,13 @@ It is not possible to overwrite the authentication information for the session w
i.e., downgrade the authentication at session level.
Instead, you should create a driver with no authentication and upgrade the authentication at session level as needed.

**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

:Type: :data:`None`, :class:`.Auth` or ``(user, password)``-tuple
:Default: :data:`None` - use the authentication information provided during driver creation.

.. versionadded:: 5.8

.. versionchanged:: 5.14 Stabilized from preview.


.. _session-notifications-min-severity-ref:

Expand Down
12 changes: 5 additions & 7 deletions docs/source/async_api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -267,11 +267,6 @@ Closing a driver will immediately shut down all connections in the pool.

By default, the driver configuration is used.

**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

See also the Session config :ref:`session-auth-ref`.
:type auth_: typing.Tuple[typing.Any, typing.Any] | Auth | None
:param result_transformer_:
Expand Down Expand Up @@ -361,9 +356,12 @@ Closing a driver will immediately shut down all connections in the pool.

.. versionchanged:: 5.8

* Added the ``auth_`` parameter.
* Added ``auth_`` parameter in preview.
* Stabilized from experimental.

.. versionchanged:: 5.14
Stabilized ``auth_`` parameter from preview.


.. _async-driver-configuration-ref:

Expand Down Expand Up @@ -651,7 +649,7 @@ See :class:`BookmarkManager` for more information.
:Type: :data:`None`, :class:`BookmarkManager`, or :class:`AsyncBookmarkManager`
:Default: :data:`None`

.. versionchanged:: 5.8 stabilized from experimental
.. versionchanged:: 5.8 Stabilized from experimental.



Expand Down
4 changes: 2 additions & 2 deletions src/neo4j/_api.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,8 +229,8 @@ class RoutingControl(str, Enum):
.. versionchanged:: 5.8
* renamed ``READERS`` to ``READ`` and ``WRITERS`` to ``WRITE``
* stabilized from experimental
* Renamed ``READERS`` to ``READ`` and ``WRITERS`` to ``WRITE``.
* Stabilized from experimental.
"""
READ = "r"
WRITE = "w"
Expand Down
18 changes: 10 additions & 8 deletions src/neo4j/_async/auth_management.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@
expiring_auth_has_expired,
ExpiringAuth,
)
from .._meta import preview


if t.TYPE_CHECKING:
Expand Down Expand Up @@ -105,20 +104,17 @@ async def handle_security_exception(
class AsyncAuthManagers:
"""A collection of :class:`.AsyncAuthManager` factories.
**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.8
.. versionchanged:: 5.12
* Method ``expiration_based()`` was renamed to :meth:`bearer`.
* Added :meth:`basic`.
.. versionchanged:: 5.14 Stabilized from preview.
"""

@staticmethod
@preview("Auth managers are a preview feature.")
def static(auth: _TAuth) -> AsyncAuthManager:
"""Create a static auth manager.
Expand Down Expand Up @@ -146,11 +142,14 @@ def static(auth: _TAuth) -> AsyncAuthManager:
:returns:
An instance of an implementation of :class:`.AsyncAuthManager` that
always returns the same auth.
.. versionadded:: 5.8
.. versionchanged:: 5.14 Stabilized from preview.
"""
return AsyncStaticAuthManager(auth)

@staticmethod
@preview("Auth managers are a preview feature.")
def basic(
provider: t.Callable[[], t.Awaitable[_TAuth]]
) -> AsyncAuthManager:
Expand Down Expand Up @@ -203,6 +202,8 @@ async def auth_provider():
flagged it as expired).
.. versionadded:: 5.12
.. versionchanged:: 5.14 Stabilized from preview.
"""
handled_codes = frozenset(("Neo.ClientError.Security.Unauthorized",))

Expand All @@ -214,7 +215,6 @@ async def wrapped_provider() -> ExpiringAuth:
return AsyncNeo4jAuthTokenManager(wrapped_provider, handled_codes)

@staticmethod
@preview("Auth managers are a preview feature.")
def bearer(
provider: t.Callable[[], t.Awaitable[ExpiringAuth]]
) -> AsyncAuthManager:
Expand Down Expand Up @@ -277,6 +277,8 @@ async def auth_provider():
expired).
.. versionadded:: 5.12
.. versionchanged:: 5.14 Stabilized from preview.
"""
handled_codes = frozenset((
"Neo.ClientError.Security.TokenExpired",
Expand Down
43 changes: 14 additions & 29 deletions src/neo4j/_async/driver.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,6 @@
from .._meta import (
deprecation_warn,
experimental_warn,
preview,
preview_warn,
unclosed_resource_warn,
)
from .._work import EagerResult
Expand Down Expand Up @@ -193,10 +191,7 @@ def driver(
driver_type, security_type, parsed = parse_neo4j_uri(uri)

if not isinstance(auth, AsyncAuthManager):
auth = AsyncAuthManagers.static._without_warning(auth)
else:
preview_warn("Auth managers are a preview feature.",
stack_level=2)
auth = AsyncAuthManagers.static(auth)
config["auth"] = auth

# TODO: 6.0 - remove "trust" config option
Expand Down Expand Up @@ -357,7 +352,7 @@ def bookmark_manager(
* ``bookmarks_consumer`` no longer receives the database name as
an argument.
.. versionchanged:: 5.8 stabilized from experimental
.. versionchanged:: 5.8 Stabilized from experimental.
"""
return AsyncNeo4jBookmarkManager(
initial_bookmarks=initial_bookmarks,
Expand Down Expand Up @@ -551,17 +546,14 @@ def session(self, **config) -> AsyncSession:
def _session(self, session_config) -> AsyncSession:
return AsyncSession(self._pool, session_config)

def _read_session_config(self, config_kwargs, preview_check=True):
config = self._prepare_session_config(preview_check, config_kwargs)
def _read_session_config(self, config_kwargs):
config = self._prepare_session_config(config_kwargs)
session_config = SessionConfig(self._default_workspace_config,
config)
return session_config

@classmethod
def _prepare_session_config(cls, preview_check, config_kwargs):
if preview_check and "auth" in config_kwargs:
preview_warn("User switching is a preview feature.",
stack_level=5)
def _prepare_session_config(cls, config_kwargs):
_normalize_notifications_config(config_kwargs)
return config_kwargs

Expand Down Expand Up @@ -745,11 +737,6 @@ async def example(driver: neo4j.AsyncDriver) -> int:
By default, the driver configuration is used.
**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
See also the Session config :ref:`session-auth-ref`.
:type auth_: typing.Tuple[typing.Any, typing.Any] | Auth | None
:param result_transformer_:
Expand Down Expand Up @@ -839,8 +826,11 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
.. versionchanged:: 5.8
* Added the ``auth_`` parameter.
* Added ``auth_`` parameter in preview.
* Stabilized from experimental.
.. versionchanged:: 5.14
Stabilized ``auth_`` parameter from preview.
"""
self._check_state()
invalid_kwargs = [k for k in kwargs if
Expand All @@ -865,8 +855,7 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
"impersonated_user": impersonated_user_,
"bookmark_manager": bookmark_manager_,
"auth": auth_,
},
preview_check=False
}
)
session = self._session(session_config)
async with session:
Expand Down Expand Up @@ -1072,7 +1061,7 @@ async def supports_multi_db(self) -> bool:
driver feature.
"""
self._check_state()
session_config = self._read_session_config({}, preview_check=False)
session_config = self._read_session_config({})
async with self._session(session_config) as session:
await session._connect(READ_ACCESS)
assert session._connection
Expand Down Expand Up @@ -1106,7 +1095,6 @@ async def verify_authentication(

else:

@preview("User switching is a preview feature.")
async def verify_authentication(
self,
auth: t.Union[Auth, t.Tuple[t.Any, t.Any], None] = None,
Expand Down Expand Up @@ -1140,12 +1128,9 @@ async def verify_authentication(
Use the exception to further understand the cause of the
connectivity problem.
**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.8
.. versionchanged:: 5.14 Stabilized from experimental.
"""
self._check_state()
if config:
Expand Down Expand Up @@ -1190,7 +1175,7 @@ async def supports_session_auth(self) -> bool:
.. versionadded:: 5.8
"""
self._check_state()
session_config = self._read_session_config({}, preview_check=False)
session_config = self._read_session_config({})
async with self._session(session_config) as session:
await session._connect(READ_ACCESS)
assert session._connection
Expand Down
2 changes: 1 addition & 1 deletion src/neo4j/_async/work/result.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -642,7 +642,7 @@ async def to_eager_result(self) -> EagerResult:
.. versionadded:: 5.5
.. versionchanged:: 5.8 stabilized from experimental
.. versionchanged:: 5.8 Stabilized from experimental.
"""

await self._buffer_all()
Expand Down
29 changes: 9 additions & 20 deletions src/neo4j/_auth_management.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,13 @@
import typing as t
from dataclasses import dataclass

from ._meta import preview
from .exceptions import Neo4jError


if t.TYPE_CHECKING:
from .api import _TAuth


@preview("Auth managers are a preview feature.")
@dataclass
class ExpiringAuth:
"""Represents potentially expiring authentication information.
Expand All @@ -46,21 +44,20 @@ class ExpiringAuth:
If :data:`None`, the authentication information is considered to not
expire until the server explicitly indicates so.
**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
.. seealso::
:meth:`.AuthManagers.expiration_based`,
:meth:`.AsyncAuthManagers.expiration_based`
.. versionadded:: 5.8
.. versionchanged:: 5.9
Removed parameter and attribute ``expires_in`` (relative expiration
time). Replaced with ``expires_at`` (absolute expiration time).
:meth:`.expires_in` can be used to create an :class:`.ExpiringAuth`
with a relative expiration time.
* Removed parameter and attribute ``expires_in`` (relative expiration
time). Replaced with ``expires_at`` (absolute expiration time).
* :meth:`.expires_in` can be used to create an :class:`.ExpiringAuth`
with a relative expiration time.
.. versionchanged:: 5.14 Stabilized from preview.
"""
auth: _TAuth
expires_at: t.Optional[float] = None
Expand Down Expand Up @@ -116,19 +113,15 @@ class AuthManager(metaclass=abc.ABCMeta):
You may use session-level authentication for such use-cases
:ref:`session-auth-ref`.
**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
.. seealso:: :class:`.AuthManagers`
.. versionadded:: 5.8
.. 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
:meth:`handle_security_exception`. The new method is called when the
server returns any `Neo.ClientError.Security.*` error. It's signature
differs in that it additionally received the error returned by the
differs in that it additionally receives the error returned by the
server and returns a boolean indicating whether the error was handled.
"""

Expand Down Expand Up @@ -178,10 +171,6 @@ def handle_security_exception(
class AsyncAuthManager(metaclass=abc.ABCMeta):
"""Async version of :class:`.AuthManager`.
**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
.. seealso:: :class:`.AuthManager`
.. versionadded:: 5.8
Expand Down
Loading

0 comments on commit e7f75ea

Please sign in to comment.