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

Metadata

Release files for quool 7.0.17

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for quool 7.0.17
File	Size	Uploaded
quool-7.0.17.tar.gz	86.5 kB	Apr 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for quool 7.0.17
File	Interpreter	ABI	Platform	Reset
quool-7.0.17-py3-none-any.whl 72.5 kB Apr 3, 2026	Python 3	none	any	Details

Total release size: 159.0 kB

Release files / quool-7.0.17.tar.gz

Download URL	quool-7.0.17.tar.gz
Size	86.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`c39150749e29aaf607f0c485a44656a8dc1f2238714fb31051ac0acad7fdf08d`
BLAKE2b-256 checksum How to use checksums	`45ae8aaf14fceba4767fff5f4433fef7a5d3d8201246c143535d100698bd76a5`
Upload date	Apr 3, 2026
Uploaded using Trusted Publishing? What is 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}`

Release files / quool-7.0.17-py3-none-any.whl

Download URL	quool-7.0.17-py3-none-any.whl
Size	72.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d2dec8f459abe4d21a5cbd28a8a719590c908b29e1cf677b8319f5ec7aec2853`
BLAKE2b-256 checksum How to use checksums	`910400464bff0d58623a5fe4e74090e31df74f7995b52e545d52abd3821d6362`
Upload date	Apr 3, 2026
Uploaded using Trusted Publishing? What is 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}`