Metadata-Version: 2.1
Name: qstrade
Version: 0.0.1
Summary: Chinese market data, CTP trading and event-driven strategy framework
Keywords: trading,futures,ctp,insight,tqsdk
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest (<9,>=7.4) ; extra == 'test'
Requires-Dist: pandas (<3,>=1.5) ; extra == 'test'
Provides-Extra: tqsdk
Requires-Dist: tqsdk (==3.8.3) ; extra == 'tqsdk'

# qstrade

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

## 安装

```bash
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 的原生二进制。

## 离线体验

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

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

## 配置

```bash
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 和运行目录路径以当前工作目录为基准。

## 行情订阅

```python
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()
```

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

## 交易与策略

```python
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` 才允许策略报撤单：

```bash
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 返回的交易日。

## 源码开发

```bash
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/*
```

```text
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` 入口保留，需先安装库。详细接口文档、示例和测试随源码分发包提供；历史本地验证日志、私有参考资料和账户文件不在发布包中。
