DOC: Clarify flags field meaning in multidocs

Author: Zach Banks

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## TBD
+- Updated `Flags` enum
+
 ## 0.6.0 - 2022-12-02
 - Added `metadata.get_dataset_condition` method to `Historical` client
 - Upgraded `dbz-python` to `0.2.0`

databento/common/enums.py

@@ -134,11 +134,9 @@ class SymbologyResolution(Enum):
 class Flags(Enum):
     """Represents record flags."""
 
-    F_LAST = 1 << 7  # 128  Last msg in packet (flags < 0)
-    F_HALT = 1 << 6  # 64  Exchange-independent HALT signal
-    F_RESET = 1 << 5  # 32  Drop book, reset symbol for this exchange
-    F_DUPID = 1 << 4  # 16  This OrderID has valid fresh duplicate (Iceberg, etc)
-    F_MBP = 1 << 3  # 8  This is SIP/MBP ADD message, single per price level
-    F_RESERVED2 = 1 << 2  # 4 Reserved for future use
-    F_RESERVED1 = 1 << 1  # 2 Reserved for future use
-    F_RESERVED0 = 1  # Reserved for future use
+    # Last message in the packet from the venue for a given `product_id`
+    F_LAST = 1 << 7
+    # Aggregated price level message, not an individual order
+    F_MBP = 1 << 4
+    # The `ts_recv` value is inaccurate (clock issues or reordering)
+    F_BAD_TS_RECV = 1 << 3

databento/common/parsing.py

@@ -283,14 +283,11 @@ def parse_flags(value: int, apply_bitmask: bool = False) -> List[str]:
     flag represented by a single integer.
 
     Possible values include:
-     - F_LAST: Last msg in packet (flags < 0).
-     - F_HALT: Exchange-independent HALT signal.
-     - F_RESET: Drop book, reset symbol for this exchange.
-     - F_DUPID: This OrderID has valid fresh duplicate (Iceberg, etc).
-     - F_MBP: This is SIP/MBP ADD message, single per price level.
-     - F_RESERVED2: Reserved for future use (no current meaning).
-     - F_RESERVED1: Reserved for future use (no current meaning).
-     - F_RESERVED0: Reserved for future use (no current meaning).
+     - F_LAST: Last message in the packet from the venue for a given `product_id`
+     - F_MBP: Aggregated price level message, not an individual order
+     - F_BAD_TS_RECV: The `ts_recv` value is inaccurate (clock issues or reordering)
+
+    Other bits are reserved and have no current meaning.
 
     Parameters
     ----------

tests/test_common_parsing.py

@@ -229,9 +229,12 @@ def test_maybe_datetime_to_string_give_valid_values_returns_expected_results(
         "value, expected",
         [
             [Flags.F_LAST.value, ["F_LAST"]],
-            [Flags.F_DUPID.value | Flags.F_LAST.value, ["F_LAST", "F_DUPID"]],
+            [
+                Flags.F_BAD_TS_RECV.value | Flags.F_LAST.value,
+                ["F_LAST", "F_BAD_TS_RECV"],
+            ],
             [128, ["F_LAST"]],
-            [129, ["F_LAST", "F_RESERVED0"]],
+            [136, ["F_LAST", "F_BAD_TS_RECV"]],
         ],
     )
     def test_parse_flags_given_valid_values_returns_expected_results(