VER: Release 0.35.0

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.35.0 - 2024-06-04
+
+#### Enhancements
+- Added optional `heartbeat_interval_s` parameter to `Live` client for configuring the
+  interval at which the gateway will send heartbeat records
+- Upgraded `databento-dbn` to 0.18.0
+- Added new off-market publisher values for `IFEU.IMPACT` and `NDEX.IMPACT`
+
+#### Breaking changes
+- Renamed `CbboMsg` to `CBBOMsg`.
+- Renamed `use_snapshot` parameter in `Live.subscribe` function to `snapshot`
+- All Python exceptions raised by `databento-dbn` have been changed to use the `DBNError` type
+
 ## 0.34.1 - 2024-05-21
 
 #### Enhancements
@@ -9,7 +22,7 @@
 
 #### Enhancements
 - Added `pip-system-certs` dependency for Windows platforms to prevent a connection issue in `requests` when behind a proxy
-- Iteration of the `Live` client will now automatically call `Live.stop` when the iterator is destroyed, such as when a for loop is escaped with an exception or `break` statement.
+- Iteration of the `Live` client will now automatically call `Live.stop` when the iterator is destroyed, such as when a for loop is escaped with an exception or `break` statement
 
 #### Bug fixes
 - Fixed an issue where `batch.download` and `batch.download_async` would fail if requested files already existed in the output directory

README.md

@@ -32,7 +32,7 @@ The library is fully compatible with the latest distribution of Anaconda 3.8 and
 The minimum dependencies as found in the `pyproject.toml` are also listed below:
 - python = "^3.8"
 - aiohttp = "^3.8.3"
-- databento-dbn = "0.17.1"
+- databento-dbn = "0.18.0"
 - numpy= ">=1.23.5"
 - pandas = ">=1.5.3"
 - pip-system-certs = ">=4.0" (Windows only)

databento/common/constants.py

@@ -3,7 +3,7 @@
 from typing import Final
 
 import numpy as np
-from databento_dbn import CbboMsg
+from databento_dbn import CBBOMsg
 from databento_dbn import ImbalanceMsg
 from databento_dbn import InstrumentDefMsg
 from databento_dbn import InstrumentDefMsgV1
@@ -41,10 +41,10 @@
     Schema.STATISTICS: StatMsg,
     Schema.TBBO: MBP1Msg,
     Schema.TRADES: TradeMsg,
-    Schema.CBBO: CbboMsg,
-    Schema.CBBO_1S: CbboMsg,
-    Schema.CBBO_1M: CbboMsg,
-    Schema.TCBBO: CbboMsg,
+    Schema.CBBO: CBBOMsg,
+    Schema.CBBO_1S: CBBOMsg,
+    Schema.CBBO_1M: CBBOMsg,
+    Schema.TCBBO: CBBOMsg,
     Schema.BBO_1S: MBP1Msg,
     Schema.BBO_1M: MBP1Msg,
 }

databento/common/publishers.py

@@ -100,6 +100,8 @@ class Venue(StringyMixin, str, Enum):
         MIAX Sapphire.
     LTSE
         Long-Term Stock Exchange, Inc..
+    XOFF
+        Off-Exchange Transactions - Listed Instruments.
 
     """
 
@@ -145,6 +147,7 @@ class Venue(StringyMixin, str, Enum):
     DBEQ = "DBEQ"
     SPHR = "SPHR"
     LTSE = "LTSE"
+    XOFF = "XOFF"
 
     @classmethod
     def from_int(cls, value: int) -> Venue:
@@ -235,6 +238,8 @@ def from_int(cls, value: int) -> Venue:
             return Venue.SPHR
         if value == 42:
             return Venue.LTSE
+        if value == 43:
+            return Venue.XOFF
         raise ValueError(f"Integer value {value} does not correspond with any Venue variant")
 
     def to_int(self) -> int:
@@ -325,6 +330,8 @@ def to_int(self) -> int:
             return 41
         if self == Venue.LTSE:
             return 42
+        if self == Venue.XOFF:
+            return 43
         raise ValueError("Invalid Venue")
 
     @property
@@ -416,6 +423,8 @@ def description(self) -> str:
             return "MIAX Sapphire"
         if self == Venue.LTSE:
             return "Long-Term Stock Exchange, Inc."
+        if self == Venue.XOFF:
+            return "Off-Exchange Transactions - Listed Instruments"
         raise ValueError("Unexpected Venue value")
 
 
@@ -485,6 +494,8 @@ class Dataset(StringyMixin, str, Enum):
         ICE Endex iMpact.
     DBEQ_MAX
         Databento Equities Max.
+    XNAS_BASIC
+        Nasdaq Basic (NLS+QBBO).
 
     """
 
@@ -518,6 +529,7 @@ class Dataset(StringyMixin, str, Enum):
     IFEU_IMPACT = "IFEU.IMPACT"
     NDEX_IMPACT = "NDEX.IMPACT"
     DBEQ_MAX = "DBEQ.MAX"
+    XNAS_BASIC = "XNAS.BASIC"
 
     @classmethod
     def from_int(cls, value: int) -> Dataset:
@@ -584,6 +596,8 @@ def from_int(cls, value: int) -> Dataset:
             return Dataset.NDEX_IMPACT
         if value == 30:
             return Dataset.DBEQ_MAX
+        if value == 31:
+            return Dataset.XNAS_BASIC
         raise ValueError(f"Integer value {value} does not correspond with any Dataset variant")
 
     def to_int(self) -> int:
@@ -650,6 +664,8 @@ def to_int(self) -> int:
             return 29
         if self == Dataset.DBEQ_MAX:
             return 30
+        if self == Dataset.XNAS_BASIC:
+            return 31
         raise ValueError("Invalid Dataset")
 
     @property
@@ -717,6 +733,8 @@ def description(self) -> str:
             return "ICE Endex iMpact"
         if self == Dataset.DBEQ_MAX:
             return "Databento Equities Max"
+        if self == Dataset.XNAS_BASIC:
+            return "Nasdaq Basic (NLS+QBBO)"
         raise ValueError("Unexpected Dataset value")
 
 
@@ -833,9 +851,9 @@ class Publisher(StringyMixin, str, Enum):
     DBEQ_PLUS_XNYS
         DBEQ Plus - NYSE.
     DBEQ_PLUS_FINN
-        DBEQ Plus - FINRA/NYSE TRF.
-    DBEQ_PLUS_FINY
         DBEQ Plus - FINRA/Nasdaq TRF Carteret.
+    DBEQ_PLUS_FINY
+        DBEQ Plus - FINRA/NYSE TRF.
     DBEQ_PLUS_FINC
         DBEQ Plus - FINRA/Nasdaq TRF Chicago.
     IFEU_IMPACT_IFEU
@@ -861,9 +879,9 @@ class Publisher(StringyMixin, str, Enum):
     DBEQ_MAX_XNYS
         DBEQ Max - NYSE.
     DBEQ_MAX_FINN
-        DBEQ Max - FINRA/NYSE TRF.
-    DBEQ_MAX_FINY
         DBEQ Max - FINRA/Nasdaq TRF Carteret.
+    DBEQ_MAX_FINY
+        DBEQ Max - FINRA/NYSE TRF.
     DBEQ_MAX_FINC
         DBEQ Max - FINRA/Nasdaq TRF Chicago.
     DBEQ_MAX_BATS
@@ -886,6 +904,16 @@ class Publisher(StringyMixin, str, Enum):
         DBEQ Max - NYSE Arca.
     DBEQ_MAX_LTSE
         DBEQ Max - Long-Term Stock Exchange.
+    XNAS_BASIC_XNAS
+        Nasdaq Basic - Nasdaq.
+    XNAS_BASIC_FINN
+        Nasdaq Basic - FINRA/Nasdaq TRF Carteret.
+    XNAS_BASIC_FINC
+        Nasdaq Basic - FINRA/Nasdaq TRF Chicago.
+    IFEU_IMPACT_XOFF
+        ICE Futures Europe - Off-Market Trades.
+    NDEX_IMPACT_XOFF
+        ICE Endex - Off-Market Trades.
 
     """
 
@@ -969,6 +997,11 @@ class Publisher(StringyMixin, str, Enum):
     DBEQ_MAX_XASE = "DBEQ.MAX.XASE"
     DBEQ_MAX_ARCX = "DBEQ.MAX.ARCX"
     DBEQ_MAX_LTSE = "DBEQ.MAX.LTSE"
+    XNAS_BASIC_XNAS = "XNAS.BASIC.XNAS"
+    XNAS_BASIC_FINN = "XNAS.BASIC.FINN"
+    XNAS_BASIC_FINC = "XNAS.BASIC.FINC"
+    IFEU_IMPACT_XOFF = "IFEU.IMPACT.XOFF"
+    NDEX_IMPACT_XOFF = "NDEX.IMPACT.XOFF"
 
     @classmethod
     def from_int(cls, value: int) -> Publisher:
@@ -1135,6 +1168,16 @@ def from_int(cls, value: int) -> Publisher:
             return Publisher.DBEQ_MAX_ARCX
         if value == 80:
             return Publisher.DBEQ_MAX_LTSE
+        if value == 81:
+            return Publisher.XNAS_BASIC_XNAS
+        if value == 82:
+            return Publisher.XNAS_BASIC_FINN
+        if value == 83:
+            return Publisher.XNAS_BASIC_FINC
+        if value == 84:
+            return Publisher.IFEU_IMPACT_XOFF
+        if value == 85:
+            return Publisher.NDEX_IMPACT_XOFF
         raise ValueError(f"Integer value {value} does not correspond with any Publisher variant")
 
     def to_int(self) -> int:
@@ -1301,6 +1344,16 @@ def to_int(self) -> int:
             return 79
         if self == Publisher.DBEQ_MAX_LTSE:
             return 80
+        if self == Publisher.XNAS_BASIC_XNAS:
+            return 81
+        if self == Publisher.XNAS_BASIC_FINN:
+            return 82
+        if self == Publisher.XNAS_BASIC_FINC:
+            return 83
+        if self == Publisher.IFEU_IMPACT_XOFF:
+            return 84
+        if self == Publisher.NDEX_IMPACT_XOFF:
+            return 85
         raise ValueError("Invalid Publisher")
 
     @property
@@ -1468,6 +1521,16 @@ def venue(self) -> Venue:
             return Venue.ARCX
         if self == Publisher.DBEQ_MAX_LTSE:
             return Venue.LTSE
+        if self == Publisher.XNAS_BASIC_XNAS:
+            return Venue.XNAS
+        if self == Publisher.XNAS_BASIC_FINN:
+            return Venue.FINN
+        if self == Publisher.XNAS_BASIC_FINC:
+            return Venue.FINC
+        if self == Publisher.IFEU_IMPACT_XOFF:
+            return Venue.XOFF
+        if self == Publisher.NDEX_IMPACT_XOFF:
+            return Venue.XOFF
         raise ValueError("Unexpected Publisher value")
 
     @property
@@ -1635,6 +1698,16 @@ def dataset(self) -> Dataset:
             return Dataset.DBEQ_MAX
         if self == Publisher.DBEQ_MAX_LTSE:
             return Dataset.DBEQ_MAX
+        if self == Publisher.XNAS_BASIC_XNAS:
+            return Dataset.XNAS_BASIC
+        if self == Publisher.XNAS_BASIC_FINN:
+            return Dataset.XNAS_BASIC
+        if self == Publisher.XNAS_BASIC_FINC:
+            return Dataset.XNAS_BASIC
+        if self == Publisher.IFEU_IMPACT_XOFF:
+            return Dataset.IFEU_IMPACT
+        if self == Publisher.NDEX_IMPACT_XOFF:
+            return Dataset.NDEX_IMPACT
         raise ValueError("Unexpected Publisher value")
 
     @property
@@ -1749,9 +1822,9 @@ def description(self) -> str:
         if self == Publisher.DBEQ_PLUS_XNYS:
             return "DBEQ Plus - NYSE"
         if self == Publisher.DBEQ_PLUS_FINN:
-            return "DBEQ Plus - FINRA/NYSE TRF"
-        if self == Publisher.DBEQ_PLUS_FINY:
             return "DBEQ Plus - FINRA/Nasdaq TRF Carteret"
+        if self == Publisher.DBEQ_PLUS_FINY:
+            return "DBEQ Plus - FINRA/NYSE TRF"
         if self == Publisher.DBEQ_PLUS_FINC:
             return "DBEQ Plus - FINRA/Nasdaq TRF Chicago"
         if self == Publisher.IFEU_IMPACT_IFEU:
@@ -1777,9 +1850,9 @@ def description(self) -> str:
         if self == Publisher.DBEQ_MAX_XNYS:
             return "DBEQ Max - NYSE"
         if self == Publisher.DBEQ_MAX_FINN:
-            return "DBEQ Max - FINRA/NYSE TRF"
-        if self == Publisher.DBEQ_MAX_FINY:
             return "DBEQ Max - FINRA/Nasdaq TRF Carteret"
+        if self == Publisher.DBEQ_MAX_FINY:
+            return "DBEQ Max - FINRA/NYSE TRF"
         if self == Publisher.DBEQ_MAX_FINC:
             return "DBEQ Max - FINRA/Nasdaq TRF Chicago"
         if self == Publisher.DBEQ_MAX_BATS:
@@ -1802,4 +1875,14 @@ def description(self) -> str:
             return "DBEQ Max - NYSE Arca"
         if self == Publisher.DBEQ_MAX_LTSE:
             return "DBEQ Max - Long-Term Stock Exchange"
+        if self == Publisher.XNAS_BASIC_XNAS:
+            return "Nasdaq Basic - Nasdaq"
+        if self == Publisher.XNAS_BASIC_FINN:
+            return "Nasdaq Basic - FINRA/Nasdaq TRF Carteret"
+        if self == Publisher.XNAS_BASIC_FINC:
+            return "Nasdaq Basic - FINRA/Nasdaq TRF Chicago"
+        if self == Publisher.IFEU_IMPACT_XOFF:
+            return "ICE Futures Europe - Off-Market Trades"
+        if self == Publisher.NDEX_IMPACT_XOFF:
+            return "ICE Endex - Off-Market Trades"
         raise ValueError("Unexpected Publisher value")

databento/common/types.py

@@ -9,7 +9,7 @@
 
 
 DBNRecord = Union[
-    databento_dbn.CbboMsg,
+    databento_dbn.CBBOMsg,
     databento_dbn.MBOMsg,
     databento_dbn.MBP1Msg,
     databento_dbn.MBP10Msg,

databento/common/validation.py

@@ -8,6 +8,8 @@
 from urllib.parse import urlsplit
 from urllib.parse import urlunsplit
 
+from databento_dbn import DBNError
+
 
 E = TypeVar("E", bound=Enum)
 
@@ -109,7 +111,7 @@ def validate_enum(
     """
     try:
         return enum(value)
-    except ValueError:
+    except (ValueError, DBNError):
         if hasattr(enum, "variants"):
             valid = list(map(str, enum.variants()))  # type: ignore [attr-defined]
         else:

databento/historical/http.py

@@ -46,8 +46,7 @@ def _check_api_key(self) -> None:
         if self._key == "YOUR_API_KEY":
             raise ValueError(
                 "The API key is currently set to 'YOUR_API_KEY'. "
-                "Please replace this value with a valid API key. "
-                "You can find these through your Databento user portal.",
+                "Please replace this value with a key from your user portal https://databento.com/portal/keys",
             )
 
     def _get(