REF: Refactor DBN versioning

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.25.0 - TBD
+
+### Breaking changes
+- Renamed `VersionUpgradePolicy::Upgrade` to `UpgradeToV2` in preparation for a future
+  DBN version 3
+
+### Enhancements
+- Added `v1` and `v2` modules to allow unambiguously referring to the record types for
+  a given DBN version regardless of whether the record type has changed. Previously
+  versioned aliases only existed for record types that have changed between DBN versions
+  - Added identical namespaces to `databento_dbn` Python package
+- Changed `dataset()` method on `MetadataBuilder` to accept an `impl ToString` so now
+  `Dataset` and `&str` can be passed directly
+- Added type aliases for `TBBOMsg`, `BBO1SMsg`, `BBO1MMsg`, `TCBBOMsg`, `CBBO1SMsg`,
+  `CBBO1MMsg` in Python
+
+### Deprecations
+- Deprecated `dataset` module. The top-level `Dataset` enum and its `const` `as_str()`
+  method provide the same functionality for all datasets. This module will be removed in
+  a future version
+
 ## 0.24.0 - 2024-12-10
 
 ### Enhancements

python/python/databento_dbn/_lib.pyi

@@ -784,13 +784,15 @@ class VersionUpgradePolicy(Enum):
 
     AS_IS
         Decode data from previous versions as-is.
-    UPGRADE
-        Decode data from previous versions converting it to the latest version.
+    UPGRADE_TO_V2
+        Decode and convert data from DBN versions prior to version 2 to that version.
+        Attempting to decode data from newer versions (when they're introduced) will
+        fail.
 
     """
 
     AS_IS: int
-    UPGRADE: int
+    UPGRADE_TO_V2: int
 
 class Metadata(SupportsBytes):
     """
@@ -5324,3 +5326,11 @@ def update_encoded_metadata(
         When the file update fails.
 
     """
+
+# Aliases
+TBBOMsg = MBOMsg
+BBO1SMsg = BBOMsg
+BBO1MMsg = BBOMsg
+TCBBOMsg = CMBP1Msg
+CBBO1SMsg = CBBOMsg
+CBBO1MMsg = CBBOMsg

python/python/databento_dbn/v1.py

@@ -0,0 +1,25 @@
+# ruff: noqa: F401, F811
+from ._lib import BBOMsg
+from ._lib import CBBOMsg
+from ._lib import CMBP1Msg
+from ._lib import ErrorMsgV1 as ErrorMsg
+from ._lib import ImbalanceMsg
+from ._lib import InstrumentDefMsgV1 as InstrumentDefMsg
+from ._lib import MBOMsg
+from ._lib import MBP1Msg
+from ._lib import MBP10Msg
+from ._lib import OHLCVMsg
+from ._lib import StatMsg
+from ._lib import StatusMsg
+from ._lib import SymbolMappingMsgV1 as SymbolMappingMsg
+from ._lib import SystemMsgV1 as SystemMsg
+from ._lib import TradeMsg
+
+
+# Aliases
+TBBOMsg = MBOMsg
+BBO1SMsg = BBOMsg
+BBO1MMsg = BBOMsg
+TCBBOMsg = CMBP1Msg
+CBBO1SMsg = CBBOMsg
+CBBO1MMsg = CBBOMsg

python/python/databento_dbn/v2.py

@@ -0,0 +1,25 @@
+# ruff: noqa: F401, F811
+from ._lib import BBOMsg
+from ._lib import CBBOMsg
+from ._lib import CMBP1Msg
+from ._lib import ErrorMsg
+from ._lib import ImbalanceMsg
+from ._lib import InstrumentDefMsg
+from ._lib import MBOMsg
+from ._lib import MBP1Msg
+from ._lib import MBP10Msg
+from ._lib import OHLCVMsg
+from ._lib import StatMsg
+from ._lib import StatusMsg
+from ._lib import SymbolMappingMsg
+from ._lib import SystemMsg
+from ._lib import TradeMsg
+
+
+# Aliases
+TBBOMsg = MBOMsg
+BBO1SMsg = BBOMsg
+BBO1MMsg = BBOMsg
+TCBBOMsg = CMBP1Msg
+CBBO1SMsg = CBBOMsg
+CBBO1MMsg = CBBOMsg

python/src/dbn_decoder.rs

@@ -129,11 +129,10 @@ impl DbnDecoder {
 #[cfg(test)]
 mod tests {
     use dbn::{
-        datasets::XNAS_ITCH,
         encode::{dbn::Encoder, EncodeRecord},
         enums::{rtype, SType, Schema},
         record::{ErrorMsg, OhlcvMsg, RecordHeader},
-        MetadataBuilder, DBN_VERSION,
+        Dataset, MetadataBuilder, DBN_VERSION,
     };
     use pyo3::{py_run, types::PyString};
 
@@ -148,7 +147,7 @@ mod tests {
         let mut encoder = Encoder::new(
             buffer,
             &MetadataBuilder::new()
-                .dataset(XNAS_ITCH.to_owned())
+                .dataset(Dataset::XnasItch.to_string())
                 .schema(Some(Schema::Trades))
                 .stype_in(Some(SType::RawSymbol))
                 .stype_out(SType::InstrumentId)
@@ -191,7 +190,7 @@ mod tests {
         let mut encoder = Encoder::new(
             buffer,
             &MetadataBuilder::new()
-                .dataset(XNAS_ITCH.to_owned())
+                .dataset(Dataset::XnasItch.to_string())
                 .schema(Some(Schema::Ohlcv1S))
                 .stype_in(Some(SType::RawSymbol))
                 .stype_out(SType::InstrumentId)

python/src/transcoder.rs

@@ -454,10 +454,9 @@ mod tests {
     use std::{io::Read, num::NonZeroU64};
 
     use dbn::{
-        datasets::XNAS_ITCH,
         encode::{DbnEncoder, EncodeRecord},
-        rtype, ErrorMsg, MappingInterval, MetadataBuilder, OhlcvMsg, RecordHeader, SType, Schema,
-        SymbolMapping, SymbolMappingMsg, WithTsOut, DBN_VERSION, UNDEF_TIMESTAMP,
+        rtype, Dataset, ErrorMsg, MappingInterval, MetadataBuilder, OhlcvMsg, RecordHeader, SType,
+        Schema, SymbolMapping, SymbolMappingMsg, WithTsOut, DBN_VERSION, UNDEF_TIMESTAMP,
     };
     use rstest::rstest;
     use time::macros::{date, datetime};
@@ -508,7 +507,7 @@ mod tests {
         let mut encoder = DbnEncoder::new(
             Vec::new(),
             &MetadataBuilder::new()
-                .dataset(XNAS_ITCH.to_owned())
+                .dataset(Dataset::XnasItch.to_string())
                 .schema(Some(Schema::Trades))
                 .stype_in(Some(SType::RawSymbol))
                 .stype_out(SType::InstrumentId)
@@ -579,7 +578,7 @@ mod tests {
         let mut encoder = DbnEncoder::new(
             buffer,
             &MetadataBuilder::new()
-                .dataset(XNAS_ITCH.to_owned())
+                .dataset(Dataset::XnasItch.to_string())
                 .schema(Some(Schema::Ohlcv1S))
                 .stype_in(Some(SType::RawSymbol))
                 .stype_out(SType::InstrumentId)
@@ -657,7 +656,7 @@ mod tests {
         let mut encoder = DbnEncoder::new(
             buffer,
             &MetadataBuilder::new()
-                .dataset(XNAS_ITCH.to_owned())
+                .dataset(Dataset::XnasItch.to_string())
                 .schema(Some(Schema::Ohlcv1S))
                 .stype_in(Some(SType::RawSymbol))
                 .stype_out(SType::InstrumentId)
@@ -783,7 +782,7 @@ mod tests {
         let mut encoder = DbnEncoder::new(
             buffer,
             &MetadataBuilder::new()
-                .dataset(XNAS_ITCH.to_owned())
+                .dataset(Dataset::XnasItch.to_string())
                 .schema(None) // Live: mixed schema
                 .stype_in(Some(SType::RawSymbol))
                 .stype_out(SType::InstrumentId)

rust/dbn-cli/src/lib.rs

@@ -204,7 +204,7 @@ impl Args {
 
     pub fn upgrade_policy(&self) -> VersionUpgradePolicy {
         if self.should_upgrade {
-            VersionUpgradePolicy::Upgrade
+            VersionUpgradePolicy::UpgradeToV2
         } else {
             VersionUpgradePolicy::AsIs
         }