Metadata-Version: 2.4
Name: OrderPulse
Version: 0.2.20
Summary: High-performance exchange feed parser and orderflow analytics engine with Rust and Python bindings
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# fastreader

High-performance Rust + PyO3 library for reading binary market data and generating order book snapshots directly from Python.

`fastreader` is designed for Python quant developers who need:

* Fast binary message parsing
* Order and trade message inspection
* Token-level filtering
* Sequential message streaming
* Order book reconstruction
* Top-of-book / depth snapshot generation

The library is implemented in Rust for speed and exposed to Python using `PyO3`.

---

# Features

* Parse binary market feed files
* Read order and trade messages
* Filter data by token/instrument
* Sequential message iteration
* Generate order book snapshots
* Configurable market depth
* Fast memory-efficient Rust backend
* Python-friendly API

---

# Installation

## Build Using maturin

```bash
pip install maturin
maturin develop --release
```

OR build wheel:

```bash
maturin build --release
```

---

# Python Import

```python
import fastreader
```

---

# Main Classes

| Class                | Description                        |
| -------------------- | ---------------------------------- |
| `BinaryDataLoader`   | Loads and reads binary market data |
| `OrderBookGenerator` | Generates order book snapshots     |

---

# BinaryDataLoader

The `BinaryDataLoader` class loads binary feed data into memory and provides utilities to inspect messages.

---

## Constructor

```python
BinaryDataLoader(path, token=None)
```

### Parameters

| Parameter | Type            | Description                      |
| --------- | --------------- | -------------------------------- |
| `path`    | `str`           | Path to binary market data file  |
| `token`   | `int` or `None` | Optional instrument token filter |

---

## Example

```python
from fastreader import BinaryDataLoader

loader = BinaryDataLoader(
    path="data/feed.bin",
    token=26000
)
```

---

# BinaryDataLoader Functions

---

## total_messages()

Returns total number of messages loaded.

### Returns

```python
int
```

### Example

```python
count = loader.total_messages()
print(count)
```

---

## total_orders()

Returns total order messages.

### Returns

```python
int
```

### Example

```python
orders = loader.total_orders()
print(orders)
```

---

## total_trades()

Returns total trade messages.

### Returns

```python
int
```

### Example

```python
trades = loader.total_trades()
print(trades)
```

---

## summary()

Returns formatted dataset summary.

### Returns

```python
str
```

### Example

```python
print(loader.summary())
```

### Sample Output

```text
Total Messages: 250000
Total Orders: 180000
Total Trades: 70000
```

---

## reset_cursor()

Resets internal sequential message cursor.

Useful when using `get_next_message()`.

### Example

```python
loader.reset_cursor()
```

---

## get_all_messages(limit=None)

Returns all messages as formatted strings.

### Parameters

| Parameter | Type            | Description                |
| --------- | --------------- | -------------------------- |
| `limit`   | `int` or `None` | Maximum messages to return |

### Returns

```python
List[str]
```

### Example

```python
messages = loader.get_all_messages(limit=5)

for msg in messages:
    print(msg)
```

### Sample Output

```text
Order Message: SeqNo1, msg_len64 ...
Trade Message: SeqNo2, msg_len48 ...
```

---

## get_order_messages(limit=None)

Returns only order messages.

### Parameters

| Parameter | Type            | Description                |
| --------- | --------------- | -------------------------- |
| `limit`   | `int` or `None` | Maximum messages to return |

### Returns

```python
List[str]
```

### Example

```python
orders = loader.get_order_messages(limit=10)

for order in orders:
    print(order)
```

---

## get_trade_messages(limit=None)

Returns only trade messages.

### Parameters

| Parameter | Type            | Description                |
| --------- | --------------- | -------------------------- |
| `limit`   | `int` or `None` | Maximum messages to return |

### Returns

```python
List[str]
```

### Example

```python
trades = loader.get_trade_messages(limit=10)

for trade in trades:
    print(trade)
```

---

## get_next_message()

Returns next message sequentially.

Internal cursor automatically moves forward after each call.

### Returns

```python
str
```

Returns:

* Message string
* `"END"` when all messages are consumed

### Example

```python
while True:
    msg = loader.get_next_message()

    if msg == "END":
        break

    print(msg)
```

---

# OrderBookGenerator

The `OrderBookGenerator` reconstructs order books from order/trade messages.

It produces snapshot rows with configurable market depth.

---

# Constructor

```python
OrderBookGenerator(depth=5)
```

### Parameters

| Parameter | Type  | Description              |
| --------- | ----- | ------------------------ |
| `depth`   | `int` | Number of bid/ask levels |

---

## Example

```python
from fastreader import OrderBookGenerator

ob = OrderBookGenerator(depth=5)
```

---

# OrderBookGenerator Functions

---

## reset()

Resets internal order book state.

### Example

```python
ob.reset()
```

---

## header()

Returns CSV-style order book header.

### Returns

```python
str
```

### Example

```python
print(ob.header())
```

### Sample Output

```text
local_ts,exch_ts,mid_price,bid_price_0,bid_qty_0,ask_price_0,ask_qty_0
```

---

## create_orderbook(store)

Default order book generation method.

Internally calls:

```python
create_orderbook_from_all_messages()
```

### Parameters

| Parameter | Type               | Description           |
| --------- | ------------------ | --------------------- |
| `store`   | `BinaryDataLoader` | Loaded binary dataset |

### Returns

```python
List[str]
```

### Example

```python
rows = ob.create_orderbook(loader)

for row in rows[:5]:
    print(row)
```

---

## create_orderbook_from_all_messages(store)

Generates order book snapshots using:

* Order messages
* Trade messages

### Parameters

| Parameter | Type               | Description           |
| --------- | ------------------ | --------------------- |
| `store`   | `BinaryDataLoader` | Loaded binary dataset |

### Returns

```python
List[str]
```

### Example

```python
rows = ob.create_orderbook_from_all_messages(loader)
```

---

## create_orderbook_from_trade_messages(store)

Generates snapshots using only trade messages.

### Parameters

| Parameter | Type               | Description           |
| --------- | ------------------ | --------------------- |
| `store`   | `BinaryDataLoader` | Loaded binary dataset |

### Returns

```python
List[str]
```

### Example

```python
trade_rows = ob.create_orderbook_from_trade_messages(loader)
```

---

## create_orderbook_from_next_messages(store)

Generates order book sequentially using cursor-based streaming.

Useful for:

* Streaming simulations
* Backtesting engines
* Sequential replay systems

### Parameters

| Parameter | Type               | Description           |
| --------- | ------------------ | --------------------- |
| `store`   | `BinaryDataLoader` | Loaded binary dataset |

### Returns

```python
List[str]
```

### Example

```python
loader.reset_cursor()

rows = ob.create_orderbook_from_next_messages(loader)
```

---

## row_count_from_all_messages(store)

Returns total generated snapshot rows.

### Parameters

| Parameter | Type               | Description           |
| --------- | ------------------ | --------------------- |
| `store`   | `BinaryDataLoader` | Loaded binary dataset |

### Returns

```python
int
```

### Example

```python
count = ob.row_count_from_all_messages(loader)
print(count)
```

---

# Complete Python Example

```python
from fastreader import BinaryDataLoader
from fastreader import OrderBookGenerator

# Load binary feed
loader = BinaryDataLoader(
    path="data/feed.bin",
    token=26000
)

# Dataset information
print(loader.summary())

# Print first 5 messages
messages = loader.get_all_messages(limit=5)

for msg in messages:
    print(msg)

# Create order book generator
ob = OrderBookGenerator(depth=5)

# Generate snapshots
rows = ob.create_orderbook(loader)

# Print first rows
for row in rows[:10]:
    print(row)
```

---

# Order Book Output Format

Each snapshot row contains:

| Field         | Description             |
| ------------- | ----------------------- |
| `local_ts`    | Local receive timestamp |
| `exch_ts`     | Exchange timestamp      |
| `mid_price`   | Mid market price        |
| `bid_price_n` | Bid price at level n    |
| `bid_qty_n`   | Bid quantity at level n |
| `ask_price_n` | Ask price at level n    |
| `ask_qty_n`   | Ask quantity at level n |

---

# Performance Notes

Since parsing and processing are implemented in Rust:

* Much faster than pure Python
* Lower memory overhead
* Efficient sequential processing
* Suitable for HFT and quant research workflows


# Error Handling

If binary parsing fails:

```python
RuntimeError
```

Typical reasons:

* Invalid file path
* Corrupted binary file
* Unsupported binary structure

---

# Suggested Project Structure

```text
project/
│
├── data/
│   └── feed.bin
│
├── scripts/
│   └── analysis.py
│
└── fastreader/
```

---

# Example Workflow for Quant Developers

```python
from fastreader import BinaryDataLoader
from fastreader import OrderBookGenerator
import pandas as pd

loader = BinaryDataLoader("data/feed.bin")

ob = OrderBookGenerator(depth=5)

rows = ob.create_orderbook(loader)

header = rows[0].split(",")
data = [r.split(",") for r in rows[1:]]

# Convert to DataFrame
book_df = pd.DataFrame(data, columns=header)

print(book_df.head())
```

---

# Future Improvements

Possible future extensions:

* Direct NumPy output
* Pandas integration
* Multi-threaded parsing
* Async streaming
* Arrow/Parquet export
* Zero-copy Python buffers
* Real-time feed support

---

# License

MIT License

