MOD: Live iteration starts after session error

Author: nmacholl

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.28.0 - TBD
+
+#### Breaking change
+- Iterating a `Live` client after the streaming session has started will now raise a `ValueError`. Calling `Live.start` is not necessary when iterating the `Live` client
+
 ## 0.27.0 - 2024-01-23
 
 #### Enhancements

databento/live/client.py

@@ -127,9 +127,14 @@ async def __anext__(self) -> DBNRecord:
 
     def __iter__(self) -> Live:
         logger.debug("starting iteration")
-        self._dbn_queue._enabled.set()
-        if not self._session.is_started() and self.is_connected():
+        if self._session.is_started():
+            logger.error("iteration started after session has started")
+            raise ValueError(
+                "Cannot start iteration after streaming has started, records may be missed. Don't call `Live.start` before iterating.",
+            )
+        elif self.is_connected():
             self.start()
+        self._dbn_queue._enabled.set()
         return self
 
     def __next__(self) -> DBNRecord:
@@ -358,12 +363,14 @@ def start(
         """
         Start the live client session.
 
+        It is not necessary to call `Live.start` before iterating a `Live` client and doing so will result in an error.
+
         Raises
         ------
         ValueError
-            If `start()` is called before a subscription has been made.
-            If `start()` is called after streaming has already started.
-            If `start()` is called after the live session has closed.
+            If `Live.start` is called before a subscription has been made.
+            If `Live.start` is called after streaming has already started.
+            If `Live.start` is called after the live session has closed.
 
         See Also
         --------
@@ -388,7 +395,7 @@ def stop(self) -> None:
         Raises
         ------
         ValueError
-            If `stop()` is called before a connection has been made.
+            If `Live.stop` is called before a connection has been made.
 
         See Also
         --------
@@ -505,7 +512,7 @@ def block_for_close(
     ) -> None:
         """
         Block until the session closes or a timeout is reached. A session will
-        close after `stop()` is called or the remote gateway disconnects.
+        close after `Live.stop` is called or the remote gateway disconnects.
 
         Parameters
         ----------
@@ -548,7 +555,7 @@ async def wait_for_close(
     ) -> None:
         """
         Coroutine to wait until the session closes or a timeout is reached. A
-        session will close after `stop()` is called or the remote gateway
+        session will close after `Live.stop` is called or the remote gateway
         disconnects.
 
         Parameters

tests/test_live_client.py

@@ -345,6 +345,48 @@ def test_live_start_before_subscribe(
         live_client.start()
 
 
+def test_live_iteration_after_start(
+    live_client: client.Live,
+) -> None:
+    """
+    Test that iterating the Live client after it is started raises a
+    ValueError.
+    """
+    # Arrange
+    live_client.subscribe(
+        dataset=Dataset.GLBX_MDP3,
+        schema=Schema.MBO,
+    )
+
+    # Act
+    live_client.start()
+
+    # Assert
+    with pytest.raises(ValueError):
+        iter(live_client)
+
+
+def test_live_async_iteration_after_start(
+    live_client: client.Live,
+) -> None:
+    """
+    Test that async-iterating the Live client after it is started raises a
+    ValueError.
+    """
+    # Arrange
+    live_client.subscribe(
+        dataset=Dataset.GLBX_MDP3,
+        schema=Schema.MBO,
+    )
+
+    # Act
+    live_client.start()
+
+    # Assert
+    with pytest.raises(ValueError):
+        live_client.__aiter__()
+
+
 @pytest.mark.parametrize(
     "schema",
     [pytest.param(schema, id=str(schema)) for schema in Schema.variants()],