qstrade

面向中国股票与期货的 Python 行情、交易及事件驱动策略库。初始版本 0.0.1，支持 Python 3.9 及以上版本；原生 SDK 的 Python 和操作系统兼容性以供应商为准。

安装

python -m pip install qstrade==0.0.1
# 使用天勤行情时安装可选依赖
python -m pip install "qstrade[tqsdk]==0.0.1"

基础库仅依赖 Python 标准库，导入时不会登录、连接交易账户或加载原生 SDK。 Insight SDK（gdp-insight-py-win）及 CTP Python 绑定需要自行安装，并与解释器版本、系统位数匹配。发布包不包含这些 SDK 的原生二进制。

离线体验

qstrade --version
qstrade --mode replay
# 等价入口
python -m qstrade --mode replay

回放无需账户或网络，预期返回 {'orders': 2, 'trades': 2, 'position': 0}；仅验证事件流程，不模拟真实交易成本。

配置

qstrade --init-config config.local.json

在生成的模板中填写所选适配器凭据及 SDK 路径。命令不会覆盖已有文件。 配置优先级：显式传入 load_config(path) / CLI --config，其次 QS_CONFIG 环境变量，最后当前工作目录的 config.local.json；供应商环境变量覆盖 JSON 同名字段。

常用环境变量包括 MARKET_DEFAULT_PROVIDER、MARKET_FUTURES_PROVIDER、MARKET_STOCK_PROVIDER、TRADER_STRATEGY_TYPE、TRADER_ADAPTER、INSIGHT_USER、INSIGHT_PASSWORD、TQSDK_USERNAME、TQSDK_PASSWORD、CTP_SDK_PATH。相对 SDK 和运行目录路径以当前工作目录为基准。

行情订阅

import time
from qstrade.market import MarketData
from qstrade.market.data import TickData


def on_tick(tick: TickData):
    print(tick["symbol"], tick["last_price"], tick["volume"])


market = MarketData.create(provider="tqsdk")  # 读取配置并登录
try:
    market.subscribe_tick(["C2701.DCE"], callback=on_tick)
    market.subscribe_kline(["C2701.DCE"], "1min")  # 默认打印标准 K 线
    time.sleep(30)
finally:
    market.logout()

订阅代码需要替换为当前有效、账户有权限的合约。回调应快速返回；不要在回调内同步订阅、查询或释放会话。

交易与策略

from qstrade.trader import create_trader
from qstrade.strategy import StrategyEngine, StrategyBase
from qstrade.strategy.examples import MaCrossStrategy

trader = create_trader()  # 只创建，不连接；由调用方管理 connect/disconnect
engine = StrategyEngine(trading_enabled=False)  # 策略观察模式
strategy = MaCrossStrategy("ma5_ma10", engine, "C2701.DCE", warmup_days=0)
engine.add_strategy(strategy)
# engine.start() 后接收行情；结束时调用 engine.stop()

CLI 默认观察模式，显式 --trade 才允许策略报撤单：

qstrade --market tqsdk --symbol C2701.DCE --seconds 30

库内 StrategyEngine 保留既有交易开关默认行为；调用方应显式设置 trading_enabled。MA 示例为 MA5 高于 MA10 时空仓开多，低于时平多，不开空、不加仓；以实际成交维护持仓，停止时尝试撤销本次引擎在途订单，不主动平仓。

统一接口

• 公共证券代码使用 Wind 格式，例如 600397.SH、SA2701.CZC、PP2701F.DCE；供应商代码转换在适配器内部完成。
• Tick / Bar 以完整字典返回，字段定义位于 qstrade.market.data，缺失值为 None。
• Tick 最新价为 last_price，盘口为 quotes；volume / amount 为当日累计量额。
• Bar 使用 OHLC 与区间 volume / amount，timestamp 表示周期起点，is_closed 表示完成状态。
• 时间为上海本地 YYYY-MM-DD HH:MM:SS[.小数秒]，不带时区后缀，保留源精度。
• Insight K 线原生时间的起止语义尚未确认，默认 timestamp=None，MA 策略跳过。独立确认所用接口的时间标签为周期起点后，才可配置 insight.bar_time_label="start"。
• 天勤未提供的 K 线成交额及交易日保持 None；交易回报使用 CTP 返回的交易日。

源码开发

python -m pip install -e ".[test]"
python -m unittest discover -s tests -t . -q
python -m pip install build twine
python -m build
python -m twine check dist/*

src/qstrade/       安装包：config、market、trader、strategy、utils、CLI
examples/         调用示例（先安装 qstrade，再运行）
tests/            离线回归测试
docs/             接口说明、策略说明和发布流程
config.example.json  空白配置模板
pyproject.toml    包元数据与构建配置

从旧项目迁移时，将 from strategy_system... 改为 from qstrade...。原 python main.py 入口保留，需先安装库。详细接口文档、示例和测试随源码分发包提供；历史本地验证日志、私有参考资料和账户文件不在发布包中。