Metadata-Version: 2.4
Name: OrderPulse
Version: 0.2.17
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

<div align="center">

🚀 High-performance binary market data parser and order book engine for Python, powered by Rust + PyO3.

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)]()
[![Rust](https://img.shields.io/badge/rust-fast-orange.svg)]()
[![PyPI](https://img.shields.io/badge/pypi-fastreader-green.svg)]()
[![Performance](https://img.shields.io/badge/performance-ultra_fast-success.svg)]()

</div>

---

## Overview

`fastreader` is a high-performance Python library built with **Rust** and **PyO3** for parsing exchange binary feed files and constructing order books efficiently.

The library is designed for:

* Quantitative trading systems
* HFT research
* Tick-level backtesting
* Exchange feed analysis
* Order flow analytics
* Order book reconstruction
* Ultra-fast binary parsing

Unlike traditional Python parsers, `fastreader` executes the heavy parsing logic in Rust, delivering significantly better speed and lower memory overhead.

---

# Features

✅ Ultra-fast binary message parsing

✅ Rust-powered backend for maximum performance

✅ Python-friendly API

✅ Parse order and trade messages

✅ Token-based filtering

✅ Cursor-based streaming access

✅ Batch message processing

✅ Top-of-book order book reconstruction

✅ Efficient memory handling

✅ Built for large exchange data files

---

# Installation

## Install from PyPI

```bash
pip install orderpulse
```

## Upgrade to Latest Version

```bash
pip install -U orderpulse
```

---

# Quick Start

## Import Library

```python
from fastreader import ReadMsgFromBinary, OrderBookBuilder
```

## Load Binary Feed File

```python
reader = ReadMsgFromBinary("market_data.bin")
```

## Get Summary

```python
reader.summary()
```

Output:

```text
Total Messages: 1520000
Total Orders: 1300000
Total Trades: 220000
```

---

# Core Classes

# 1. ReadMsgFromBinary

Main parser class used to read exchange binary files.

---

## Constructor

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

### Parameters

| Parameter | Type           | Description              |
| --------- | -------------- | ------------------------ |
| path      | str            | Binary file path         |
| token     | int (optional) | Filter messages by token |

---

## Example: Read Full File

```python
from fastreader import ReadMsgFromBinary

reader = ReadMsgFromBinary("data.bin")
```

---

## Example: Token Filtered Reading

```python
reader = ReadMsgFromBinary(
    "data.bin",
    token=26000
)
```

Only messages belonging to token `26000` will be loaded.

---

# Available Methods

---

## total_messages()

Returns total parsed messages.

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

---

## total_orders()

Returns total order messages.

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

---

## total_trades()

Returns total trade messages.

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

---

## summary()

Prints complete message summary.

```python
reader.summary()
```

---

## reset_cursor()

Resets internal message cursor.

Useful when iterating incrementally.

```python
reader.reset_cursor()
```

---

# Message Extraction APIs

---

## get_all_messages()

Returns all parsed messages.

```python
messages = reader.get_all_messages()
```

### With Limit

```python
messages = reader.get_all_messages(limit=10)
```

---

## get_order_messages()

Returns only order messages.

```python
orders = reader.get_order_messages()
```

### With Limit

```python
orders = reader.get_order_messages(limit=5)
```

---

## get_trade_messages()

Returns only trade messages.

```python
trades = reader.get_trade_messages()
```

### With Limit

```python
trades = reader.get_trade_messages(limit=5)
```

---

# Incremental Reading

---

## get_next_msg()

Reads one message at a time.

Ideal for streaming-style processing.

```python
while True:
    msg = reader.get_next_msg()

    if msg == "END":
        break

    print(msg)
```

---

# MessageBatch

`MessageBatch` is a lightweight container used for efficient message selection and downstream processing.

---

# Selection APIs

---

## select_all_messages()

Returns all messages as a `MessageBatch`.

```python
batch = reader.select_all_messages()
```

---

## select_order_messages()

Returns only order messages.

```python
order_batch = reader.select_order_messages()
```

---

## select_trade_messages()

Returns only trade messages.

```python
trade_batch = reader.select_trade_messages()
```

---

## select_next_messages(limit)

Returns next `N` messages using internal cursor.

```python
batch = reader.select_next_messages(100)
```

Useful for chunk-wise processing of very large files.

---

# MessageBatch Methods

---

## len()

Returns number of messages.

```python
print(batch.len())
```

---

## is_empty()

Checks whether batch is empty.

```python
print(batch.is_empty())
```

---

## to_list()

Converts batch into Python list.

```python
data = batch.to_list()
```

### With Limit

```python
data = batch.to_list(limit=10)
```

---

# OrderBookBuilder

The `OrderBookBuilder` reconstructs top-of-book snapshots using parsed order and trade messages.

---

## Create Builder

```python
from fastreader import OrderBookBuilder

ob = OrderBookBuilder()
```

---

## create_orderbook_all_messages()

Builds order book using all messages from reader.

```python
rows = ob.create_orderbook_all_messages(reader)

print(rows)
```

---

## create_orderbook()

Build order book from a `MessageBatch`.

```python
batch = reader.select_order_messages()

rows = ob.create_orderbook(batch)
```

---

# Example: Complete Workflow

```python
from fastreader import ReadMsgFromBinary
from fastreader import OrderBookBuilder

# Load file
reader = ReadMsgFromBinary(
    "market_data.bin",
    token=26000
)

# Print summary
reader.summary()

# Get first 10 messages
msgs = reader.get_all_messages(limit=10)

for msg in msgs:
    print(msg)

# Select order messages
batch = reader.select_order_messages()

# Build order book
ob = OrderBookBuilder()

rows = ob.create_orderbook(batch)

print("Generated Rows:", rows)
```

---

# Message Format

Messages are returned as formatted strings.

Example:

```text
Order Message: SeqNo12345, msg_len64, Msg_Type'O', Exch_ts123456789, local_ts123456790, order_id11111, Token26000, order_Type'B', Price25000, Quantity100, missed0
```

---

# Message Fields

| Field         | Description             |
| ------------- | ----------------------- |
| SeqNo         | Stream sequence number  |
| msg_len       | Packet length           |
| Msg_Type      | Exchange message type   |
| Exch_ts       | Exchange timestamp      |
| local_ts      | Local receive timestamp |
| order_id      | Order identifier        |
| order_id_buy  | Buy order ID            |
| order_id_sell | Sell order ID           |
| Token         | Instrument token        |
| order_Type    | Order type              |
| Price         | Order/trade price       |
| Quantity      | Quantity                |
| missed        | Gap indicator           |

---

# Performance

`fastreader` is optimized for:

* Large binary files
* Low-latency parsing
* Efficient memory usage
* High throughput message processing

Because parsing logic is implemented in Rust, performance is significantly faster than pure Python implementations.

---

# Use Cases

* Tick data analysis
* HFT research
* Exchange feed decoding
* Backtesting engines
* Order flow analytics
* Market microstructure research
* Real-time strategy simulation
* Order book reconstruction

---

# Why Rust + PyO3?

This library combines:

### Rust

* Memory safety
* High speed
* Zero-cost abstractions
* Parallel-friendly architecture

### Python

* Easy integration
* Quant ecosystem support
* Data science workflows
* Rapid research iteration

Result:

🔥 Production-grade performance with Python simplicity.

---

# Recommended Workflow

```text
Binary Feed File
        ↓
ReadMsgFromBinary
        ↓
MessageBatch Selection
        ↓
OrderBookBuilder
        ↓
Analytics / Alpha / Backtesting
```

---

# Future Roadmap

Planned improvements:

* Direct NumPy export
* Pandas DataFrame support
* Async streaming parser
* Multi-threaded parsing
* Depth-wise order book snapshots
* CSV export
* Arrow / Parquet integration
* Real-time websocket ingestion

---

# Contributing

Contributions are welcome.

You can contribute by:

* Reporting bugs
* Improving performance
* Adding exchange decoders
* Extending order book logic
* Writing benchmarks
* Improving documentation

---

# License

MIT License

---

# Author

Built for quantitative trading and ultra-fast market data processing.

If this library helps your research or trading workflow, consider starring the repository.

---

# Support

If you encounter issues:

1. Open a GitHub issue
2. Share sample binary data
3. Include stack trace/output
4. Mention library version

---

<div align="center">

⚡ fastreader — Rust Speed. Python Simplicity.

</div>
 
