Notifications api (#847)

* Make `neo4j.work` internal

* ADR 009: Implement notification filters (Bolt 5.2)

* Add tests to make sure credentials aren't logged

* Add basic Bolt 5.1 (LOGON after HELLO) support

Author: robsdedude

CHANGELOG.md

@@ -3,6 +3,7 @@
 See also https://github.com/neo4j/neo4j-python-driver/wiki for more details.
 
 ## NEXT RELEASE
+- Deprecated importing from `neo4j.work` and its submodules. Everything should be imported directly from `neo4j` instead.
 - ...
 
 

bin/make-unasync

@@ -223,6 +223,7 @@ def apply_unasync(files):
         "assert_awaited_once": "assert_called_once",
         "assert_awaited_once_with": "assert_called_once_with",
         "await_count": "call_count",
+        "AsyncMock": "MagicMock",
     }
     additional_testkit_backend_replacements = {}
     rules = [

docs/source/api.rst

@@ -377,6 +377,8 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`ssl-context-ref`
 + :ref:`trusted-certificates-ref`
 + :ref:`user-agent-ref`
++ :ref:`driver-notifications-min-severity-ref`
++ :ref:`driver-notifications-disabled-categories-ref`
 
 
 .. _connection-acquisition-timeout-ref:
@@ -596,6 +598,49 @@ Specify the client agent name.
 :Default: *The Python Driver will generate a user agent name.*
 
 
+.. _driver-notifications-min-severity-ref:
+
+``notifications_min_severity``
+------------------------------
+Set the minimum severity for notifications the server should send to the client.
+
+Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+
+:data:`None` will apply the server's default setting.
+
+.. Note::
+    If configured, the server or all servers of the cluster need to support notifications filtering.
+    Otherwise, the driver will raise a :exc:`.ConfigurationError` as soon as it encounters a server that does not.
+
+:Type: :data:`None`, :class:`.NotificationMinimumSeverity`, or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.7
+
+.. seealso:: :class:`.NotificationMinimumSeverity`, session config :ref:`session-notifications-min-severity-ref`
+
+
+.. _driver-notifications-disabled-categories-ref:
+
+``notifications_disabled_categories``
+-------------------------------------
+Set categories of notifications the server should not send to the client.
+
+Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+
+:data:`None` will apply the server's default setting.
+
+.. Note::
+    If configured, the server or all servers of the cluster need to support notifications filtering.
+    Otherwise, the driver will raise a :exc:`.ConfigurationError` as soon as it encounters a server that does not.
+
+:Type: :data:`None`, :term:`iterable` of :class:`.NotificationDisabledCategory` and/or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.7
+
+.. seealso:: :class:`.NotificationDisabledCategory`, session config :ref:`session-notifications-disabled-categories-ref`
+
 
 Driver Object Lifetime
 ======================
@@ -759,6 +804,8 @@ To construct a :class:`neo4j.Session` use the :meth:`neo4j.Driver.session` metho
 + :ref:`default-access-mode-ref`
 + :ref:`fetch-size-ref`
 + :ref:`bookmark-manager-ref`
++ :ref:`session-notifications-min-severity-ref`
++ :ref:`session-notifications-disabled-categories-ref`
 
 
 .. _bookmarks-ref:
@@ -858,7 +905,7 @@ context of the impersonated user. For this, the user for which the
 
 .. Note::
 
-    The server or all servers of the cluster need to support impersonation.
+    If configured, the server or all servers of the cluster need to support impersonation.
     Otherwise, the driver will raise :exc:`.ConfigurationError`
     as soon as it encounters a server that does not.
 
@@ -952,6 +999,49 @@ See :class:`.BookmarkManager` for more information.
 It might be changed or removed any time even without prior notice.
 
 
+.. _session-notifications-min-severity-ref:
+
+``notifications_min_severity``
+------------------------------
+Set the minimum severity for notifications the server should send to the client.
+
+Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+
+:data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-min-severity-ref`).
+
+.. Note::
+    If configured, the server or all servers of the cluster need to support notifications filtering.
+    Otherwise, the driver will raise a :exc:`.ConfigurationError` as soon as it encounters a server that does not.
+
+:Type: :data:`None`, :class:`.NotificationMinimumSeverity`, or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.7
+
+.. seealso:: :class:`.NotificationMinimumSeverity`
+
+
+.. _session-notifications-disabled-categories-ref:
+
+``notifications_disabled_categories``
+-------------------------------------
+Set categories of notifications the server should not send to the client.
+
+Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+
+:data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-min-severity-ref`).
+
+.. Note::
+    If configured, the server or all servers of the cluster need to support notifications filtering.
+    Otherwise, the driver will raise a :exc:`.ConfigurationError` as soon as it encounters a server that does not.
+
+:Type: :data:`None`, :term:`iterable` of :class:`.NotificationDisabledCategory` and/or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.7
+
+.. seealso:: :class:`.NotificationDisabledCategory`
+
 
 
 ***********
@@ -1288,6 +1378,34 @@ ServerInfo
    :members:
 
 
+SummaryNotification
+===================
+
+.. autoclass:: neo4j.SummaryNotification()
+    :members:
+
+
+NotificationSeverity
+--------------------
+
+.. autoclass:: neo4j.NotificationSeverity()
+    :members:
+
+
+NotificationCategory
+--------------------
+
+.. autoclass:: neo4j.NotificationCategory()
+    :members:
+
+
+SummaryNotificationPosition
+---------------------------
+
+.. autoclass:: neo4j.SummaryNotificationPosition()
+    :members:
+
+
 
 ***************
 Core Data Types
@@ -1583,6 +1701,14 @@ BookmarkManager
 Constants, Enums, Helpers
 *************************
 
+.. autoclass:: neo4j.NotificationMinimumSeverity
+    :show-inheritance:
+    :members:
+
+.. autoclass:: neo4j.NotificationDisabledCategory
+    :show-inheritance:
+    :members:
+
 .. autoclass:: neo4j.RoutingControl
     :show-inheritance:
     :members:

src/neo4j/__init__.py

@@ -18,7 +18,13 @@
 
 from logging import getLogger as _getLogger
 
-from ._api import RoutingControl
+from ._api import (
+    NotificationCategory,
+    NotificationDisabledCategory,
+    NotificationMinimumSeverity,
+    NotificationSeverity,
+    RoutingControl,
+)
 from ._async.driver import (
     AsyncBoltDriver,
     AsyncDriver,
@@ -60,7 +66,15 @@
     Session,
     Transaction,
 )
-from ._work import EagerResult
+from ._work import (
+    EagerResult,
+    Query,
+    ResultSummary,
+    SummaryCounters,
+    SummaryNotification,
+    SummaryNotificationPosition,
+    unit_of_work,
+)
 from .addressing import (
     Address,
     IPv4Address,
@@ -86,12 +100,6 @@
     Version,
     WRITE_ACCESS,
 )
-from .work import (
-    Query,
-    ResultSummary,
-    SummaryCounters,
-    unit_of_work,
-)
 
 
 __all__ = [
@@ -115,6 +123,7 @@
     "Config",
     "custom_auth",
     "DEFAULT_DATABASE",
+    "NotificationDisabledCategory",
     "Driver",
     "EagerResult",
     "ExperimentalWarning",
@@ -125,7 +134,11 @@
     "kerberos_auth",
     "log",
     "ManagedTransaction",
+    "NotificationMinimumSeverity",
     "Neo4jDriver",
+    "NotificationCategory",
+    "NotificationFilter",
+    "NotificationSeverity",
     "PoolConfig",
     "Query",
     "READ_ACCESS",
@@ -137,6 +150,8 @@
     "Session",
     "SessionConfig",
     "SummaryCounters",
+    "SummaryNotification",
+    "SummaryNotificationPosition",
     "Transaction",
     "TRUST_ALL_CERTIFICATES",
     "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES",