Metadata-Version: 2.4
Name: rqalpha-mod-tushare-bundle
Version: 0.4.0
Summary: Incrementally update an RQAlpha bundle with Tushare Pro data, indicators and index weights
Home-page: 
Author: 
Author-email: 
License: Apache License v2
Classifier: Programming Language :: Python
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: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rqalpha>=6.2
Requires-Dist: tushare>=1.4
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: pandas
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# rqalpha-mod-tushare-bundle

使用 Tushare Pro 对 RQAlpha 6.2 日线 bundle 做增量更新。Token 不写入源码，运行时从
`TUSHARE_TOKEN` 环境变量读取。

支持的数据：

- A 股、场内基金、现有指数和期货日线；
- 期货真实合约、主力连续 `88`、价差前复权 `888` 和价差后复权 `889`；
- 股票涨跌停、停牌日、ST 日；
- 股票/基金复权因子、股票分红及拆分；
- 股票、基金、期货合约元数据和交易日历。
- Tushare `daily_basic` 全部每日指标，保存在独立的 `daily_basic.h5`。
- Tushare `index_weight` 指数历史成分与权重，保存在独立的 `index_weights.h5`。
- 北交所股票元数据、日线、涨跌停、复权因子、分红拆分、停牌及 ST 状态。

更新流程先复制到暂存目录，完成结构和 Tushare 全量逐行校验后才替换正式文件；提交后再次
用 RQAlpha `BaseDataSource` 加载验证。任何失败都会保留或恢复更新前 bundle。

```powershell
$env:TUSHARE_TOKEN = "你的 token"
rqalpha mod enable tushare_bundle
rqalpha-tushare-bundle compare
rqalpha-tushare-bundle update
rqalpha-tushare-bundle validate
```

每次 `update` 都从各 HDF5 文件的最后交易日之后开始；新上市合约只补上市后的数据。重复执行
不会重复写入已有日期。Mod 默认不在每次回测前联网；需要自动更新时，再在 RQAlpha mod 配置中
设置 `auto_update: true`。

## daily_basic 每日指标

`daily_basic` 不属于 RQAlpha 标准日线结构，因此模块不会修改 `stocks.h5` 的 dtype，而是在 bundle
根目录创建 `daily_basic.h5`。文件按交易日保存全市场截面，已有日期不会重复下载或覆盖。普通
`update` 会同时更新该文件；也可以单独回填和验证：

```powershell
# 首次回填；不传 start-date 时从 RQAlpha 交易日历的第一天开始
rqalpha-tushare-bundle update-daily-basic --start-date 20140101

# 独立重新下载并逐字段比较
rqalpha-tushare-bundle validate-daily-basic --start-date 20260701 --end-date 20260710

# Tushare 修订数据或存储规则升级时，显式刷新已有日期
rqalpha-tushare-bundle update-daily-basic --start-date 20260701 --end-date 20260710 --replace-existing
```

保存字段为：`close`、`turnover_rate`、`turnover_rate_f`、`volume_ratio`、`pe`、
`pe_ttm`、`pb`、`ps`、`ps_ttm`、`dv_ratio`、`dv_ttm`、`total_share`、
`float_share`、`free_share`、`total_mv`、`circ_mv`、`limit_status`。数值和单位保持
Tushare 原定义：股本是万股，市值是万元，百分比字段不除以 100；缺失浮点值保存为 `NaN`。
沪深股票使用 RQAlpha 的 `.XSHG/.XSHE` 标识，北交所使用 RQAlpha 6.2 的标准 `.BJSE`
标识。旧版 sidecar 中的 `.BJ` 会在下一次更新时事务性迁移为 `.BJSE`。

启用 mod 后，策略中可以按交易日读取全市场截面：

```python
import rqalpha.api as rq_api


def handle_bar(context, bar_dict):
    daily = rq_api.get_daily_basic(
        date=context.now.date(),
        fields=["total_mv", "circ_mv", "pe_ttm", "pb"],
    )
```

也可以读取单只股票的历史指标：

```python
history = rq_api.history_daily_basic(
    "000001.XSHE", count=22, fields=["total_mv", "turnover_rate"]
)
```

在 RQAlpha 运行环境之外可直接使用
`rqalpha_mod_tushare_bundle.daily_basic.DailyBasicStore(bundle_path)` 读取同一文件。

## 北交所股票行情

普通 `update` 会在全市场新交易日中同步北交所。首次使用需要补历史，或需要显式回填时：

```powershell
rqalpha-tushare-bundle update-bse-stocks --start-date 20221101
```

历史源数据修订时才使用显式覆盖；覆盖按证券代码和交易日主键进行，不影响其他市场：

```powershell
rqalpha-tushare-bundle update-bse-stocks --start-date 20221101 `
    --end-date 20260715 --replace-existing
```

RQAlpha 标识为 `920xxx.BJSE`，证券元数据使用 `exchange=BJSE`、`board_type=BJS`，从而使用
RQAlpha 内置的北交所下单数量规则。

## 指数历史成分权重

指数权重不属于 RQAlpha 标准 bundle，因此保存在 `index_weights.h5`。文件按 Tushare 指数代码和
权重日期保存快照，普通增量更新不会重复下载或覆盖已有快照。默认更新北证50 `899050.BJ`；
可以重复传入 `--index-code` 管理任意多个 Tushare 指数：

```powershell
# 首次全历史回填
rqalpha-tushare-bundle update-index-weights --index-code 899050.BJ --start-date 20221101

# 再次运行只请求最后一期权重之后的数据
rqalpha-tushare-bundle update-index-weights --index-code 899050.BJ

# 独立重下载并逐只成分、逐权重比较
rqalpha-tushare-bundle validate-index-weights --index-code 899050.BJ

# 只有显式指定范围时才允许刷新已存在的快照
rqalpha-tushare-bundle update-index-weights --index-code 899050.BJ `
    --start-date 20260630 --end-date 20260630 --replace-existing
```

启用 mod 后，策略中这样读取指定交易日当时已经生效的最近一期权重：

```python
import rqalpha.api as rq_api


def handle_bar(context, bar_dict):
    weights = rq_api.get_index_weights("899050.BJ", date=context.now.date())
```

返回列为 `index_code`、`order_book_id`、`weight_date`、`weight`。`weight` 保留 Tushare
百分数单位（每期通常合计 100），默认查询不晚于指定日期的最近快照，避免未来函数；传入
`exact=True` 时只接受完全相同的权重日期。沪深成分映射为 `.XSHG/.XSHE`，北交所成分映射为
`.BJSE`。RQAlpha 外可用 `rqalpha_mod_tushare_bundle.index_weight.IndexWeightStore(bundle_path)`。

更新前文件会保存在 bundle 同级的 `bundle_backup_before_tushare_时间戳` 目录。bundle 内会生成：

- `tushare_small_comparison.json`：与官方重叠日期的小样本逐字段对比；
- `tushare_full_official_overlap.json`：官方重叠日的全市场跨供应商审计；
- `tushare_full_validation.json`：更新区间的独立重下载逐行复核；
- `tushare_update_state.json`：增量水位、备份路径和追加统计；
- `tushare_update_result.json`：最近一次实际更新结果。
- `tushare_daily_basic_result.json`：最近一次 daily_basic 增量结果；
- `tushare_daily_basic_validation.json`：daily_basic 独立重下载校验结果。
- `tushare_index_weights_result.json`：最近一次指数权重增量结果；
- `tushare_index_weights_validation.json`：指数权重独立重下载校验结果。
- `tushare_bse_stocks_result.json`：最近一次北交所股票增量或覆盖结果；
- `tushare_daily_basic_bse_migration.json`：旧北交所代码迁移结果。

说明：Tushare 不提供场内基金和期货每日涨跌停接口，这两类涨跌停价按官方 bundle 的最近制度、
合约最小变动价位和前收盘/前结算价推导。不同供应商对少量低流动性远月期货可能给出不同源值，
模块保留 Tushare 值，并在 `tushare_full_official_overlap.json` 中逐项记录，不会静默伪装成一致。
