hft-lob 0.1.2

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]

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

  hft_lob /data/orderflow.bin 12345 100000
  

• 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).

---

🤖 Built by AI, for Developers

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.

---

📝 Example: Calling from Python Script

import subprocess

def query_orderbook(file_path):
    result = subprocess.run(["hft_lob", file_path], capture_output=True, text=True)
    print(result.stdout)

query_orderbook("/path/to/orderflow.bin")

---

🧑‍💻 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!

---

📫 Questions?

• For issues or feature requests, open a GitHub issue.
• For extension to other platforms (Mac/Windows), see the comments in hft_lob/cli.py or [contact the maintainer].

---

Enjoy high-performance orderbook analytics from anywhere with just Python and pip!