Replace Session.last_bookmark with Session.last_bookmarks

Renamed the attribute and made it return a list of strings instead of an
optional string.

Furthermore, it will return *all* initial bookmarks (if not updated by a  server
message since session creation) instead of only the last bookmark, which not
necessarily would be the latest bookmark.

Author: robsdedude

CHANGELOG.md

@@ -54,6 +54,8 @@
   was silently ignored.
 - `Result.single` now raises `ResultNotSingleError` if not exactly one result is
   available.
+- `Session.last_bookmark` was renamed to `Session.last_bookmarks`.
+  It returns a list of strings (previously string or None).
 
 ## Version 4.4
 

neo4j/_async/work/session.py

@@ -110,7 +110,7 @@ async def _connect(self, access_mode):
 
     def _collect_bookmark(self, bookmark):
         if bookmark:
-            self._bookmarks = [bookmark]
+            self._bookmarks = bookmark,
 
     async def _result_closed(self):
         if self._auto_result:
@@ -222,11 +222,28 @@ async def run(self, query, parameters=None, **kwargs):
 
         return self._auto_result
 
-    async def last_bookmark(self):
-        """Return the bookmark received following the last completed transaction.
-        Note: For auto-transaction (Session.run) this will trigger an consume for the current result.
+    async def last_bookmarks(self):
+        """Return most recent bookmarks of the session.
 
-        :returns: :class:`neo4j.Bookmark` object
+        Bookmarks can be used to causally chain sessions. For example,
+        if a session (``session1``) wrote something, that another session
+        (``session2``) needs to read, use
+        ``session2 = driver.session(bookmarks=session1.last_bookmarks())`` to
+        achieve this.
+
+        A session automatically manages bookmarks, so this method is rarely
+        needed. If you need causal consistency, try to run the relevant queries
+        in the same session.
+
+        "Most recent bookmarks" are either the bookmarks passed to the session
+        or creation, or the last bookmark the session received after committing
+        a transaction to the server.
+
+        Note: For auto-transaction (Session.run) this will trigger a
+        ``consume`` for the current result.
+
+        :returns: list of bookmarks
+        :rtype: list[str]
         """
         # The set of bookmarks to be passed into the next transaction.
 
@@ -237,9 +254,7 @@ async def last_bookmark(self):
             self._collect_bookmark(self._transaction._bookmark)
             self._transaction = None
 
-        if len(self._bookmarks):
-            return self._bookmarks[len(self._bookmarks)-1]
-        return None
+        return list(self._bookmarks)
 
     async def _transaction_closed_handler(self):
         if self._transaction:

neo4j/_sync/work/session.py

@@ -110,7 +110,7 @@ def _connect(self, access_mode):
 
     def _collect_bookmark(self, bookmark):
         if bookmark:
-            self._bookmarks = [bookmark]
+            self._bookmarks = bookmark,
 
     def _result_closed(self):
         if self._auto_result:
@@ -222,11 +222,28 @@ def run(self, query, parameters=None, **kwargs):
 
         return self._auto_result
 
-    def last_bookmark(self):
-        """Return the bookmark received following the last completed transaction.
-        Note: For auto-transaction (Session.run) this will trigger an consume for the current result.
+    def last_bookmarks(self):
+        """Return most recent bookmarks of the session.
 
-        :returns: :class:`neo4j.Bookmark` object
+        Bookmarks can be used to causally chain sessions. For example,
+        if a session (``session1``) wrote something, that another session
+        (``session2``) needs to read, use
+        ``session2 = driver.session(bookmarks=session1.last_bookmarks())`` to
+        achieve this.
+
+        A session automatically manages bookmarks, so this method is rarely
+        needed. If you need causal consistency, try to run the relevant queries
+        in the same session.
+
+        "Most recent bookmarks" are either the bookmarks passed to the session
+        or creation, or the last bookmark the session received after committing
+        a transaction to the server.
+
+        Note: For auto-transaction (Session.run) this will trigger a
+        ``consume`` for the current result.
+
+        :returns: list of bookmarks
+        :rtype: list[str]
         """
         # The set of bookmarks to be passed into the next transaction.
 
@@ -237,9 +254,7 @@ def last_bookmark(self):
             self._collect_bookmark(self._transaction._bookmark)
             self._transaction = None
 
-        if len(self._bookmarks):
-            return self._bookmarks[len(self._bookmarks)-1]
-        return None
+        return list(self._bookmarks)
 
     def _transaction_closed_handler(self):
         if self._transaction:

testkitbackend/_async/requests.py

@@ -323,10 +323,7 @@ async def RetryableNegative(backend, data):
 async def SessionLastBookmarks(backend, data):
     key = data["sessionId"]
     session = backend.sessions[key].session
-    bookmark = await session.last_bookmark()
-    bookmarks = []
-    if bookmark:
-        bookmarks.append(bookmark)
+    bookmarks = await session.last_bookmarks()
     await backend.send_response("Bookmarks", {"bookmarks": bookmarks})
 
 

testkitbackend/_sync/requests.py

@@ -323,10 +323,7 @@ def RetryableNegative(backend, data):
 def SessionLastBookmarks(backend, data):
     key = data["sessionId"]
     session = backend.sessions[key].session
-    bookmark = session.last_bookmark()
-    bookmarks = []
-    if bookmark:
-        bookmarks.append(bookmark)
+    bookmarks = session.last_bookmarks()
     backend.send_response("Bookmarks", {"bookmarks": bookmarks})
 
 

tests/integration/examples/test_pass_bookmarks_example.py

@@ -76,13 +76,13 @@ def main(self):
         with self.driver.session() as session_a:
             session_a.write_transaction(self.create_person, "Alice")
             session_a.write_transaction(self.employ, "Alice", "Wayne Enterprises")
-            saved_bookmarks.append(session_a.last_bookmark())
+            saved_bookmarks.extend(session_a.last_bookmarks())
 
         # Create the second person and employment relationship.
         with self.driver.session() as session_b:
             session_b.write_transaction(self.create_person, "Bob")
             session_b.write_transaction(self.employ, "Bob", "LexCorp")
-            saved_bookmarks.append(session_b.last_bookmark())
+            saved_bookmarks.extend(session_b.last_bookmarks())
 
         # Create a friendship between the two people created above.
         with self.driver.session(bookmarks=saved_bookmarks) as session_c:

tests/unit/async_/work/test_session.py

@@ -169,16 +169,21 @@ async def test_closes_connection_after_tx_commit(pool, test_run_args):
         assert session._connection is None
 
 
-@pytest.mark.parametrize("bookmarks", (None, [], ["abc"], ["foo", "bar"]))
+@pytest.mark.parametrize(
+    "bookmarks",
+    (None, [], ["abc"], ["foo", "bar"], {"a", "b"}, ("1", "two"))
+)
 @mark_async_test
 async def test_session_returns_bookmark_directly(pool, bookmarks):
     async with AsyncSession(
         pool, SessionConfig(bookmarks=bookmarks)
     ) as session:
-        if bookmarks:
-            assert await session.last_bookmark() == bookmarks[-1]
+        if bookmarks is None:
+            assert await session.last_bookmarks() == []
+        elif isinstance(bookmarks, set):
+            assert sorted(await session.last_bookmarks()) == sorted(bookmarks)
         else:
-            assert await session.last_bookmark() is None
+            assert await session.last_bookmarks() == list(bookmarks)
 
 
 @pytest.mark.parametrize(("query", "error_type"), (

tests/unit/sync/work/test_session.py

@@ -169,16 +169,21 @@ def test_closes_connection_after_tx_commit(pool, test_run_args):
         assert session._connection is None
 
 
-@pytest.mark.parametrize("bookmarks", (None, [], ["abc"], ["foo", "bar"]))
+@pytest.mark.parametrize(
+    "bookmarks",
+    (None, [], ["abc"], ["foo", "bar"], {"a", "b"}, ("1", "two"))
+)
 @mark_sync_test
 def test_session_returns_bookmark_directly(pool, bookmarks):
     with Session(
         pool, SessionConfig(bookmarks=bookmarks)
     ) as session:
-        if bookmarks:
-            assert session.last_bookmark() == bookmarks[-1]
+        if bookmarks is None:
+            assert session.last_bookmarks() == []
+        elif isinstance(bookmarks, set):
+            assert sorted(session.last_bookmarks()) == sorted(bookmarks)
         else:
-            assert session.last_bookmark() is None
+            assert session.last_bookmarks() == list(bookmarks)
 
 
 @pytest.mark.parametrize(("query", "error_type"), (