rqalpha-mod-tushare-bundle

两个 RQAlpha 插件模块：从 tushare 拉数据构建本地 HDF5 bundle，让 RQAlpha / RQFactor 直接读取而不连 rqdatac 服务器。

• rqalpha-mod-tushare-downloader — CLI 工具：从 tushare 拉数据存为 CSV，再构建 RQAlpha 原生 HDF5 bundle
• rqalpha-mod-tushare-data — RQAlpha mod：注册 BaseDataSource + rqdatac monkey-patch，让 RQAlpha / RQFactor 从本地 bundle 读取数据

📖 完整文档：Read the Docs · GitHub Pages 镜像

详见 RQAlpha 官方 mod 开发文档

安装 / Installation

两个包独立发布，按需安装：

# 下载 + 构建 bundle（需要 tushare 账号）
pip install rqalpha-mod-tushare-downloader

# 运行时 mod（回测 / 因子计算时需要）
pip install rqalpha-mod-tushare-data

使用 / Usage

1. 下载并构建 bundle

# 设置 tushare token（https://tushare.pro）
export TUSHARE_TOKEN="your_token_here"

# 全量下载并构建（首次运行）
tushare-downloader --token $TUSHARE_TOKEN --start-date 20170101 --end-date 20260720 --phase build

# 增量更新（日常使用）
tushare-downloader --token $TUSHARE_TOKEN --incremental

默认输出位置（可通过 CLI flag 覆盖）：

• HDF5 bundle: ~/.rqalpha/bundle/
• CSV 缓存: ~/.rqalpha/tushare_data/

2. 在 RQAlpha config 中启用 mod

# your_config.yml
mod:
  tushare-data:
    enabled: true
    priority: 10

或代码中：

import rqalpha_mod_tushare_data
mod = rqalpha_mod_tushare_data.load_mod()
# RQAlpha 会自动调用 mod.start_up(env, mod_config)

3. CLI 高级选项

# 自定义路径（不写 ~/.rqalpha/）
tushare-downloader --token $TUSHARE_TOKEN --incremental \
  --csv-dir ./tushare_data --bundle-path ./bundle

# 只下载不构建
tushare-downloader --token $TUSHARE_TOKEN --phase download

# 只构建（假设 CSV 已存在）
tushare-downloader --token $TUSHARE_TOKEN --phase build

# 完整参数
tushare-downloader --help

版本要求 / Requirements

• Python ≥ 3.10
• numpy ≥ 1.24
• pandas ≥ 2.0
• h5py ≥ 3.0
• rqalpha ≥ 6.0
• rqdatac ≥ 3.0（仅 rqalpha-mod-tushare-data 运行时需要）

测试 / Testing

20 个独立测试脚本，共享 test/_helpers.py 的 PASS/FAIL/SKIP 工具：

$env:PYTHON_JIT = "0"  # Windows PowerShell
# 全部 20 个测试
for f in test/test_*.py; do python "$f" || break; done

测试覆盖：

• 包结构 + load_mod + AbstractMod 子类
• 生命周期签名（start_up / tear_down）
• pandas 2.x 兼容 shim（3 个 monkey-patch）
• 共享状态 + h5 工具
• PATCH_MAP 完整性（40 项 rqdatac 函数）
• 各数据域补丁（instruments / calendar / price / financial / industry / factor / stubs）
• apply_rqdatac_patch 端到端 + 边界
• BaseDataSource 直读
• RQAlpha mod 全链路集成
• 下载器 mod 包结构 + CLI argparse
• setup.py 结构验证
• 默认路径检测

项目结构 / Project Structure

rqalpha-mod-tushare-bundle/
├── rqalpha_mod_tushare_data/         # rqalpha-mod-tushare-data 包
│   ├── __init__.py                    # load_mod + AbstractMod 实例工厂
│   ├── mod.py                         # TushareBundleMod(AbstractMod)
│   ├── setup.py                       # 独立 setuptools 配置
│   ├── MANIFEST.in                    # sdist 文件清单
│   └── patches/                       # rqdatac 40 个函数补丁（按职责拆分）
│       ├── __init__.py                # PATCH_MAP + apply_rqdatac_patch
│       ├── _state.py                  # 共享可变状态
│       ├── _h5_utils.py               # 低层 h5/日期工具
│       ├── instruments.py             # 2 个补丁
│       ├── calendar.py                # 4 个补丁
│       ├── price.py                   # 10 个补丁
│       ├── financial.py               # 4 个补丁
│       ├── industry.py                # 10 个补丁
│       ├── factor.py                  # 2 个补丁
│       ├── stubs.py                   # 8 个空桩
│       └── pandas_compat.py           # pandas 2.x 兼容 shim
├── rqalpha_mod_tushare_downloader/    # rqalpha-mod-tushare-downloader 包
│   ├── __init__.py                    # load_mod + TushareDownloader
│   ├── mod.py                         # TushareDownloaderMod(AbstractMod)
│   ├── __main__.py                    # CLI main()
│   ├── downloader.py                  # TushareDownloader 类（~2000 行）
│   ├── build_workers.py               # 多进程 build 工具
│   └── setup.py                       # 独立 setuptools 配置（含 console_scripts）
├── docs/                              # Sphinx + RTD theme 文档
│   └── source/                        # Markdown 源文件
├── examples/                          # 开发用示例脚本
│   ├── compare_test.py
│   └── download_example.py
├── test/                              # 20 个测试脚本
│   ├── _helpers.py                    # 共享 PASS/FAIL/SKIP 工具
│   ├── README.md
│   └── test_*.py                      # 20 个独立测试
├── setup.py                           # 仅打包 rqalpha-mod-tushare-downloader
├── MANIFEST.in                        # sdist 文件清单
├── LICENSE                            # MIT
├── README.md                          # 本文件
├── requirements.txt                   # 完整依赖（含开发依赖）
├── .readthedocs.yaml                  # Read the Docs 配置
├── .github/workflows/docs.yml         # GitHub Pages 部署
└── .gitignore

文档 / Documentation

• 本地预览：cd docs && make html（需要 pip install -r docs/requirements.txt）
• Read the Docs：配置 .readthedocs.yaml 后可自动构建
• GitHub Pages：push 到 main 触发 .github/workflows/docs.yml，部署到 https://joshuaxql.github.io/rqalpha-mod-tushare-bundle/

License

MIT — see LICENSE.