ADR 022: GQL compliant notifications

docs/source/api.rst

@@ -686,6 +686,9 @@ Set the minimum severity for notifications the server should send to the client.
 Disabling severities allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced through :attr:`.ResultSummary.gql_status_objects`:
+For GQL-aware servers, notifications are a subset of GqlStatusObjects.
+See also :attr:`.GqlSatusObject.is_notification`.
 
 :data:`None` will apply the server's default setting.
 
@@ -706,13 +709,17 @@ Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`
 
 ``notifications_disabled_categories``
 -------------------------------------
-Set categories of notifications the server should not send to the client.
+Set categories/classifications of notifications the server should not send to the client.
 Disabling categories allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced (alongside other status objects) through :attr:`.ResultSummary.gql_status_objects`:
+See also :attr:`.GqlSatusObject.is_notification`.
 
 :data:`None` will apply the server's default setting.
 
+If specified together with :ref:`driver-notifications-disabled-classifications-ref`, the settings will be merged.
+
 .. Note::
     If configured, the server or all servers of the cluster need to support notifications filtering
     (server version 5.7 and newer).
@@ -726,6 +733,27 @@ Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`
 .. seealso:: :class:`.NotificationDisabledCategory`, session config :ref:`session-notifications-disabled-categories-ref`
 
 
+.. _driver-notifications-disabled-classifications-ref:
+
+``notifications_disabled_classifications``
+------------------------------------------
+Identical to :ref:`driver-notifications-disabled-categories-ref`.
+
+This alias is provided for a consistent naming with :attr:`.GqlStatusObject.classification`.
+
+**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`, :term:`iterable` of :class:`.NotificationDisabledClassification` and/or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.21
+
+.. seealso:: :class:`.NotificationDisabledClassification`, session config :ref:`session-notifications-disabled-classifications-ref`
+
+
 .. _driver-warn-notification-severity-ref:
 
 ``warn_notification_severity``
@@ -1159,11 +1187,14 @@ Set the minimum severity for notifications the server should send to the client.
 Disabling severities allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced (alongside other status objects) through :attr:`.ResultSummary.gql_status_objects`:
+See also :attr:`.GqlSatusObject.is_notification`.
 
 :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.
+    If configured, the server or all servers of the cluster need to support notifications filtering
+    (server version 5.7 and newer).
     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`
@@ -1182,11 +1213,16 @@ Set categories of notifications the server should not send to the client.
 Disabling categories allows the server to skip analysis for those, which can speed up query execution.
 
 Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`.ResultSummary.summary_notifications`.
+Further, they are surfaced (alongside other status objects) through :attr:`.ResultSummary.gql_status_objects`:
+See also :attr:`.GqlSatusObject.is_notification`.
 
-:data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-min-severity-ref`).
+:data:`None` will apply the driver's configuration setting (:ref:`driver-notifications-disabled-categories-ref`).
+
+If specified together with :ref:`session-notifications-disabled-classifications-ref`, the settings will be merged.
 
 .. Note::
-    If configured, the server or all servers of the cluster need to support notifications filtering.
+    If configured, the server or all servers of the cluster need to support notifications filtering
+    (server version 5.7 and newer).
     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`
@@ -1197,6 +1233,27 @@ Notifications are available via :attr:`.ResultSummary.notifications` and :attr:`
 .. seealso:: :class:`.NotificationDisabledCategory`
 
 
+.. _session-notifications-disabled-classifications-ref:
+
+``notifications_disabled_classifications``
+------------------------------------------
+Identical to :ref:`session-notifications-disabled-categories-ref`.
+
+This alias is provided for a consistent naming with :attr:`.GqlStatusObject.classification`.
+
+**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`, :term:`iterable` of :class:`.NotificationDisabledClassification` and/or :class:`str`
+:Default: :data:`None`
+
+.. versionadded:: 5.21
+
+.. seealso:: :class:`.NotificationDisabledClassification`
+
+
 
 ***********
 Transaction
@@ -1521,6 +1578,20 @@ ServerInfo
    :members:
 
 
+GqlStatusObject
+===============
+
+.. autoclass:: neo4j.GqlStatusObject()
+    :members:
+
+
+NotificationClassification
+--------------------------
+
+.. autoclass:: neo4j.NotificationClassification()
+    :members:
+
+
 SummaryNotification
 ===================
 
@@ -1542,11 +1613,26 @@ NotificationCategory
     :members:
 
 
+SummaryInputPosition
+--------------------
+
+.. autoclass:: neo4j.SummaryInputPosition()
+    :members:
+
+
 SummaryNotificationPosition
 ---------------------------
 
-.. autoclass:: neo4j.SummaryNotificationPosition()
-    :members:
+.. data:: neo4j.SummaryNotificationPosition
+    :annotation: = neo4j.SummaryInputPosition
+
+    Deprecated alias for :class:`.SummaryInputPosition`.
+
+    .. versionadded:: 5.7
+
+    .. versionchanged:: 5.21
+        Deprecated in favor of :class:`.SummaryInputPosition`.
+
 
 
 
@@ -1869,6 +1955,9 @@ Constants, Enums, Helpers
     :show-inheritance:
     :members:
 
+.. autoclass:: neo4j.NotificationDisabledClassification()
+    :members:
+
 .. autoclass:: neo4j.RoutingControl()
     :show-inheritance:
     :members:

src/neo4j/__init__.py

@@ -14,11 +14,13 @@
 # limitations under the License.
 
 
+import typing as _t
 from logging import getLogger as _getLogger
 
 from ._api import (
     NotificationCategory,
     NotificationDisabledCategory,
+    NotificationDisabledClassification as _NotificationDisabledClassification,
     NotificationMinimumSeverity,
     NotificationSeverity,
     RoutingControl,
@@ -49,6 +51,7 @@
     deprecation_warn as _deprecation_warn,
     ExperimentalWarning,
     get_user_agent,
+    preview_warn as _preview_warn,
     PreviewWarning,
     version as __version__,
 )
@@ -67,13 +70,25 @@
 )
 from ._work import (
     EagerResult,
+    GqlStatusObject as _GqlStatusObject,
+    NotificationClassification as _NotificationClassification,
     Query,
     ResultSummary,
     SummaryCounters,
+    SummaryInputPosition,
     SummaryNotification,
-    SummaryNotificationPosition,
     unit_of_work,
 )
+
+
+if _t.TYPE_CHECKING:
+    from ._api import NotificationDisabledClassification
+    from ._work import (
+        GqlStatusObject,
+        NotificationClassification,
+        SummaryInputPosition as SummaryNotificationPosition
+    )
+
 from .addressing import (
     Address,
     IPv4Address,
@@ -122,20 +137,23 @@
     "Config",
     "custom_auth",
     "DEFAULT_DATABASE",
-    "NotificationDisabledCategory",
     "Driver",
     "EagerResult",
     "ExperimentalWarning",
     "get_user_agent",
+    "GqlStatusObject",
     "GraphDatabase",
     "IPv4Address",
     "IPv6Address",
     "kerberos_auth",
     "log",
     "ManagedTransaction",
-    "NotificationMinimumSeverity",
     "Neo4jDriver",
     "NotificationCategory",
+    "NotificationClassification",
+    "NotificationDisabledCategory",
+    "NotificationDisabledClassification",
+    "NotificationMinimumSeverity",
     "NotificationSeverity",
     "PoolConfig",
     "PreviewWarning",
@@ -149,6 +167,7 @@
     "Session",
     "SessionConfig",
     "SummaryCounters",
+    "SummaryInputPosition",
     "SummaryNotification",
     "SummaryNotificationPosition",
     "Transaction",
@@ -173,12 +192,30 @@ def __getattr__(name):
         "log", "Config", "PoolConfig", "SessionConfig", "WorkspaceConfig"
     ):
         _deprecation_warn(
-            "Importing {} from neo4j is deprecated without replacement. It's "
-            "internal and will be removed in a future version."
+            "Importing {} from neo4j is deprecated without replacement. "
+            "It's internal and will be removed in a future version."
             .format(name),
             stack_level=2
         )
         return globals()[f"_{name}"]
+    if name == "SummaryNotificationPosition":
+        _deprecation_warn(
+            "SummaryNotificationPosition is deprecated. "
+            "Use SummaryInputPosition instead.",
+            stack_level=2
+        )
+        return SummaryInputPosition
+    if name in (
+        "NotificationClassification",
+        "GqlStatusObject",
+        "NotificationDisabledClassification",
+    ):
+        _preview_warn(
+            f"{name} is part of GQLSTATUS support, "
+            "which is a preview feature.",
+            stack_level=2
+        )
+        return globals()[f"_{name}"]
     raise AttributeError(f"module {__name__} has no attribute {name}")