ETFDataHub 1.0.0
ETF数据中心，自动选择最优数据源获取ETF历史K线数据
License: MIT
Requires Python: >=3.8
Keywords: etf, finance, stock, kline, data

# ETFDataHub - ETF数据中心

一个专注于ETF数据的统一金融数据获取库，自动选择最优数据源获取ETF和股票的历史K线数据。

## ✨ 特性

- 🔄 **多数据源支持**: 集成东方财富、Tushare、Baostock、同花顺、新浪财经等多个数据源
- 🎯 **智能选择**: 根据数据质量自动选择最佳数据源
- 🛡️ **故障容错**: 自动重试和降级机制，确保数据获取的可靠性
- 📊 **标准格式**: 统一的输出格式，包含完整的OHLCV数据
- 🚀 **简单易用**: 一行代码获取高质量金融数据
- 📈 **ETF专注**: 专注于ETF日线行情数据的获取和质量评估
- 🔧 **配置灵活**: 支持环境变量配置敏感信息
- 📋 **详细日志**: 完善的日志记录，便于调试和监控

## 📦 安装

```bash
pip install -e .
```

## 🚀 快速开始

```python
from ETFDataHub import get_etf_k_data

# 获取创业板ETF最近30天的数据
df = get_etf_k_data('159915')

# 获取指定日期范围的数据
df = get_etf_k_data('159915', '20240101', '20241201')

# 显示调试信息
df = get_etf_k_data('159915', debug=True)

# 指定数据源
df = get_etf_k_data('159915', sources=['eastmoney', 'sina'])

print(df.head())
```

## 📊 数据源质量评估

### 数据源优先级

1. **东方财富** (数据完整性高，覆盖范围广，更新及时)
2. **Tushare Pro** (数据质量最高，专业金融数据)
3. **同花顺** (数据质量高，功能完整)
4. **Baostock** (免费开源，数据稳定可靠)
5. **新浪财经** (作为备用数据源)

### 数据质量评估指标

- **完整性**: 数据是否完整，无缺失值
- **准确性**: 数据是否准确，无异常值
- **一致性**: 不同数据源之间的数据是否一致
- **及时性**: 数据更新是否及时
- **稳定性**: 数据源是否稳定可靠

### 数据源对比分析

| 数据源 | 数据完整性 | 覆盖范围 | 数据质量 | 接口稳定性 | 推荐指数 |
|--------|------------|----------|----------|------------|----------|
| 东方财富 | ✅ 高 | ✅ 完整 | ✅ 准确 | ✅ 稳定 | ⭐⭐⭐⭐⭐ |
| Tushare | ✅ 高 | ✅ 完整 | ✅ 专业 | ✅ 稳定 | ⭐⭐⭐⭐⭐ |
| 同花顺 | ✅ 高 | ✅ 完整 | ✅ 准确 | ⚠️ 需配置 | ⭐⭐⭐⭐ |
| Baostock | ✅ 中 | ✅ 完整 | ✅ 准确 | ✅ 稳定 | ⭐⭐⭐⭐ |
| 新浪财经 | ⚠️ 有限 | ⚠️ 有限 | ✅ 准确 | ✅ 稳定 | ⭐⭐ |

## 🔧 API 参考

### `get_etf_k_data()`

获取ETF的历史K线数据。

**参数：**
- `fund_code` (str): ETF代码，如 '159915'
- `beg` (str, 可选): 开始日期，格式 'YYYYMMDD'，默认 '20200101'
- `end` (str, 可选): 结束日期，格式 'YYYYMMDD'，默认今天
- `debug` (bool, 可选): 是否显示调试信息，默认 False
- `sources` (list, 可选): 指定数据源列表，如 ['eastmoney', 'sina']

**返回：**
- `pd.DataFrame`: 包含完整K线数据的DataFrame

### `evaluate_data_sources()`

评估所有数据源的质量。

**参数：**
- `fund_code` (str, 可选): ETF代码，用于测试
- `beg` (str, 可选): 开始日期
- `end` (str, 可选): 结束日期
- `debug` (bool, 可选): 是否显示调试信息

**返回：**
- `dict`: 包含各个数据源质量评估结果的字典

### `compare_data_sources()`

对比不同数据源的数据。

**参数：**
- `fund_code` (str): ETF代码
- `beg` (str): 开始日期
- `end` (str): 结束日期
- `debug` (bool, 可选): 是否显示调试信息

**返回：**
- `dict`: 包含各个数据源数据对比结果的字典

### `test_etf_coverage()`

测试ETF覆盖范围。

**参数：**
- `etf_list` (list, 可选): ETF代码列表
- `days` (int, 可选): 测试天数，默认 30
- `debug` (bool, 可选): 是否显示调试信息

**返回：**
- `dict`: 包含ETF覆盖测试结果的字典

## 📊 使用示例

### 1. 基本使用

```python
# 获取上证50ETF数据
df = get_etf_k_data('510050')
print("上证50ETF数据:")
print(df.head())
print(f"数据条数: {len(df)}")

# 获取沪深300ETF数据
df = get_etf_k_data('510300')
print("\n沪深300ETF数据:")
print(df.head())
print(f"数据条数: {len(df)}")
```

### 2. 数据源质量评估

```python
from ETFDataHub import evaluate_data_sources

# 评估数据源质量
quality_result = evaluate_data_sources('510050', '20240101', '20240131', debug=True)
print("数据源质量评估结果:")
for source, quality in quality_result.items():
    print(f"{source}:")
    print(f"  综合评分: {quality['overall']:.2f}")
    print(f"  完整性: {quality['completeness']:.2f}")
    print(f"  准确性: {quality['accuracy']:.2f}")
    print(f"  一致性: {quality['consistency']:.2f}")
    print(f"  及时性: {quality['timeliness']:.2f}")
    print(f"  稳定性: {quality['stability']:.2f}")
```

### 3. 数据源对比

```python
from ETFDataHub import compare_data_sources

# 对比数据源
comparison = compare_data_sources('510050', '20240101', '20240131', debug=True)
print("数据源对比结果:")
print(f"最佳数据源: {comparison['best_source']}")
print(f"最佳数据源得分: {comparison['best_score']:.2f}")
print("各数据源得分:")
for source, score in comparison['scores'].items():
    print(f"  {source}: {score:.2f}")
```

### 4. ETF覆盖测试

```python
from ETFDataHub import test_etf_coverage

# 测试主流ETF覆盖情况
result = test_etf_coverage(debug=True)
print("ETF覆盖测试结果:")
print(f"测试ETF数量: {len(result['etfs'])}")
print(f"成功获取数据的ETF: {result['success_count']}")
print(f"成功率: {result['success_rate']:.2f}%")

# 查看详细结果
for etf, status in result['etfs'].items():
    print(f"{etf}: {'成功' if status['success'] else '失败'}")
    if 'error' in status:
        print(f"  错误: {status['error']}")
```

## 🧪 测试

### 运行所有测试

```bash
pytest src/tests/
```

### 测试单个数据源

```bash
# 测试新浪数据源
python -m data_sources.sina

# 测试东方财富数据源
python -m data_sources.eastmoney
```

## 🔧 配置说明

### 环境变量配置

在项目根目录创建 `.env` 文件：

```env
# Tushare Pro API Token
TUSHARE_TOKEN=your_tushare_token_here

# 日志级别
LOG_LEVEL=INFO
```

### 数据源配置

可以通过 `sources` 参数指定使用的数据源：

```python
# 只使用东方财富和Tushare
df = get_etf_k_data('510050', sources=['eastmoney', 'tushare'])

# 只使用Baostock和新浪
df = get_etf_k_data('510050', sources=['baostock', 'sina'])
```

## 📋 数据字段说明

| 字段 | 说明 | 类型 |
|------|------|------|
| 日期 | 交易日期 | datetime.date |
| 开盘 | 开盘价 | float |
| 收盘 | 收盘价 | float |
| 最高 | 最高价 | float |
| 最低 | 最低价 | float |
| 成交量 | 成交量 | int |
| 成交额 | 成交金额 | float |
| 涨跌幅 | 涨跌幅百分比 | float |
| 涨跌额 | 涨跌金额 | float |
| 振幅 | 振幅百分比 | float |
| 换手率 | 换手率百分比 | float |

## ⚠️ 免责声明

本库仅供学习和研究使用，不构成投资建议。使用本库获取的金融数据进行投资决策所产生的一切风险由用户自行承担。请遵守相关法律法规，尊重金融数据提供商的使用条款。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📞 支持

如果您在使用过程中遇到问题，请：

1. 查看日志信息
2. 检查网络连接
3. 确认数据源配置正确
4. 提交 Issue 描述问题

## 📄 许可证

MIT License

## 📊 项目状态

- ✅ 东方财富数据源：稳定可用
- ✅ Tushare数据源：稳定可用
- ✅ 同花顺数据源：稳定可用（只返回最近140天数据）
- ✅ Baostock数据源：稳定可用（只支持2026-01-05之后数据）
- ✅ 新浪数据源：稳定可用

## 🌟 推荐使用

对于ETF数据获取，推荐使用以下组合：

1. **首选**: 东方财富 + Tushare (数据质量最高)
2. **备用**: 同花顺 + Baostock + 新浪 (多源备份)
3. **完整**: 东方财富 + Tushare + 同花顺 + Baostock + 新浪 (全方位覆盖)