Quool

Quantitative Toolkit — an extensible event-driven backtesting and live trading framework for quantitative strategies.

Quool provides a modular architecture built around three pillars: Source (market data), Broker (execution & accounting), and Strategy (logic). It supports both backtesting with historical data and paper/live trading with broker integrations.

Installation

pip install quool

Requires Python >= 3.10.

Quick Start

import pandas as pd
from quool import DataFrameSource, Broker, Strategy
from quool import FixedRateCommission, FixedRateSlippage

# 1. Market data source (MultiIndex DataFrame: time x code)
source = DataFrameSource(market_data)

# 2. Broker with commission and slippage models
broker = Broker(
    commission=FixedRateCommission(),
    slippage=FixedRateSlippage(),
)
broker.transfer(pd.Timestamp("2024-01-01"), 1_000_000)  # initial cash

# 3. Implement strategy
class MyStrategy(Strategy):
    def init(self):       # called once before backtest
        pass

    def update(self):     # called every timestamp
        # self.buy("000001", 100)   # buy 100 shares at market
        # self.order_target_percent("000001", 0.1)  # target 10% portfolio
        pass

# 4. Run backtest
strategy = MyStrategy(source, broker)
results = strategy.backtest()

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Strategy                            │
│  init() → preupdate() → update() → stop()               │
└──────────────┬─────────────────────────┬────────────────┘
               │                         │
        ┌──────▼──────┐            ┌──────▼──────┐
        │   Source    │            │   Broker    │
        │ (market    │            │ (execution  │
        │   data)    │            │  & accounting)
        └────────────┘            └──────┬──────┘
                                          │
                                   ┌──────▼──────┐
                                   │   Order /   │
                                   │  Delivery   │
                                   └─────────────┘

Core Concepts

Source

Source is the abstract market data provider. Subclasses implement update() to advance time and return OHLCV snapshots.

Class	Description
`DataFrameSource`	Historical data from a pandas DataFrame (MultiIndex: time × code)
`DuckPQSource`	DuckDB/Parquet queries
`RealtimeSource`	Real-time EastMoney API with a rolling buffer
`XtDataPreloadSource`	XtQuant historical data preloaded into a DataFrame

Broker

Broker manages order execution, portfolio accounting (cash & positions), and order matching for backtesting. For live trading, broker subclasses integrate with external systems.

Class	Description
`Broker`	Core simulated broker with pluggable commission/slippage models
`AShareBroker`	Enforces A-share 100-share lot-size rules
`XueQiuBroker`	XueQiu paper trading integration
`XtBroker`	XtQuant live trading gateway

Order & Delivery

Order tracks the full lifecycle: CREATED → SUBMITTED → PARTIAL → FILLED/CANCELED/EXPIRED/REJECTED
Delivery records individual fills (execution details: price, quantity, commission)
Execution types: MARKET, LIMIT, STOP, STOPLIMIT, TARGET, TARGETLIMIT

Strategy

Base class for trading strategies. Provides:

Lifecycle hooks: init(), preupdate(), update(), stop()
Execution helpers: buy(), sell(), close(), order_target_value(), order_target_percent()
Backtesting: backtest() — blocking loop; run() / arun() — real-time scheduling
Persistence: dump(), load(), store(), restore()

Evaluator

Computes comprehensive performance metrics from broker deliveries:

Return: total_return, annual_return, annual_volatility
Risk-adjusted: sharpe_ratio, calmar_ratio, sortino_ratio
Drawdown: max_drawdown, max_drawdown_period
Risk: VaR_5%, CVaR_5%
Benchmark: beta, alpha, excess_return, information_ratio
Trading: position_duration, trade_win_rate, trade_return
Distribution: skewness, kurtosis, day_return_win_rate, monthly_win_rate

Friction Models

Class	Description
`FixedRateCommission`	Flat-rate commission with minimum fee and stamp duty
`FixedRateSlippage`	Slippage model adjusting execution price based on volume

Storage

DuckDB-backed Parquet storage for efficient historical data management:

Class	Description
`DuckTable`	Single Parquet dataset with SQL querying
`DuckPQ`	Multiple Parquet tables with shared DuckDB connection

Utilities

Function	Description
`setup_logger`	Configurable logging with file handlers
`notify_task`	Email notification decorator
`proxy_request`	HTTP requests with proxy failover
`generate_usage`	Auto-generate Markdown documentation for classes/callables

API Reference

For detailed API documentation, see:

docs/README.md — Full module index and detailed documentation
docs/Order.md — Order and Delivery models
docs/Broker.md — Broker and execution
docs/Strategy.md — Strategy lifecycle and helpers
docs/Source.md — Data source implementations
docs/Evaluator.md — Performance evaluation
docs/Friction.md — Transaction cost models
docs/Storage.md — DuckDB/Parquet storage
docs/Util.md — Utility functions

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quool-7.0.17.tar.gz (86.5 kB view details)

Uploaded Apr 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

quool-7.0.17-py3-none-any.whl (72.5 kB view details)

Uploaded Apr 3, 2026 Python 3

File details

Details for the file quool-7.0.17.tar.gz.

File metadata

Download URL: quool-7.0.17.tar.gz
Upload date: Apr 3, 2026
Size: 86.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for quool-7.0.17.tar.gz
Algorithm	Hash digest
SHA256	`c39150749e29aaf607f0c485a44656a8dc1f2238714fb31051ac0acad7fdf08d`
MD5	`2daa1d7456c319de2646dbadac5be1f7`
BLAKE2b-256	`45ae8aaf14fceba4767fff5f4433fef7a5d3d8201246c143535d100698bd76a5`

See more details on using hashes here.

File details

Details for the file quool-7.0.17-py3-none-any.whl.

File metadata

Download URL: quool-7.0.17-py3-none-any.whl
Upload date: Apr 3, 2026
Size: 72.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for quool-7.0.17-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d2dec8f459abe4d21a5cbd28a8a719590c908b29e1cf677b8319f5ec7aec2853`
MD5	`a7d8d9527e4270742c64d0cd585c9357`
BLAKE2b-256	`910400464bff0d58623a5fe4e74090e31df74f7995b52e545d52abd3821d6362`