Metadata-Version: 2.4
Name: hft_lob
Version: 0.1.4
Summary: Python wrapper for a high-performance Rust orderbook CLI.
Home-page: https://github.com/pratima/hft_lob
Author: Pratima Kumari
Author-email: pratima.kumari@example.com
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-python
Dynamic: summary


# 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

```sh
pip install hft_lob
```
Or, for local development:
```sh
pip install .
```

---

##  Usage

After installation, simply run:
```sh
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:
  ```sh
  hft_lob /data/orderflow.bin 12345 
  ```
- To see available options:
  ```sh
  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](#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

```python
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!

---
 
