Mature execute_query API

 * Renaming `neo4j.RoutingControl.WRITERS` to `WRITE` and `READERS` to `READ`.
 * Renaming `driver.query_bookmark_manager()` to
   `execute_query_bookmark_manager()`.
 * Remove experimental tag from execute_query and its related APIs
   * `driver.execute_query`
   * `driver.execute_query_bookmark_manager`
   * `AsyncBookmarkManager`, `BookmarkManager`, the corresponding config option
     (session's `bookmark_manager`) and factory method
     (`driver.bookmark_manager()`)
   * `RoutingControl` enum
   * `EagerResult` and `result.to_eager_result()`

Author: robsdedude

CHANGELOG.md

@@ -3,7 +3,8 @@
 See also https://github.com/neo4j/neo4j-python-driver/wiki for more details.
 
 ## NEXT RELEASE
-- ...
+- Renamed experimental `neo4j.RoutingControl.READERS` to `READ` and `WRITERS` to `WRITE`.
+- Renamed experimental `driver.query_bookmark_manager` to `execute_query_bookmark_manager`.
 
 
 ## Version 5.7

docs/source/api.rst

@@ -156,7 +156,7 @@ Closing a driver will immediately shut down all connections in the pool.
     :members: session, query_bookmark_manager, encrypted, close,
               verify_connectivity, get_server_info
 
-    .. method:: execute_query(query, parameters_=None,routing_=neo4j.RoutingControl.WRITERS, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=Result.to_eager_result, **kwargs)
+    .. method:: execute_query(query, parameters_=None,routing_=neo4j.RoutingControl.WRITE, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=Result.to_eager_result, **kwargs)
 
         Execute a query in a transaction function and return all results.
 
@@ -185,9 +185,9 @@ Closing a driver will immediately shut down all connections in the pool.
                     impersonated_user=impersonated_user_,
                     bookmark_manager=bookmark_manager_,
                 ) as session:
-                    if routing_ == RoutingControl.WRITERS:
+                    if routing_ == RoutingControl.WRITE:
                         return session.execute_write(work)
-                    elif routing_ == RoutingControl.READERS:
+                    elif routing_ == RoutingControl.READ:
                         return session.execute_read(work)
 
         Usage example::
@@ -202,7 +202,7 @@ Closing a driver will immediately shut down all connections in the pool.
                 records, summary, keys = driver.execute_query(
                     "MATCH (p:Person {age: $age}) RETURN p.name",
                     {"age": 42},
-                    routing_=neo4j.RoutingControl.READERS,  # or just "r"
+                    routing_=neo4j.RoutingControl.READ,  # or just "r"
                     database_="neo4j",
                 )
                 assert keys == ["p.name"]  # not needed, just for illustration
@@ -223,7 +223,7 @@ Closing a driver will immediately shut down all connections in the pool.
                     "SET p.nickname = 'My dear' "
                     "RETURN count(*)",
                     # optional routing parameter, as write is default
-                    # routing_=neo4j.RoutingControl.WRITERS,  # or just "w",
+                    # routing_=neo4j.RoutingControl.WRITE,  # or just "w",
                     database_="neo4j",
                     result_transformer_=neo4j.Result.single,
                     age=15,
@@ -348,15 +348,10 @@ Closing a driver will immediately shut down all connections in the pool.
         :returns: the result of the ``result_transformer``
         :rtype: T
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
-        It might be changed or removed any time even without prior notice.
-
-        We are looking for feedback on this feature. Please let us know what
-        you think about it here:
-        https://github.com/neo4j/neo4j-python-driver/discussions/896
-
         .. versionadded:: 5.5
 
+        .. versionchanged:: 5.8 stabilized from experimental
+
 
 .. _driver-configuration-ref:
 
@@ -995,8 +990,7 @@ See :class:`.BookmarkManager` for more information.
 
 .. versionadded:: 5.0
 
-**This is experimental.** (See :ref:`filter-warnings-ref`)
-It might be changed or removed any time even without prior notice.
+.. versionchanged:: 5.8 stabilized from experimental
 
 
 .. _session-notifications-min-severity-ref:

docs/source/async_api.rst

@@ -138,7 +138,7 @@ Closing a driver will immediately shut down all connections in the pool.
     :members: session, query_bookmark_manager, encrypted, close,
               verify_connectivity, get_server_info
 
-    .. method:: execute_query(query, parameters_=None, routing_=neo4j.RoutingControl.WRITERS, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=AsyncResult.to_eager_result, **kwargs)
+    .. method:: execute_query(query, parameters_=None, routing_=neo4j.RoutingControl.WRITE, database_=None, impersonated_user_=None, bookmark_manager_=self.query_bookmark_manager, result_transformer_=AsyncResult.to_eager_result, **kwargs)
         :async:
 
         Execute a query in a transaction function and return all results.
@@ -168,9 +168,9 @@ Closing a driver will immediately shut down all connections in the pool.
                     impersonated_user=impersonated_user_,
                     bookmark_manager=bookmark_manager_,
                 ) as session:
-                    if routing_ == RoutingControl.WRITERS:
+                    if routing_ == RoutingControl.WRITE:
                         return await session.execute_write(work)
-                    elif routing_ == RoutingControl.READERS:
+                    elif routing_ == RoutingControl.READ:
                         return await session.execute_read(work)
 
         Usage example::
@@ -185,7 +185,7 @@ Closing a driver will immediately shut down all connections in the pool.
                 records, summary, keys = await driver.execute_query(
                     "MATCH (p:Person {age: $age}) RETURN p.name",
                     {"age": 42},
-                    routing_=neo4j.RoutingControl.READERS,  # or just "r"
+                    routing_=neo4j.RoutingControl.READ,  # or just "r"
                     database_="neo4j",
                 )
                 assert keys == ["p.name"]  # not needed, just for illustration
@@ -206,7 +206,7 @@ Closing a driver will immediately shut down all connections in the pool.
                     "SET p.nickname = 'My dear' "
                     "RETURN count(*)",
                     # optional routing parameter, as write is default
-                    # routing_=neo4j.RoutingControl.WRITERS,  # or just "w",
+                    # routing_=neo4j.RoutingControl.WRITE,  # or just "w",
                     database_="neo4j",
                     result_transformer_=neo4j.AsyncResult.single,
                 )
@@ -329,15 +329,10 @@ Closing a driver will immediately shut down all connections in the pool.
         :returns: the result of the ``result_transformer``
         :rtype: T
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
-        It might be changed or removed any time even without prior notice.
-
-        We are looking for feedback on this feature. Please let us know what
-        you think about it here:
-        https://github.com/neo4j/neo4j-python-driver/discussions/896
-
         .. versionadded:: 5.5
 
+        .. versionchanged:: 5.8 stabilized from experimental
+
 
 .. _async-driver-configuration-ref:
 
@@ -622,8 +617,7 @@ See :class:`BookmarkManager` for more information.
 :Type: :data:`None`, :class:`BookmarkManager`, or :class:`AsyncBookmarkManager`
 :Default: :data:`None`
 
-**This is experimental.** (See :ref:`filter-warnings-ref`)
-It might be changed or removed any time even without prior notice.
+.. versionchanged:: 5.8 stabilized from experimental
 
 
 

src/neo4j/_api.py

@@ -208,21 +208,22 @@ class RoutingControl(str, Enum):
     Inherits from :class:`str` and :class:`Enum`. Every driver API accepting a
     :class:`.RoutingControl` value will also accept a string
 
-        >>> RoutingControl.READERS == "r"
+        >>> RoutingControl.READ == "r"
         True
-        >>> RoutingControl.WRITERS == "w"
+        >>> RoutingControl.WRITE == "w"
         True
 
-    **This is experimental.**
-    It might be changed or removed any time even without prior notice.
-
     .. seealso::
         :attr:`.AsyncDriver.execute_query`, :attr:`.Driver.execute_query`
 
     .. versionadded:: 5.5
+
+    .. versionchanged:: 5.8
+        * renamed ``READERS`` to ``READ`` and ``WRITERS`` to ``WRITE``
+        * stabilized from experimental
     """
-    READERS = "r"
-    WRITERS = "w"
+    READ = "r"
+    WRITE = "w"
 
 
 if t.TYPE_CHECKING:

src/neo4j/_async/driver.py

@@ -47,7 +47,6 @@
     deprecation_warn,
     experimental,
     experimental_warn,
-    ExperimentalWarning,
     unclosed_resource_warn,
 )
 from .._work import EagerResult
@@ -261,10 +260,6 @@ def driver(
                                     routing_context=routing_context, **config)
 
     @classmethod
-    @experimental(
-        "The bookmark manager feature is experimental. "
-        "It might be changed or removed any time even without prior notice."
-    )
     def bookmark_manager(
         cls,
         initial_bookmarks: t.Union[None, Bookmarks, t.Iterable[str]] = None,
@@ -325,9 +320,6 @@ def bookmark_manager(
 
         :returns: A default implementation of :class:`AsyncBookmarkManager`.
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
-        It might be changed or removed any time even without prior notice.
-
         .. versionadded:: 5.0
 
         .. versionchanged:: 5.3
@@ -341,6 +333,8 @@ def bookmark_manager(
               an argument.
             * ``bookmarks_consumer`` no longer receives the database name as
               an argument.
+
+        .. versionchanged:: 5.8 stabilized from experimental
         """
         return AsyncNeo4jBookmarkManager(
             initial_bookmarks=initial_bookmarks,
@@ -448,12 +442,7 @@ def __init__(self, pool, default_workspace_config):
         assert default_workspace_config is not None
         self._pool = pool
         self._default_workspace_config = default_workspace_config
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore",
-                                    message=r".*\bbookmark manager\b.*",
-                                    category=ExperimentalWarning)
-            self._query_bookmark_manager = \
-                AsyncGraphDatabase.bookmark_manager()
+        self._query_bookmark_manager = AsyncGraphDatabase.bookmark_manager()
 
     async def __aenter__(self) -> AsyncDriver:
         return self
@@ -543,7 +532,7 @@ async def execute_query(
         self,
         query_: str,
         parameters_: t.Optional[t.Dict[str, t.Any]] = None,
-        routing_: T_RoutingControl = RoutingControl.WRITERS,
+        routing_: T_RoutingControl = RoutingControl.WRITE,
         database_: t.Optional[str] = None,
         impersonated_user_: t.Optional[str] = None,
         bookmark_manager_: t.Union[
@@ -561,7 +550,7 @@ async def execute_query(
         self,
         query_: str,
         parameters_: t.Optional[t.Dict[str, t.Any]] = None,
-        routing_: T_RoutingControl = RoutingControl.WRITERS,
+        routing_: T_RoutingControl = RoutingControl.WRITE,
         database_: t.Optional[str] = None,
         impersonated_user_: t.Optional[str] = None,
         bookmark_manager_: t.Union[
@@ -574,15 +563,11 @@ async def execute_query(
     ) -> _T:
         ...
 
-    @experimental(
-        "Driver.execute_query is experimental. "
-        "It might be changed or removed any time even without prior notice."
-    )
     async def execute_query(
         self,
         query_: str,
         parameters_: t.Optional[t.Dict[str, t.Any]] = None,
-        routing_: T_RoutingControl = RoutingControl.WRITERS,
+        routing_: T_RoutingControl = RoutingControl.WRITE,
         database_: t.Optional[str] = None,
         impersonated_user_: t.Optional[str] = None,
         bookmark_manager_: t.Union[
@@ -621,9 +606,9 @@ async def work(tx):
                     impersonated_user=impersonated_user_,
                     bookmark_manager=bookmark_manager_,
                 ) as session:
-                    if routing_ == RoutingControl.WRITERS:
+                    if routing_ == RoutingControl.WRITE:
                         return await session.execute_write(work)
-                    elif routing_ == RoutingControl.READERS:
+                    elif routing_ == RoutingControl.READ:
                         return await session.execute_read(work)
 
         Usage example::
@@ -638,7 +623,7 @@ async def example(driver: neo4j.AsyncDriver) -> List[str]:
                 records, summary, keys = await driver.execute_query(
                     "MATCH (p:Person {age: $age}) RETURN p.name",
                     {"age": 42},
-                    routing_=neo4j.RoutingControl.READERS,  # or just "r"
+                    routing_=neo4j.RoutingControl.READ,  # or just "r"
                     database_="neo4j",
                 )
                 assert keys == ["p.name"]  # not needed, just for illustration
@@ -659,7 +644,7 @@ async def example(driver: neo4j.AsyncDriver) -> int:
                     "SET p.nickname = 'My dear' "
                     "RETURN count(*)",
                     # optional routing parameter, as write is default
-                    # routing_=neo4j.RoutingControl.WRITERS,  # or just "w",
+                    # routing_=neo4j.RoutingControl.WRITE,  # or just "w",
                     database_="neo4j",
                     result_transformer_=neo4j.AsyncResult.single,
                 )
@@ -782,10 +767,9 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
         :returns: the result of the ``result_transformer``
         :rtype: T
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
-        It might be changed or removed any time even without prior notice.
-
         .. versionadded:: 5.5
+
+        .. versionchanged:: 5.8 stabilized from experimental
         """
         invalid_kwargs = [k for k in kwargs if
                           k[-2:-1] != "_" and k[-1:] == "_"]
@@ -803,17 +787,13 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
             bookmark_manager_ = self._query_bookmark_manager
         assert bookmark_manager_ is not _default
 
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore",
-                                    message=r".*\bbookmark_manager\b.*",
-                                    category=ExperimentalWarning)
-            session = self.session(database=database_,
-                                   impersonated_user=impersonated_user_,
-                                   bookmark_manager=bookmark_manager_)
+        session = self.session(database=database_,
+                               impersonated_user=impersonated_user_,
+                               bookmark_manager=bookmark_manager_)
         async with session:
-            if routing_ == RoutingControl.WRITERS:
+            if routing_ == RoutingControl.WRITE:
                 executor = session.execute_write
-            elif routing_ == RoutingControl.READERS:
+            elif routing_ == RoutingControl.READ:
                 executor = session.execute_read
             else:
                 raise ValueError("Invalid routing control value: %r"
@@ -823,11 +803,7 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record::
             )
 
     @property
-    @experimental(
-        "Driver.query_bookmark_manager is experimental. "
-        "It might be changed or removed any time even without prior notice."
-    )
-    def query_bookmark_manager(self) -> AsyncBookmarkManager:
+    def execute_query_bookmark_manager(self) -> AsyncBookmarkManager:
         """The driver's default query bookmark manager.
 
         This is the default :class:`AsyncBookmarkManager` used by
@@ -846,10 +822,12 @@ async def example(driver: neo4j.AsyncDriver) -> None:
                 # (i.e., can read what was written by <QUERY 2>)
                 await driver.execute_query("<QUERY 3>")
 
-        **This is experimental.** (See :ref:`filter-warnings-ref`)
-        It might be changed or removed any time even without prior notice.
-
         .. versionadded:: 5.5
+
+        .. versionchanged:: 5.8
+            * renamed from ``query_bookmark_manager`` to
+              ``execute_query_bookmark_manager``
+            * stabilized from experimental
         """
         return self._query_bookmark_manager
 
@@ -1020,11 +998,7 @@ async def _work(
 ) -> _T:
     res = await tx.run(query, parameters)
     if transformer is AsyncResult.to_eager_result:
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore",
-                                    message=r".*\bto_eager_result\b.*",
-                                    category=ExperimentalWarning)
-            return await transformer(res)
+        return await transformer(res)
     return await transformer(res)