VER: Release 0.2.1

.github/workflows/build.yml

@@ -13,7 +13,7 @@ jobs:
       matrix:
         arch: [x64, ARM64]
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
     name: build - Python ${{ matrix.python-version }} (${{ matrix.arch }} ${{ matrix.os }})
     runs-on: ${{ matrix.os }}
 

.github/workflows/release.yml

@@ -13,7 +13,7 @@ on:
 jobs:
   tag-release:
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    name: tag-release - Python 3.10 (ubuntu-latest)
+    name: tag-release - Python 3.11 (ubuntu-latest)
     runs-on: ubuntu-latest
     outputs:
       upload_url: ${{ steps.create-release.outputs.upload_url }}
@@ -38,7 +38,7 @@ jobs:
       - name: Set up Python environment
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       # Install build dependencies
       - name: Install build dependencies
@@ -89,7 +89,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
     runs-on: macos-latest
     steps:
       - name: Checkout repository
@@ -134,7 +134,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
     runs-on: windows-latest
     steps:
       - name: Checkout repository
@@ -174,7 +174,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
         target: [x86_64, aarch64]
     runs-on: ubuntu-latest
     steps:
@@ -215,7 +215,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
         target: [x86_64-unknown-linux-musl, aarch64-unknown-linux-musl]
     runs-on: ubuntu-latest
     steps:

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## 0.2.0 - TBD
+## 0.2.1 - 2022-12-02
+- Add Python DBZ writing example
+- Depend on crates.io version of [databento-defs](https://crates.io/crates/databento-defs)
+
+## 0.2.0 - 2022-11-28
 - Change JSON output to NDJSON
 - Quote nanosecond timestamps in JSON to avoid loss of precision when parsing
 - Change DBZ decoding to use [streaming-iterator](https://crates.io/crates/streaming-iterator)

README.md

@@ -2,6 +2,7 @@
 
 [![build](https://github.com/databento/dbz/actions/workflows/build.yml/badge.svg)](https://github.com/databento/dbz/actions/workflows/build.yml)
 ![license](https://img.shields.io/github/license/databento/dbz?color=blue)
+[![Current Crates.io Version](https://img.shields.io/crates/v/dbz-lib.svg)](https://crates.io/crates/dbz-lib)
 
 A library (`dbz-lib`) and CLI tool (`dbz-cli`) for working with Databento Binary
 Encoding (DBZ) files.

src/dbz-cli/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "dbz-cli"
 authors = ["Databento <support@databento.com>"]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 description = "Command-line utility for converting dbz files to text-based formats"
 default-run = "dbz"
@@ -17,7 +17,7 @@ path = "src/main.rs"
 
 [dependencies]
 # Databento common DBZ library
-dbz-lib = { path = "../dbz-lib" }
+dbz-lib = { path = "../dbz-lib", version = "0.2.1" }
 
 # Error handling
 anyhow = "1.0.58"

src/dbz-cli/README.md

@@ -1,5 +1,9 @@
 # dbz-cli
 
+[![build](https://github.com/databento/dbz/actions/workflows/build.yml/badge.svg)](https://github.com/databento/dbz/actions/workflows/build.yml)
+![license](https://img.shields.io/github/license/databento/dbz?color=blue)
+[![Current Crates.io Version](https://img.shields.io/crates/v/dbz-lib.svg)](https://crates.io/crates/dbz-lib)
+
 This crate provides a CLI tool `dbz` for converting the Databento Binary
 Encoding (DBZ) files to text formats. This tool is heavily inspired by the
 [`zstd` CLI](https://github.com/facebook/zstd).

src/dbz-lib/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "dbz-lib"
 authors = ["Databento <support@databento.com>"]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 description = "Library for working with the Databento Binary Encoding (DBZ) format"
 license = "Apache-2.0"
@@ -19,7 +19,7 @@ python-test = ["pyo3"]
 
 [dependencies]
 # Databento common definitions
-databento-defs = { git = "https://github.com/databento/databento-defs", branch = "dev", features = ["serde"], version = "0.3.0" }
+databento-defs = { version = "0.3.1", features = ["serde"] }
 
 # error handling
 anyhow = "1.0.65"

src/dbz-lib/README.md

@@ -1,5 +1,9 @@
 # dbz-lib
 
+[![build](https://github.com/databento/dbz/actions/workflows/build.yml/badge.svg)](https://github.com/databento/dbz/actions/workflows/build.yml)
+![license](https://img.shields.io/github/license/databento/dbz?color=blue)
+[![Current Crates.io Version](https://img.shields.io/crates/v/dbz-lib.svg)](https://crates.io/crates/dbz-lib)
+
 The official library for working with the Databento Binary Encoding (DBZ) format.
 
 ## Usage
@@ -18,11 +22,9 @@ while let Some(tick) = dbz.next() {
 }
 ```
 
-The documentation provides an overview of all methods and features.
-
 ## Documentation
 
-FIXME: when prepping to release to crates.io
+See [the docs](https://docs.rs/dbz-lib) for more detailed usage.
 
 ## Building
 

src/dbz-lib/src/write/csv.rs

@@ -328,7 +328,7 @@ mod tests {
     use super::*;
     use crate::write::test_data::{VecStream, BID_ASK, RECORD_HEADER};
     use databento_defs::record::{
-        Mbp10Msg, Mbp1Msg, OhlcvMsg, StatusMsg, SymDefMsg, TickMsg, TradeMsg,
+        Mbp10Msg, Mbp1Msg, OhlcvMsg, SecurityUpdateAction, StatusMsg, SymDefMsg, TickMsg, TradeMsg,
     };
     use std::{io::BufWriter, os::raw::c_char};
 
@@ -545,7 +545,7 @@ mod tests {
             settl_price_type: 9,
             sub_fraction: 23,
             underlying_product: 10,
-            security_update_action: 7,
+            security_update_action: SecurityUpdateAction::Invalid,
             maturity_month_month: 8,
             maturity_month_day: 9,
             maturity_month_week: 11,
@@ -559,6 +559,6 @@ mod tests {
         let writer = BufWriter::new(&mut buffer);
         write_csv(writer, VecStream::new(data)).unwrap();
         let line = extract_2nd_line(buffer);
-        assert_eq!(line, format!("{HEADER_CSV},1658441891000000000,100,1000,1698450000000000000,1697350000000000000,1000000,-1000000,0,500000,5,5,10,10,256785,0,0,13,0,10000,1,1000,100,1,0,0,0,0,0,0,0,0,0,4,,USD,,,,,,,,,,,1,2,4,8,9,23,10,7,8,9,11,1,0,5,0"));
+        assert_eq!(line, format!("{HEADER_CSV},1658441891000000000,100,1000,1698450000000000000,1697350000000000000,1000000,-1000000,0,500000,5,5,10,10,256785,0,0,13,0,10000,1,1000,100,1,0,0,0,0,0,0,0,0,0,4,,USD,,,,,,,,,,,1,2,4,8,9,23,10,Invalid,8,9,11,1,0,5,0"));
     }
 }

src/dbz-lib/src/write/json.rs

@@ -65,7 +65,10 @@ mod tests {
     };
     use databento_defs::{
         enums::{Compression, SType, Schema},
-        record::{Mbp10Msg, Mbp1Msg, OhlcvMsg, StatusMsg, SymDefMsg, TickMsg, TradeMsg},
+        record::{
+            Mbp10Msg, Mbp1Msg, OhlcvMsg, SecurityUpdateAction, StatusMsg, SymDefMsg, TickMsg,
+            TradeMsg,
+        },
     };
     use serde_json::ser::CompactFormatter;
 
@@ -308,7 +311,7 @@ mod tests {
             settl_price_type: 9,
             sub_fraction: 23,
             underlying_product: 10,
-            security_update_action: 7,
+            security_update_action: SecurityUpdateAction::Invalid,
             maturity_month_month: 8,
             maturity_month_day: 9,
             maturity_month_week: 11,
@@ -332,7 +335,7 @@ mod tests {
                     r#""open_interest_qty":0,"contract_multiplier":0,"decay_quantity":0,"original_contract_size":0,"related_security_id":0,"trading_reference_date":0,"appl_id":0,"#,
                     r#""maturity_month_year":0,"decay_start_date":0,"chan":4,"currency":"","settl_currency":"USD","secsubtype":"","symbol":"","group":"","exchange":"","asset":"","cfi":"","#,
                     r#""security_type":"","unit_of_measure":"","underlying":"","related":"","match_algorithm":1,"md_security_trading_status":2,"main_fraction":4,"price_display_format":8,"#,
-                    r#""settl_price_type":9,"sub_fraction":23,"underlying_product":10,"security_update_action":7,"maturity_month_month":8,"maturity_month_day":9,"maturity_month_week":11,"#,
+                    r#""settl_price_type":9,"sub_fraction":23,"underlying_product":10,"security_update_action":"Invalid","maturity_month_month":8,"maturity_month_day":9,"maturity_month_week":11,"#,
                     r#""user_defined_instrument":1,"contract_multiplier_unit":0,"flow_schedule_type":5,"tick_rule":0"#
                 )
             )

src/dbz-python/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "dbz-python"
 authors = ["Databento <support@databento.com>"]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 description = "Python library written in Rust for working with the Databento Binary Encoding (DBZ) format"
 license = "Apache-2.0"

src/dbz-python/README.md

@@ -1,6 +1,47 @@
 # dbz-python
 
+[![build](https://github.com/databento/dbz/actions/workflows/build.yml/badge.svg)](https://github.com/databento/dbz/actions/workflows/build.yml)
+![license](https://img.shields.io/github/license/databento/dbz?color=blue)
+![pypi-version](https://img.shields.io/pypi/v/dbz_python)
+
 Python bindings for the `dbz-lib` Rust library.
+Used by the [Databento Python client library](https://github.com/databento/databento-python).
+
+Using this crate is for advanced users and is not fully documented or supported.
+
+## Installation
+
+To install the latest stable version from PyPI:
+```sh
+pip install -U dbz-python
+```
+
+## Usage
+
+To read the metadata from a DBZ file into a `dict`, read the raw bytes and pass them to `decode_metadata`.
+```python
+from dbz_python import decode_metadata
+
+with open("my.dbz", "rb") as fin:
+    metadata = decode_metadata(fin.read())
+# Print symbology mappings
+print(metadata["mappings"])
+```
+
+You can write DBZ files using `write_dbz_file`:
+```python
+from dbz_python import write_dbz_file
+
+records = [
+    {"rtype": 160, "publisher_id": 1, "product_id": 1, "ts_event": 647784973705, "order_id": 1,
+     "price": 3723000000000, "size": 1, "flags": -128, "channel_id": 0, "action": ord('C'),
+     "side": ord('A'), "ts_recv": 1609160400000704060, "ts_in_delta": 0, "sequence": 1170352}
+]
+with open("my.dbz", "wb") as out:
+    write_dbz_file(file=out, schema="mbo", dataset="custom", records=records, stype="product_id")
+```
+Note that the keys in the dictionaries in `records` must match the field names of the schema, or
+the function will raise a `KeyError`.
 
 ## Building