[ADR-001] bookmark manager (#771)

Co-authored-by: Florent Biville <florent.biville@neo4j.com>
Co-authored-by: Antonio Barcelos <antonio.barcelos@neo4j.com>

Author: 3 people

bin/make-unasync

@@ -154,12 +154,12 @@ class CustomRule(unasync.Rule):
                     start += 1
                     end += 1
                 else:
-                    out += self._unasync_prefix(name[start:(end - 1)])
+                    out += self._unasync_name(name[start:(end - 1)])
                     start = end - 1
 
         sub_name = name[start:]
         if sub_name.isidentifier():
-            out += self._unasync_prefix(name[start:])
+            out += self._unasync_name(name[start:])
         else:
             out += sub_name
 
@@ -221,6 +221,7 @@ def apply_unasync(files):
         "mark_async_test": "mark_sync_test",
         "assert_awaited_once": "assert_called_once",
         "assert_awaited_once_with": "assert_called_once_with",
+        "await_count": "call_count",
     }
     additional_testkit_backend_replacements = {}
     rules = [

docs/source/api.rst

@@ -14,40 +14,41 @@ Driver Construction
 The :class:`neo4j.Driver` construction is done via a ``classmethod`` on the :class:`neo4j.GraphDatabase` class.
 
 .. autoclass:: neo4j.GraphDatabase
-   :members: driver
+   :members: bookmark_manager
 
+    .. method:: driver
 
-Driver creation example:
+        Driver creation example:
 
-.. code-block:: python
+        .. code-block:: python
 
-    from neo4j import GraphDatabase
+            from neo4j import GraphDatabase
 
-    uri = "neo4j://example.com:7687"
-    driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))
+            uri = "neo4j://example.com:7687"
+            driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))
 
-    driver.close()  # close the driver object
+            driver.close()  # close the driver object
 
 
-For basic authentication, ``auth`` can be a simple tuple, for example:
+        For basic authentication, ``auth`` can be a simple tuple, for example:
 
-.. code-block:: python
+        .. code-block:: python
 
-   auth = ("neo4j", "password")
+           auth = ("neo4j", "password")
 
-This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``.
-Other authentication methods are described under :ref:`auth-ref`.
+        This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``.
+        Other authentication methods are described under :ref:`auth-ref`.
 
 
-``with`` block context example:
+        ``with`` block context example:
 
-.. code-block:: python
+        .. code-block:: python
 
-    from neo4j import GraphDatabase
+            from neo4j import GraphDatabase
 
-    uri = "neo4j://example.com:7687"
-    with GraphDatabase.driver(uri, auth=("neo4j", "password")) as driver:
-        # use the driver
+            uri = "neo4j://example.com:7687"
+            with GraphDatabase.driver(uri, auth=("neo4j", "password")) as driver:
+                # use the driver
 
 
 
@@ -138,7 +139,7 @@ Alternatively, one of the auth token helper functions can be used.
 Driver
 ******
 
-Every Neo4j-backed application will require a :class:`neo4j.Driver` object.
+Every Neo4j-backed application will require a driver object.
 
 This object holds the details required to establish connections with a Neo4j database, including server URIs, credentials and other configuration.
 :class:`neo4j.Driver` objects hold a connection pool from which :class:`neo4j.Session` objects can borrow connections.
@@ -274,6 +275,7 @@ Specify whether TCP keep-alive should be enabled.
 :Default: ``True``
 
 **This is experimental.** (See :ref:`filter-warnings-ref`)
+It might be changed or removed any time even without prior notice.
 
 
 .. _max-connection-lifetime-ref:
@@ -576,6 +578,7 @@ To construct a :class:`neo4j.Session` use the :meth:`neo4j.Driver.session` metho
 + :ref:`database-ref`
 + :ref:`default-access-mode-ref`
 + :ref:`fetch-size-ref`
++ :ref:`bookmark-manager-ref`
 
 
 .. _bookmarks-ref:
@@ -704,6 +707,33 @@ The fetch size used for requesting messages from Neo4j.
 :Default: ``1000``
 
 
+.. _bookmark-manager-ref:
+
+``bookmark_manager``
+--------------------
+Specify a bookmark manager for the session to use. If present, the bookmark
+manager is used to keep all work within the session causally consistent with
+all work in other sessions using the same bookmark manager.
+
+See :class:`.BookmarkManager` for more information.
+
+.. warning::
+    Enabling the BookmarkManager can have a negative impact on performance since
+    all queries will wait for the latest changes to be propagated across the
+    cluster.
+
+    For simple use-cases, it often suffices that work within a single session
+    is automatically causally consistent.
+
+:Type: :const:`None` or :class:`.BookmarkManager`
+:Default: :const:`None`
+
+.. versionadded:: 5.0
+
+**This is experimental.** (See :ref:`filter-warnings-ref`)
+It might be changed or removed any time even without prior notice.
+
+
 
 
 ***********
@@ -829,7 +859,7 @@ Returning a live result object would prevent the driver from correctly managing
 
 This function will receive a :class:`neo4j.ManagedTransaction` object as its first parameter.
 
-.. autoclass:: neo4j.ManagedTransaction
+.. autoclass:: neo4j.ManagedTransaction()
 
     .. automethod:: run
 
@@ -911,6 +941,7 @@ Graph
     .. automethod:: relationship_type
 
 **This is experimental.** (See :ref:`filter-warnings-ref`)
+It might be changed or removed any time even without prior notice.
 
 
 ******
@@ -1231,6 +1262,14 @@ Temporal Data Types
 See topic :ref:`temporal-data-types` for more details.
 
 
+***************
+BookmarkManager
+***************
+
+.. autoclass:: neo4j.api.BookmarkManager
+    :members:
+
+
 .. _errors-ref:
 
 ******
@@ -1526,6 +1565,7 @@ Bookmarks
 
 .. autoclass:: neo4j.Bookmarks
     :members:
+    :special-members: __bool__, __add__, __iter__
 
 .. autoclass:: neo4j.Bookmark
     :members:

docs/source/async_api.rst

@@ -21,51 +21,53 @@ Async Driver Construction
 The :class:`neo4j.AsyncDriver` construction is done via a ``classmethod`` on the :class:`neo4j.AsyncGraphDatabase` class.
 
 .. autoclass:: neo4j.AsyncGraphDatabase
-   :members: driver
+    :members: bookmark_manager
 
+    .. automethod:: driver
 
-Driver creation example:
+        Driver creation example:
 
-.. code-block:: python
+        .. code-block:: python
 
-    import asyncio
+            import asyncio
 
-    from neo4j import AsyncGraphDatabase
+            from neo4j import AsyncGraphDatabase
 
-    async def main():
-        uri = "neo4j://example.com:7687"
-        driver = AsyncGraphDatabase.driver(uri, auth=("neo4j", "password"))
+            async def main():
+                uri = "neo4j://example.com:7687"
+                driver = AsyncGraphDatabase.driver(uri, auth=("neo4j", "password"))
 
-        await driver.close()  # close the driver object
+                await driver.close()  # close the driver object
 
-     asyncio.run(main())
+             asyncio.run(main())
 
 
-For basic authentication, ``auth`` can be a simple tuple, for example:
+        For basic authentication, ``auth`` can be a simple tuple, for example:
 
-.. code-block:: python
+        .. code-block:: python
 
-   auth = ("neo4j", "password")
+           auth = ("neo4j", "password")
 
-This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``.
-Other authentication methods are described under :ref:`auth-ref`.
+        This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``.
+        Other authentication methods are described under :ref:`auth-ref`.
 
-``with`` block context example:
+        ``with`` block context example:
 
-.. code-block:: python
+        .. code-block:: python
 
-    import asyncio
+            import asyncio
 
-    from neo4j import AsyncGraphDatabase
+            from neo4j import AsyncGraphDatabase
 
-    async def main():
-        uri = "neo4j://example.com:7687"
-        auth = ("neo4j", "password")
-        async with AsyncGraphDatabase.driver(uri, auth=auth) as driver:
-            # use the driver
-            ...
+            async def main():
+                uri = "neo4j://example.com:7687"
+                auth = ("neo4j", "password")
+                async with AsyncGraphDatabase.driver(uri, auth=auth) as driver:
+                    # use the driver
+                    ...
+
+             asyncio.run(main())
 
-     asyncio.run(main())
 
 
 .. _async-uri-ref:
@@ -120,7 +122,7 @@ Each supported scheme maps to a particular :class:`neo4j.AsyncDriver` subclass t
 AsyncDriver
 ***********
 
-Every Neo4j-backed application will require a :class:`neo4j.AsyncDriver` object.
+Every Neo4j-backed application will require a driver object.
 
 This object holds the details required to establish connections with a Neo4j database, including server URIs, credentials and other configuration.
 :class:`neo4j.AsyncDriver` objects hold a connection pool from which :class:`neo4j.AsyncSession` objects can borrow connections.
@@ -144,6 +146,7 @@ Async Driver Configuration
 (see :ref:`driver-configuration-ref`). The only difference is that the async
 driver accepts an async custom resolver function:
 
+
 .. _async-resolver-ref:
 
 ``resolver``
@@ -366,7 +369,35 @@ Session Configuration
 =====================
 
 :class:`neo4j.AsyncSession` is configured exactly like :class:`neo4j.Session`
-(see :ref:`session-configuration-ref`).
+(see :ref:`session-configuration-ref`). The only difference is the async session
+accepts either a :class:`neo4j.api.BookmarkManager` object or a
+:class:`neo4j.api.AsyncBookmarkManager` as bookmark manager:
+
+
+.. _async-bookmark-manager-ref:
+
+``bookmark_manager``
+--------------------
+Specify a bookmark manager for the driver to use. If present, the bookmark
+manager is used to keep all work on the driver causally consistent.
+
+See :class:`BookmarkManager` for more information.
+
+.. warning::
+    Enabling the BookmarkManager can have a negative impact on performance since
+    all queries will wait for the latest changes to be propagated across the
+    cluster.
+
+    For simpler use-cases, sessions (:class:`.AsyncSession`) can be used to
+    group a series of queries together that will be causally chained
+    automatically.
+
+:Type: :const:`None`, :class:`BookmarkManager`, or :class:`AsyncBookmarkManager`
+:Default: :const:`None`
+
+**This is experimental.** (See :ref:`filter-warnings-ref`)
+It might be changed or removed any time even without prior notice.
+
 
 
 ****************
@@ -501,7 +532,7 @@ Returning a live result object would prevent the driver from correctly managing
 
 This function will receive a :class:`neo4j.AsyncManagedTransaction` object as its first parameter.
 
-.. autoclass:: neo4j.AsyncManagedTransaction
+.. autoclass:: neo4j.AsyncManagedTransaction()
 
     .. automethod:: run
 
@@ -522,7 +553,6 @@ Example:
 To exert more control over how a transaction function is carried out, the :func:`neo4j.unit_of_work` decorator can be used.
 
 
-
 ***********
 AsyncResult
 ***********
@@ -568,6 +598,13 @@ A :class:`neo4j.AsyncResult` is attached to an active connection, through a :cla
 See https://neo4j.com/docs/python-manual/current/cypher-workflow/#python-driver-type-mapping for more about type mapping.
 
 
+********************
+AsyncBookmarkManager
+********************
+
+.. autoclass:: neo4j.api.AsyncBookmarkManager
+    :members:
+
 
 ******************
 Async Cancellation