{"id":6339,"library":"databento-dbn","title":"Databento Binary Encoding (DBN) Python Bindings","description":"Python bindings for encoding and decoding Databento Binary Encoding (DBN). This library provides efficient Rust-backed functionality for working with DBN data streams and files, offering features like record buffering, mutable record references, and direct access to timestamp fields. As of version 0.54.0, it includes enhancements for dynamic record types and improved memory management. Releases occur frequently, typically on a monthly or bi-monthly basis.","status":"active","version":"0.54.0","language":"en","source_language":"en","source_url":"https://github.com/databento/dbn","tags":["data-serialization","financial-data","binary-encoding","high-performance"],"install":[{"cmd":"pip install databento-dbn","lang":"bash","label":"Install `databento-dbn`"}],"dependencies":[],"imports":[{"symbol":"DBNDecoder","correct":"from databento_dbn import DBNDecoder"},{"symbol":"DBNEncoder","correct":"from databento_dbn import DBNEncoder"},{"symbol":"Metadata","correct":"from databento_dbn import Metadata"},{"symbol":"MBO","correct":"from databento_dbn import MBO"},{"symbol":"Trades","correct":"from databento_dbn import Trades"},{"note":"`Record` was removed as a union type alias in v0.46.0; use `DBNRecord` instead.","wrong":"from databento_dbn import Record","symbol":"DBNRecord","correct":"from databento_dbn import DBNRecord"},{"symbol":"UNDEF_TIMESTAMP","correct":"from databento_dbn import UNDEF_TIMESTAMP"}],"quickstart":{"code":"import io\nimport datetime\nfrom databento_dbn import DBNDecoder, DBNEncoder, Metadata, Schema, SType, Compression, MBO, UNDEF_TIMESTAMP\n\nNANO_SECONDS_IN_SECOND = 1_000_000_000\n\ndef to_nanos(dt: datetime.datetime) -> int:\n    \"Convert datetime object to nanoseconds since Unix epoch.\"\n    return int(dt.timestamp() * NANO_SECONDS_IN_SECOND)\n\n# 1. Create DBN metadata\nmetadata = Metadata(\n    version=3,\n    dataset=\"GLBX.MDP3\",\n    schema=Schema.MBO,\n    stype_in=SType.RAW_SYMBOL,\n    stype_out=SType.INSTRUMENT_ID,\n    start=to_nanos(datetime.datetime(2024, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc)),\n    end=to_nanos(datetime.datetime(2024, 1, 1, 0, 0, 1, tzinfo=datetime.timezone.utc)),\n    symbols=[\"ES.c.0\"],\n    partial=[0],\n    not_found=[0],\n    mappings=[],\n    ts_out=False, # Set to False for this example to show UNDEF_TIMESTAMP\n    compression=Compression.NONE,\n)\n\n# 2. Encode a sample MBO record into DBN bytes\nencoder = DBNEncoder(metadata=metadata, upgrade_records=True)\nsample_mbo = MBO(\n    publisher_id=1,\n    instrument_id=12345,\n    ts_event=to_nanos(datetime.datetime(2024, 1, 1, 0, 0, 0, 123456789, tzinfo=datetime.timezone.utc)),\n    action=b'A',\n    side=b'B',\n    price=100_00_000_000_000, # Represents 100.00 in fixed-point nanodollars\n    size=10,\n    depth=0,\n    is_snapshot=1,\n    ts_in_delta=0,\n    sequence=1,\n    booklevel=0,\n    flags=0,\n    display_qty=10,\n    orders_count=1,\n    ts_recv=to_nanos(datetime.datetime(2024, 1, 1, 0, 0, 0, 123456789, tzinfo=datetime.timezone.utc)),\n    trade_size=0,\n    trade_id=0,\n    mbp_flags=0,\n    channel_id=0,\n)\nencoded_bytes = encoder.encode_record(sample_mbo)\nencoded_bytes += encoder.finish() # Finalize the stream\n\nprint(f\"Encoded {len(encoded_bytes)} bytes of DBN data.\")\n\n# 3. Decode the DBN data from bytes\ndecoder = DBNDecoder()\ndecoded_records = []\nfor record in decoder.decode(encoded_bytes):\n    decoded_records.append(record)\n\nprint(f\"\\nDecoded {len(decoded_records)} records from raw bytes.\")\nfor record in decoded_records:\n    print(record)\n    if isinstance(record, MBO):\n        print(f\"  MBO Record: Instrument ID={record.instrument_id}, Price={record.price / NANO_SECONDS_IN_SECOND:.2f}, Size={record.size}\")\n        if record.ts_out == UNDEF_TIMESTAMP:\n            print(\"  ts_out is undefined (as expected for this metadata configuration)\")\n\n# 4. Decode the DBN data from a file-like object\ndbn_io = io.BytesIO(encoded_bytes)\nfile_decoder = DBNDecoder()\nfile_records = []\nfor record in file_decoder.decode(dbn_io):\n    file_records.append(record)\nprint(f\"\\nDecoded {len(file_records)} records from BytesIO.\")","lang":"python","description":"This quickstart demonstrates how to encode a DBN record from Python objects and then decode the resulting DBN bytes. It covers creating metadata, encoding an MBO record, and decoding from both raw bytes and a file-like object. It also highlights checking for `UNDEF_TIMESTAMP` for fields like `ts_out`."},"warnings":[{"fix":"Access `record.ts_out` directly. Its value will be `databento_dbn.UNDEF_TIMESTAMP` if not set. Avoid relying on `record.__dict__` for record attributes.","message":"The `ts_out` attribute on all Python record types changed from a dynamic `__dict__` attribute to a permanent `int` field. Simultaneously, `__dict__` was removed from all Python record classes.","severity":"breaking","affected_versions":"<0.53.0"},{"fix":"Update type hints and `isinstance` checks to use `DBNRecord` instead of `Record` (e.g., `isinstance(rec, DBNRecord)`).","message":"The `Record` class was removed from Python type stubs (it was never a true base class in runtime). `DBNRecord` union type was introduced as its replacement for type hinting all DBN record types.","severity":"breaking","affected_versions":"<0.46.0"},{"fix":"For explicit version-specific types, import from `databento_dbn.v1`, `databento_dbn.v2`, or `databento_dbn.v3` (e.g., `from databento_dbn.v3 import MBO`). When working with decoded records, use `getattr()` or handle `AttributeError` for potentially missing fields if the DBN version is unknown.","message":"DBN records may have different fields or structures across DBN versions (v1, v2, v3). While `DBNDecoder` handles this automatically, direct instantiation or field access of record types might need to consider version compatibility.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}