DOC: Update intraday replay docs

Author: robertmaierle

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.63.1 - TBD
+
+#### Bug fixes
+- Fixed type hint for `start` parameter in `Live.subscribe()`
+
 ## 0.63.0 - 2025-09-02
 
 #### Enhancements
@@ -18,7 +23,7 @@ This release delivers a number of breaking changes to the Python interface for D
   - Removed `hd` property from records in Python. Header fields are accessible
     directly from the record
   - Removed ability to directly instantiate most enums from an `int` in Python and coercion
-    from `int` in `__eq__`. They can still be instantitated with the `from_int` class method.
+    from `int` in `__eq__`. They can still be instantiated with the `from_int` class method.
     Write `Side.from_int(66)` instead of `Side(66)` and `Side.BID == Side.from_int(66)`
     instead of `Side.BID == 66`. Affected enums:
     - `Side`

databento/common/parsing.py

@@ -344,14 +344,14 @@ def optional_datetime_to_string(
 
 
 def datetime_to_unix_nanoseconds(
-    value: pd.Timestamp | date | str | int,
+    value: pd.Timestamp | datetime | date | str | int,
 ) -> int:
     """
     Return a valid UNIX nanosecond timestamp from the given value.
 
     Parameters
     ----------
-    value : pd.Timestamp, date, str, or int
+    value : pd.Timestamp, datetime, date, str, or int
         The value to parse.
 
     Returns
@@ -378,15 +378,15 @@ def datetime_to_unix_nanoseconds(
 
 
 def optional_datetime_to_unix_nanoseconds(
-    value: pd.Timestamp | date | str | int | None,
+    value: pd.Timestamp | datetime | date | str | int | None,
 ) -> int | None:
     """
     Return a valid UNIX nanosecond timestamp from the given value (if not
     None).
 
     Parameters
     ----------
-    value : pd.Timestamp, date, str, or int
+    value : pd.Timestamp, datetime, date, str, or int
         The value to parse.
 
     Returns

databento/live/client.py

@@ -8,10 +8,13 @@
 import threading
 from collections.abc import Iterable
 from concurrent import futures
+from datetime import date
+from datetime import datetime
 from os import PathLike
 from typing import IO
 
 import databento_dbn
+import pandas as pd
 from databento_dbn import Schema
 from databento_dbn import SType
 
@@ -368,20 +371,22 @@ def start(
         self,
     ) -> None:
         """
-        Start the live client session.
+        Start the session.
 
-        It is not necessary to call `Live.start` before iterating a `Live` client and doing so will result in an error.
+        It is not necessary to call this method before iterating a `Live` client and doing so
+        will result in an error.
 
         Raises
         ------
         ValueError
-            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.
+            If called before a subscription has been made.
+            If called after the session has already started.
+            If called after the session has closed.
 
         See Also
         --------
         Live.stop
+        Live.terminate
 
         """
         logger.info("starting live client")
@@ -396,17 +401,25 @@ def start(
 
     def stop(self) -> None:
         """
-        Stop the live client session as soon as possible. Once stopped, a
-        client cannot be restarted.
+        Stop the session and finish processing received records.
+
+        A client can only be stopped after a successful connection is made with `Live.start`.
+
+        This method does not block waiting for the connection to close.
+
+        The connection will eventually close after calling this method. Once the connection
+        is closed, the client can be reused, but the session state is not preserved.
 
         Raises
         ------
         ValueError
-            If `Live.stop` is called before a connection has been made.
+            If called before a connection has started.
 
         See Also
         --------
-        Live.start
+        Live.terminate
+        Live.block_for_close
+        Live.wait_for_close
 
         """
         logger.info("stopping live client")
@@ -424,17 +437,18 @@ def subscribe(
         schema: Schema | str,
         symbols: Iterable[str | int] | str | int = ALL_SYMBOLS,
         stype_in: SType | str = SType.RAW_SYMBOL,
-        start: str | int | None = None,
+        start: pd.Timestamp | datetime | date | str | int | None = None,
         snapshot: bool = False,
     ) -> None:
         """
-        Subscribe to a data stream. Multiple subscription requests can be made
-        for a streaming session. Once one subscription has been made, future
-        subscriptions must all belong to the same dataset.
+        Add a new subscription to the session.
+
+        All subscriptions must be for the same `dataset`.
+
+        Multiple subscriptions for different schemas can be made.
 
-        When creating the first subscription this method will also create
-        the TCP connection to the remote gateway. All subscriptions must
-        have the same dataset.
+        When creating the first subscription, this method will also create
+        the TCP connection to the remote gateway.
 
         Parameters
         ----------
@@ -446,13 +460,14 @@ def subscribe(
             The symbols to subscribe to.
         stype_in : SType or str, default 'raw_symbol'
             The input symbology type to resolve from.
-        start : str or int, optional
-            UNIX nanosecond epoch timestamp to start streaming from (inclusive), based on `ts_event`. Must be within 24 hours except when requesting the mbo or definition schemas.
+        start : pd.Timestamp, datetime, date, str or int, optional
+            The inclusive start of subscription replay.
+            Pass `0` to request all available data.
+            Cannot be specified after the session is started.
+            See `Intraday Replay` https://databento.com/docs/api-reference-live/basics/intraday-replay.
         snapshot: bool, default to 'False'
             Request subscription with snapshot. The `start` parameter must be `None`.
 
-
-
         Raises
         ------
         ValueError
@@ -497,17 +512,23 @@ def subscribe(
 
     def terminate(self) -> None:
         """
-        Terminate the live client session and stop processing records as soon
-        as possible.
+        Terminate the session and stop processing records immediately.
+
+        A client can only be terminated after a connection is started with `Live.start`.
+
+        Once terminated, the client can be reused, but the session state
+        is not preserved.
 
         Raises
         ------
         ValueError
-            If the client is not connected.
+            If called before a connection has started.
 
         See Also
         --------
         Live.stop
+        Live.block_for_close
+        Live.wait_for_close
 
         """
         logger.info("terminating live client")
@@ -521,11 +542,14 @@ def block_for_close(
     ) -> None:
         """
         Block until the session closes or a timeout is reached. A session will
-        close after `Live.stop` is called or the remote gateway disconnects.
+        close after the remote gateway disconnects, or after `Live.stop` or
+        `Live.terminate` are called.
 
-        If a `timeout` is specified, `Live.stop` will be called when the
+        If a `timeout` is specified, `Live.terminate` will be called when the
         timeout is reached.
 
+        When this method unblocks, the session is guaranteed to be closed.
+
         Parameters
         ----------
         timeout : float, optional
@@ -541,7 +565,7 @@ def block_for_close(
 
         See Also
         --------
-        wait_for_close
+        Live.wait_for_close
 
         """
         try:
@@ -565,12 +589,14 @@ async def wait_for_close(
     ) -> None:
         """
         Coroutine to wait until the session closes or a timeout is reached. A
-        session will close after `Live.stop` is called or the remote gateway
-        disconnects.
+        session will close when the remote gateway disconnects, or after
+        `Live.stop` or `Live.terminate` are called.
 
-        If a `timeout` is specified, `Live.stop` will be called when the
+        If a `timeout` is specified, `Live.terminate` will be called when the
         timeout is reached.
 
+        When this method unblocks, the session is guaranteed to be closed.
+
         Parameters
         ----------
         timeout : float, optional
@@ -586,7 +612,7 @@ async def wait_for_close(
 
         See Also
         --------
-        block_for_close
+        Live.block_for_close
 
         """
         waiter = asyncio.wrap_future(

examples/historical_timeseries_from_file.py

@@ -4,10 +4,10 @@
 
 
 if __name__ == "__main__":
-    ts_start = datetime.datetime.utcnow()
+    ts_start = datetime.datetime.now(tz=datetime.timezone.utc)
 
     # Can load from file path (if exists)
     data = DBNStore.from_file(path="my_data.dbn")
 
     print(data.to_df())
-    print(datetime.datetime.utcnow() - ts_start)
+    print(datetime.datetime.now(tz=datetime.timezone.utc) - ts_start)

tests/test_common_parsing.py

@@ -291,6 +291,11 @@ def test_maybe_datetime_to_string_give_valid_values_returns_expected_results(
         pytest.param(1680736543000000000, 1680736543000000000, id="int"),
         pytest.param("1680736543000000000", 1680736543000000000, id="str-int"),
         pytest.param(dt.date(2023, 4, 5), 1680652800000000000, id="date"),
+        pytest.param(
+            dt.datetime(2023, 4, 5, 23, 15, 43, tzinfo=dt.timezone.utc),
+            1680736543000000000,
+            id="datetime",
+        ),
         pytest.param(
             pd.to_datetime("2023-04-05T00:00:00"),
             1680652800000000000,
@@ -304,7 +309,7 @@ def test_maybe_datetime_to_string_give_valid_values_returns_expected_results(
     ],
 )
 def test_datetime_to_unix_nanoseconds(
-    value: pd.Timestamp | str | int,
+    value: pd.Timestamp | dt.datetime | dt.date | str | int,
     expected: int,
 ) -> None:
     """