使用

1. 下载并构建 bundle

设置 tushare token（注册）：

export TUSHARE_TOKEN="your_token_here"
# Windows PowerShell
$env:TUSHARE_TOKEN = "your_token_here"

全量下载 + 构建（首次运行）

tushare-downloader --token $TUSHARE_TOKEN \
    --start-date 20170101 --end-date 20260720 --phase build

增量更新（日常使用）

tushare-downloader --token $TUSHARE_TOKEN --incremental

增量模式先下载新 CSV（tushare 天然增量），再增量构建 HDF5。

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

默认输出位置

可通过 CLI flag 或构造参数覆盖：

资源	默认路径	覆盖方式
HDF5 bundle	`~/.rqalpha/bundle/`	`--bundle-path` / `TushareDownloader(bundle_path=...)`
CSV 缓存	`~/.rqalpha/tushare_data/`	`--csv-dir` / `TushareDownloader(csv_dir=...)`

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. 直接使用 patch（不通过 RQAlpha）

rqalpha-mod-tushare-data 暴露了 apply_rqdatac_patch，可以直接在自定义脚本中接管 rqdatac 命名空间。~ 会被自动展开为用户主目录：

from rqalpha_mod_tushare_data.patches import apply_rqdatac_patch
apply_rqdatac_patch("~/.rqalpha/bundle")

import rqdatac
df = rqdatac.get_price("000001.XSHE", "2024-01-01", "2024-01-31")
print(df)

4. 直读 BaseDataSource

BaseDataSource 是 RQAlpha 内部回测引擎读数据的那层。不通过 mod.start_up，可以直接实例化它（仅需要一个带 data_bundle_path 等字段的 config 对象）：

import os
from rqalpha.data.base_data_source import BaseDataSource


class _Config:
    """Minimal config stub for BaseDataSource.

    BaseDataSource only reads `data_bundle_path` / `future_info` / `start_date` /
    `benchmark` — see `rqalpha.interface.AbstractDataSource` for the full contract.
    """
    pass

config = _Config()
# BaseDataSource 不会自动展开 ~，需要显式调用 expanduser
config.data_bundle_path = os.path.expanduser("~/.rqalpha/bundle")
config.future_info = {}
config.start_date = "2024-01-01"
config.benchmark = "000300.XSHG"

ds = BaseDataSource(config)
inst = ds.get_instruments("000001.XSHE")
print(inst.order_book_id, inst.type)  # 000001.XSHE CS

完整示例参考 test/test_base_data_source.py（覆盖 get_instruments / get_bar / history_bars / get_dividend / 指数工具等所有公开方法）。

测试

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

# Windows PowerShell
$env:PYTHON_JIT = "0"

# 全部 20 个测试
Get-ChildItem test\test_*.py | ForEach-Object {
    & .venv\Scripts\python.exe $_.FullName
    if ($LASTEXITCODE) { Write-Host "FAIL: $_"; break }
}

测试覆盖：

包结构 + 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 结构验证（含 cmdclass sdist 重命名钩子）
默认路径检测

故障排查

401 / 403 错误

Tushare token 错误或积分不足。检查 ~/.rqalpha/tushare_data/ 里 CSV 是否生成，部分 API（如 fina_indicator_vip）需要 5000 积分以上。

RQAlpha 找不到 mod

确认 rqalpha-mod-tushare-data 安装到与 rqalpha 相同的 Python 环境：

python -c "import rqalpha, rqalpha_mod_tushare_data; print(rqalpha.__file__); print(rqalpha_mod_tushare_data.__file__)"

两个路径应该在同一 site-packages 下。