Make newly created session return no bookmarks

Author: robsdedude

CHANGELOG.md

@@ -16,39 +16,42 @@
     Use `trusted_certificates` instead which expects `None` or a `list`. See the
     API documentation for more details.
 - `neo4j.time` module:
- - `Duration`
-   - The constructor does not accept `subseconds` anymore.  
-     Use `milliseconds`, `microseconds`, or `nanoseconds` instead.
-   - The property `subseconds` has been removed.  
-     Use `nanoseconds` instead.
-   - The property `hours_minutes_seconds` has been removed.  
-     Use `hours_minutes_seconds_nanoseconds` instead.
-   - For all math operations holds: they are element-wise on
-     (`months`, `days`, `nanoseconds`).
-     This affects (i.e., changes) the working of `//`, `%`, `/`, and `*`.
-     - Years are equal to 12 months.
-     - Weeks are equal to 7 days.
-     - `seconds`, `milliseconds`, `microseconds`, and `nanoseconds` are
-       implicitly converted to `nanoseconds` or `seconds` as fit.
-   - Multiplication and division allow for floats but will always result in
-     integer values (round to nearest even).
- - `Time`
-   - The constructor does not accept `float`s for `second` anymore.  
-     Use `nanosecond` instead.
-   - Ticks are now nanoseconds since midnight (`int`).
-     - The property `ticks_ns` has been renamed to `ticks`.  
-       The old `ticks` is no longer supported.
-     - The property`from_ticks_ns` has been renamed to `from_ticks`.  
-       The old `from_ticks` is no longer supported.
-   - The property `second` returns an `int` instead of a `float`.  
-     Use `nanosecond` to get the sub-second information.
-   - The property `hour_minute_second` has been removed.  
-     Use `hour_minute_second_nanosecond` instead.
- - `DateTime`
-   - The property `hour_minute_second` has been removed.  
-     Use `hour_minute_second_nanosecond` instead.
-   - The property `second` returns an `int` instead of a `float`.  
-     Use `nanosecond` to get the sub-second information.
+  - `Duration`
+    - The constructor does not accept `subseconds` anymore.  
+      Use `milliseconds`, `microseconds`, or `nanoseconds` instead.
+    - The property `subseconds` has been removed.  
+      Use `nanoseconds` instead.
+    - The property `hours_minutes_seconds` has been removed.  
+      Use `hours_minutes_seconds_nanoseconds` instead.
+    - For all math operations holds: they are element-wise on
+      (`months`, `days`, `nanoseconds`).
+      This affects (i.e., changes) the working of `//`, `%`, `/`, and `*`.
+      - Years are equal to 12 months.
+      - Weeks are equal to 7 days.
+      - `seconds`, `milliseconds`, `microseconds`, and `nanoseconds` are
+        implicitly converted to `nanoseconds` or `seconds` as fit.
+    - Multiplication and division allow for floats but will always result in
+      integer values (round to nearest even).
+  - `Time`
+    - The constructor does not accept `float`s for `second` anymore.  
+      Use `nanosecond` instead.
+    - Ticks are now nanoseconds since midnight (`int`).
+      - The property `ticks_ns` has been renamed to `ticks`.  
+        The old `ticks` is no longer supported.
+      - The property`from_ticks_ns` has been renamed to `from_ticks`.  
+        The old `from_ticks` is no longer supported.
+    - The property `second` returns an `int` instead of a `float`.  
+      Use `nanosecond` to get the sub-second information.
+    - The property `hour_minute_second` has been removed.  
+      Use `hour_minute_second_nanosecond` instead.
+  - `DateTime`
+    - The property `hour_minute_second` has been removed.  
+      Use `hour_minute_second_nanosecond` instead.
+    - The property `second` returns an `int` instead of a `float`.  
+      Use `nanosecond` to get the sub-second information.
+- `Session.last_bookmark` returns `None` until the first bookmark has been
+  received from the server. Previously, it returned the last bookmark of all
+  the bookmarks passed on session creation.
 
 
 ## Version 4.4

neo4j/_async/work/session.py

@@ -85,7 +85,8 @@ class AsyncSession(AsyncWorkspace):
     def __init__(self, pool, session_config):
         super().__init__(pool, session_config)
         assert isinstance(session_config, SessionConfig)
-        self._bookmarks = tuple(session_config.bookmarks)
+        self._bookmarks_in = tuple(session_config.bookmarks)
+        self._bookmark_out = None
 
     def __del__(self):
         if asyncio.iscoroutinefunction(self.close):
@@ -110,7 +111,8 @@ async def _connect(self, access_mode):
 
     def _collect_bookmark(self, bookmark):
         if bookmark:
-            self._bookmarks = [bookmark]
+            self._bookmarks_in = bookmark,
+            self._bookmark_out = bookmark
 
     async def _result_closed(self):
         if self._auto_result:
@@ -217,16 +219,28 @@ async def run(self, query, parameters=None, **kwargs):
         await self._auto_result._run(
             query, parameters, self._config.database,
             self._config.impersonated_user, self._config.default_access_mode,
-            self._bookmarks, **kwargs
+            self._bookmarks_in, **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.
+        """Return the bookmark received from the last completed transaction.
 
-        :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_bookmark())`` 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.
+
+        Note: For auto-transaction (Session.run) this will trigger a
+        ``consume`` for the current result.
+
+        :returns: str or None
         """
         # The set of bookmarks to be passed into the next transaction.
 
@@ -237,9 +251,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 self._bookmark_out
 
     async def _transaction_closed_handler(self):
         if self._transaction:
@@ -262,7 +274,7 @@ async def _open_transaction(self, *, access_mode, metadata=None,
         )
         await self._transaction._begin(
             self._config.database, self._config.impersonated_user,
-            self._bookmarks, access_mode, metadata, timeout
+            self._bookmarks_in, access_mode, metadata, timeout
         )
 
     async def begin_transaction(self, metadata=None, timeout=None):

neo4j/_async/work/workspace.py

@@ -33,7 +33,7 @@ def __init__(self, pool, config):
         self._connection_access_mode = None
         # Sessions are supposed to cache the database on which to operate.
         self._cached_database = False
-        self._bookmarks = None
+        self._bookmarks_in = None
 
     def __del__(self):
         if asyncio.iscoroutinefunction(self.close):
@@ -74,14 +74,14 @@ async def _connect(self, access_mode):
                 await self._pool.update_routing_table(
                     database=self._config.database,
                     imp_user=self._config.impersonated_user,
-                    bookmarks=self._bookmarks,
+                    bookmarks=self._bookmarks_in,
                     database_callback=self._set_cached_database
                 )
         self._connection = await self._pool.acquire(
             access_mode=access_mode,
             timeout=self._config.connection_acquisition_timeout,
             database=self._config.database,
-            bookmarks=self._bookmarks
+            bookmarks=self._bookmarks_in
         )
         self._connection_access_mode = access_mode
 

neo4j/_sync/work/session.py

@@ -85,7 +85,8 @@ class Session(Workspace):
     def __init__(self, pool, session_config):
         super().__init__(pool, session_config)
         assert isinstance(session_config, SessionConfig)
-        self._bookmarks = tuple(session_config.bookmarks)
+        self._bookmarks_in = tuple(session_config.bookmarks)
+        self._bookmark_out = None
 
     def __del__(self):
         if asyncio.iscoroutinefunction(self.close):
@@ -110,7 +111,8 @@ def _connect(self, access_mode):
 
     def _collect_bookmark(self, bookmark):
         if bookmark:
-            self._bookmarks = [bookmark]
+            self._bookmarks_in = bookmark,
+            self._bookmark_out = bookmark
 
     def _result_closed(self):
         if self._auto_result:
@@ -217,16 +219,28 @@ def run(self, query, parameters=None, **kwargs):
         self._auto_result._run(
             query, parameters, self._config.database,
             self._config.impersonated_user, self._config.default_access_mode,
-            self._bookmarks, **kwargs
+            self._bookmarks_in, **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.
+        """Return the bookmark received from the last completed transaction.
 
-        :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_bookmark())`` 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.
+
+        Note: For auto-transaction (Session.run) this will trigger a
+        ``consume`` for the current result.
+
+        :returns: str or None
         """
         # The set of bookmarks to be passed into the next transaction.
 
@@ -237,9 +251,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 self._bookmark_out
 
     def _transaction_closed_handler(self):
         if self._transaction:
@@ -262,7 +274,7 @@ def _open_transaction(self, *, access_mode, metadata=None,
         )
         self._transaction._begin(
             self._config.database, self._config.impersonated_user,
-            self._bookmarks, access_mode, metadata, timeout
+            self._bookmarks_in, access_mode, metadata, timeout
         )
 
     def begin_transaction(self, metadata=None, timeout=None):

neo4j/_sync/work/workspace.py

@@ -33,7 +33,7 @@ def __init__(self, pool, config):
         self._connection_access_mode = None
         # Sessions are supposed to cache the database on which to operate.
         self._cached_database = False
-        self._bookmarks = None
+        self._bookmarks_in = None
 
     def __del__(self):
         if asyncio.iscoroutinefunction(self.close):
@@ -74,14 +74,14 @@ def _connect(self, access_mode):
                 self._pool.update_routing_table(
                     database=self._config.database,
                     imp_user=self._config.impersonated_user,
-                    bookmarks=self._bookmarks,
+                    bookmarks=self._bookmarks_in,
                     database_callback=self._set_cached_database
                 )
         self._connection = self._pool.acquire(
             access_mode=access_mode,
             timeout=self._config.connection_acquisition_timeout,
             database=self._config.database,
-            bookmarks=self._bookmarks
+            bookmarks=self._bookmarks_in
         )
         self._connection_access_mode = access_mode