VER: Relese 0.34.1

See release notes.

Author: nmacholl

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.34.1 - 2024-05-21
+
+#### Enhancements
+- Added `use_snapshot` parameter to `Live.subscribe`, defaults to `False`
+
 ## 0.34.0 - 2024-05-14
 
 #### Enhancements
@@ -11,6 +16,9 @@
 - Fixed an issue where `batch.download`, `batch.download_async`, and `timeseries.get_range` could use a lot of memory while streaming data
 - Fixed an issue where reusing a `Live` client with an open output stream would drop DBN records when received at the same time as the `Metadata` header
 
+##### Deprecations
+- The `start_date` and `end_date` keys in the response from `Historical.metadata.get_dataset_range` will be removed in a future release. Use the new `start` and `end` keys instead, which include time resolution
+
 ## 0.33.0 - 2024-04-16
 
 #### Enhancements

databento/live/client.py

@@ -379,6 +379,7 @@ def subscribe(
         symbols: Iterable[str | int] | str | int = ALL_SYMBOLS,
         stype_in: SType | str = SType.RAW_SYMBOL,
         start: str | int | None = None,
+        use_snapshot: bool = False,
     ) -> None:
         """
         Subscribe to a data stream. Multiple subscription requests can be made
@@ -401,11 +402,14 @@ def subscribe(
             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.
+        use_snapshot: bool, default to 'False'
+            Reserved for future use.
 
         Raises
         ------
         ValueError
             If a dataset is given that does not match the previous datasets.
+            If use_snapshot is True and start is not None.
         BentoError
             If creating the connection times out.
             If creating the connection fails.
@@ -419,11 +423,12 @@ def subscribe(
 
         """
         logger.info(
-            "subscribing to %s:%s %s start=%s",
+            "subscribing to %s:%s %s start=%s use_snapshot=%s",
             schema,
             stype_in,
             symbols,
             start if start is not None else "now",
+            use_snapshot,
         )
         dataset = validate_semantic_string(dataset, "dataset")
         schema = validate_enum(schema, Schema, "schema")
@@ -437,12 +442,17 @@ def subscribe(
                 f"Cannot subscribe to dataset `{dataset}` "
                 f"because subscriptions to `{self.dataset}` have already been made.",
             )
+
+        if use_snapshot and start is not None:
+            raise ValueError("Subscription with snapshot expects start=None")
+
         self._session.subscribe(
             dataset=dataset,
             schema=schema,
             stype_in=stype_in,
             symbols=symbols,
             start=start,
+            use_snapshot=use_snapshot,
         )
 
     def terminate(self) -> None:

databento/live/gateway.py

@@ -121,6 +121,7 @@ class SubscriptionRequest(GatewayControl):
     stype_in: SType
     symbols: str
     start: int | None = None
+    snapshot: int = 0
 
 
 @dataclasses.dataclass

databento/live/protocol.py

@@ -256,6 +256,7 @@ def subscribe(
         symbols: Iterable[str | int] | str | int = ALL_SYMBOLS,
         stype_in: SType | str = SType.RAW_SYMBOL,
         start: str | int | None = None,
+        use_snapshot: bool = False,
     ) -> None:
         """
         Send a SubscriptionRequest to the gateway.
@@ -271,15 +272,19 @@ def subscribe(
         start : str or int, optional
             UNIX nanosecond epoch timestamp to start streaming from. Must be
             within 24 hours.
+        use_snapshot: bool, default to 'False'
+            Reserved for future use.
 
         """
         logger.info(
-            "sending subscription to %s:%s %s start=%s",
+            "sending subscription to %s:%s %s start=%s use_snapshot=%s",
             schema,
             stype_in,
             symbols,
             start if start is not None else "now",
+            use_snapshot,
         )
+
         stype_in_valid = validate_enum(stype_in, SType, "stype_in")
         symbols_list = optional_symbols_list_to_list(symbols, stype_in_valid)
 
@@ -291,6 +296,7 @@ def subscribe(
                 stype_in=stype_in_valid,
                 symbols=batch_str,
                 start=optional_datetime_to_unix_nanoseconds(start),
+                snapshot=int(use_snapshot),
             )
             subscription_bytes.append(bytes(message))
 

databento/live/session.py

@@ -408,6 +408,7 @@ def subscribe(
         symbols: Iterable[str | int] | str | int = ALL_SYMBOLS,
         stype_in: SType | str = SType.RAW_SYMBOL,
         start: str | int | None = None,
+        use_snapshot: bool = False,
     ) -> None:
         """
         Send a subscription request on the current connection. This will create
@@ -426,6 +427,8 @@ def subscribe(
         start : str or int, optional
             UNIX nanosecond epoch timestamp to start streaming from. Must be
             within 24 hours.
+        use_snapshot: bool, default to 'False'
+            Reserved for future use.
 
         """
         with self._lock:
@@ -441,6 +444,7 @@ def subscribe(
                 symbols=symbols,
                 stype_in=stype_in,
                 start=start,
+                use_snapshot=use_snapshot,
             )
 
     def resume_reading(self) -> None:

databento/version.py

@@ -1 +1 @@
-__version__ = "0.34.0"
+__version__ = "0.34.1"

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "databento"
-version = "0.34.0"
+version = "0.34.1"
 description = "Official Python client library for Databento"
 authors = [
     "Databento <[email protected]>",

tests/test_live_client.py

@@ -173,6 +173,43 @@ def test_live_connection_cram_failure(
     exc.match(r"User authentication failed:")
 
 
+@pytest.mark.parametrize(
+    "start",
+    [
+        "now",
+        "2022-06-10T12:00",
+        1671717080706865759,
+    ],
+)
+def test_live_subscription_with_snapshot_failed(
+    mock_live_server: MockLiveServer,
+    test_api_key: str,
+    start: str | int,
+) -> None:
+    """
+    Test that an invalid snapshot subscription raises a ValueError.
+    """
+    # Arrange
+    live_client = client.Live(
+        key=test_api_key,
+        gateway=mock_live_server.host,
+        port=mock_live_server.port,
+    )
+
+    # Act, Assert
+    with pytest.raises(ValueError) as exc:
+        live_client.subscribe(
+            dataset=Dataset.GLBX_MDP3,
+            schema=Schema.MBO,
+            symbols=ALL_SYMBOLS,
+            start=start,
+            use_snapshot=True,
+        )
+
+    # Ensure this was an authentication error
+    exc.match(r"Subscription with snapshot expects start=None")
+
+
 @pytest.mark.parametrize(
     "dataset",
     [pytest.param(dataset, id=str(dataset)) for dataset in Dataset],
@@ -446,6 +483,52 @@ def test_live_subscribe(
     assert message.stype_in == stype_in
     assert message.symbols == symbols
     assert message.start == start
+    assert message.snapshot == "0"
+
+
+@pytest.mark.parametrize(
+    "use_snapshot",
+    [
+        False,
+        True,
+    ],
+)
+def test_live_subscribe_snapshot(
+    live_client: client.Live,
+    mock_live_server: MockLiveServer,
+    use_snapshot: bool,
+) -> None:
+    """
+    Test that use_snapshot parameter is assigned correctly.
+    """
+    # Arrange
+
+    schema = Schema.MBO
+    stype_in = SType.RAW_SYMBOL
+    symbols = ALL_SYMBOLS
+    start = None
+
+    live_client.subscribe(
+        dataset=Dataset.GLBX_MDP3,
+        schema=schema,
+        stype_in=stype_in,
+        symbols=symbols,
+        start=start,
+        use_snapshot=use_snapshot,
+    )
+
+    # Act
+    message = mock_live_server.get_message_of_type(
+        gateway.SubscriptionRequest,
+        timeout=1,
+    )
+
+    # Assert
+    assert message.schema == schema
+    assert message.stype_in == stype_in
+    assert message.symbols == symbols
+    assert message.start == start
+    assert message.snapshot == str(int(use_snapshot))
 
 
 @pytest.mark.usefixtures("mock_live_server")

tests/test_live_gateway_messages.py

@@ -347,19 +347,31 @@ def test_parse_subscription_request(
                 stype_in=SType.INSTRUMENT_ID,
                 symbols="1234,5678,90",
             ),
-            b"schema=mbo|" b"stype_in=instrument_id|" b"symbols=1234,5678,90\n",
+            b"schema=mbo|" b"stype_in=instrument_id|" b"symbols=1234,5678,90|" b"snapshot=0\n",
         ),
         pytest.param(
             SubscriptionRequest(
                 schema=Schema.MBO,
                 stype_in=SType.RAW_SYMBOL,
                 symbols="UNI,TTE,ST",
                 start=1671717080706865759,
+                snapshot=0,
             ),
             b"schema=mbo|"
             b"stype_in=raw_symbol|"
             b"symbols=UNI,TTE,ST|"
-            b"start=1671717080706865759\n",
+            b"start=1671717080706865759|"
+            b"snapshot=0\n",
+        ),
+        pytest.param(
+            SubscriptionRequest(
+                schema=Schema.MBO,
+                stype_in=SType.INSTRUMENT_ID,
+                symbols="1234,5678,90",
+                start=None,
+                snapshot=1,
+            ),
+            b"schema=mbo|" b"stype_in=instrument_id|" b"symbols=1234,5678,90|" b"snapshot=1\n",
         ),
     ],
 )