hft-lob 0.1.6

Python wrapper for a high-performance Rust orderbook CLI.

hft_lob

A blazing-fast Python CLI package for high-frequency trading research, powered by a Rust-based Limit Order Book (LOB) engine. Run a high-performance orderbook from your terminal with a single pip install—no Rust toolchain required!

---

Project Structure

hft_lob/
    __init__.py                # Marks this directory as a Python package (empty or with package-level docstring)
    cli.py                     # Python CLI entrypoint; launches the Rust binary
    bin/
        orderbook-linux-x86_64 # The compiled Rust LOB engine (Linux x86_64)
setup.py                       # Python packaging script (includes README for PyPI)
pyproject.toml                 # Build system requirements for PEP 517/518
README.md                      # This documentation file

File & Folder Explanations

• hft_lob/: Main Python package directory.
  • init.py: Marks the directory as a package. Can be empty or contain package-level docstrings.
  • cli.py: The Python script that acts as the CLI entrypoint. When you run hft_lob from the terminal, this script is executed. It locates the Rust binary and runs it with any arguments you provide.
  • bin/orderbook-linux-x86_64: The actual Rust-compiled orderbook engine. This is the core logic, optimized for speed and reliability. The Python CLI simply launches this binary.
• setup.py: Standard Python packaging script. It:
  • Reads your README.md for the PyPI long description (so your PyPI page looks great).
  • Declares the CLI entrypoint (hft_lob command).
  • Ensures the Rust binary is included in the package.
• pyproject.toml: Declares build system requirements (setuptools) for modern Python packaging.
• README.md: This file. Explains usage, structure, and development details.

---

Features

• Ultra-fast: All orderbook logic runs in Rust for maximum performance.
• Zero Rust required: End users only need Python and pip.
• CLI-first: Installs a terminal command (hft_lob) for direct use.
• Easy distribution: No C-extensions or Python bindings—just a subprocess call to the Rust binary.
• Portable: Works on Linux x86_64 (matching the bundled binary).

---

Installation

pip install hft_lob

Or, for local development:

pip install .

---

Usage

After installation, simply run:

hft_lob /path/to/datafile.bin [optional:token] [optional:max_messages]
Example - hft_lob /nas/50.30/NSE_CM/Feed_CM_StreamID_2_30_03_2026.bin 1333(specific token) > orderbook.csv 

• All arguments are passed directly to the Rust binary.
• Example:

  hft_lob /data/orderflow.bin 12345 
  

• To see available options:

  hft_lob --help
  

---

How it Works

• The Python CLI (hft_lob/cli.py) uses subprocess to launch the Rust binary (bin/orderbook-linux-x86_64).
• No Python-to-Rust bindings: all heavy lifting is done in Rust, Python just acts as a launcher.
• This design ensures maximum speed, minimal dependencies, and easy packaging.

---

Development & Packaging

• To update the Rust binary, simply replace hft_lob/bin/orderbook-linux-x86_64 with your new build.
• The setup.py script ensures the binary is included in the package and that the README is shown on PyPI.
• The project uses modern Python packaging standards (pyproject.toml).

---

This project structure and packaging approach is designed for reliability, performance, and ease of use—leveraging best practices from both the Python and Rust ecosystems.

---

Platform

Currently supported:

• Linux x86_64 (if you want Mac/Windows support, you must build and bundle those binaries separately—contact the maintainer or see Advanced Use below).

---

Advanced Use

• If you need to call the Rust logic from your own Python code, just use Python’s subprocess module to call hft_lob with any arguments and parse the output.
• For Mac or Windows, build your Rust binary for your OS, place it in hft_lob/bin/, and update cli.py to detect the platform and select the correct binary.

---

def query_orderbook(file_path):

Example: Calling from Python Code

You can also call the Rust orderbook engine directly from Python using the provided function:

from hft_lob.cli import get_lob_for_token

# Provide the path to your data file and the token you want to query
file_path = "/path/to/orderflow.bin"
token = 1333  # Replace with your token

lob_output = get_lob_for_token(file_path, token)
print(lob_output)

This function runs the Rust binary and returns the LOB output as a string. You can use any file path and token as parameters.

---

Reader Function Feature

You can use a reader function to process the output of the Rust binary line by line or in a streaming fashion. This is useful for handling large files or integrating with other Python code.

Example Usage

from hft_lob.cli import run_with_reader

def my_reader(line):
  # Process each line from the Rust binary output
  print("Read line:", line)

file_path = "/path/to/orderflow.bin"
run_with_reader(file_path, reader=my_reader)

Replace my_reader with your own function to handle each line as needed. This allows for efficient processing of large outputs without loading everything into memory.

---

Development

1. Clone this repo.
2. Build your Rust binary (cargo build --release).
3. Copy the binary to hft_lob/bin/orderbook-linux-x86_64.
4. Install with pip install ..
5. Run hft_lob from your terminal!

---