Metadata-Version: 2.1
Name: rqalpha-mod-tushare-downloader
Version: 0.1.2
Summary: Tushare-based RQAlpha bundle downloader and builder (CLI tool)
Author: rqalpha-mod-tushare-bundle maintainers
License: MIT
Project-URL: Source, https://github.com/joshuaxql/rqalpha-mod-tushare-bundle
Project-URL: Documentation, https://rqalpha.readthedocs.io/zh-cn/latest/development/mod.html
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tushare==1.4.29
Requires-Dist: tqdm==4.69.0
Requires-Dist: rqalpha>=6.0
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24

# 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](https://rqalpha-mod-tushare-bundle.readthedocs.io/) · [GitHub Pages 镜像](https://joshuaxql.github.io/rqalpha-mod-tushare-bundle/)
>
> 详见 [RQAlpha 官方 mod 开发文档](https://rqalpha.readthedocs.io/zh-cn/latest/development/mod.html)

## 安装 / Installation

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

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

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

## 使用 / Usage

### 1. 下载并构建 bundle

```bash
# 设置 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

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

或代码中：

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

### 3. CLI 高级选项

```bash
# 自定义路径（不写 ~/.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 工具：

```bash
$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](LICENSE).
