quantbox-cn 0.2.0

A quantitative trading toolbox with multiple data source support

Quantbox

Quantbox 是一个现代化的 Python 金融数据获取和管理框架，采用清晰的三层架构设计，支持多种数据源（Tushare、掘金量化等），为量化研究和交易提供统一、高效的数据接口。

⚠️ 重要更新 (2025-11-11)：

• ✨ 优化交易日历数据结构（移除冗余 is_open 字段，新增 datestamp 索引）
• 🎯 增强合约查询接口（支持简单格式和完整格式，智能解析）
• 📈 查询性能提升 6.4%，存储空间减少 12%
• 详见 迁移指南

✨ 核心特性

• 🏗️ 三层架构设计：工具层 → 适配器层 → 服务层，职责清晰，易于扩展
• ⚡ 异步高性能：完整异步实现，性能提升 10-20 倍，支持 Python 3.14 nogil
• 🔌 多数据源支持：统一接口访问 Tushare、掘金量化 (GMAdapter)、本地 MongoDB
• 🚀 智能数据源选择：自动优先使用本地数据，降低 API 调用成本
• ⚡ 缓存预热系统：启动时预热 1491 个缓存条目，运行时性能提升 95%+
• 💾 高效数据存储：批量 upsert 操作，自动去重和索引优化
• 🎯 灵活合约格式：支持简单格式 "a2501" 和完整格式 "DCE.a2501"，智能解析
• 📈 优化数据结构：交易日历使用 datestamp 索引，查询性能提升 6.4%
• 📊 完整类型注解：全面的类型提示，更好的 IDE 支持
• ✅ 高测试覆盖率：12个测试文件，187+ 测试用例，服务层 100%/85% 覆盖
• 🛠️ 现代化工具链：使用 uv 进行快速依赖管理

🏛️ 架构概览

┌─────────────────────────────────────────┐
│         Application Layer               │
│      (Your Scripts & Applications)      │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│          Services Layer                 │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ MarketData   │  │  DataSaver      │ │
│  │   Service    │  │   Service       │ │
│  └──────────────┘  └─────────────────┘ │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Adapters Layer                  │
│  ┌──────────┐  ┌──────────┐  ┌───────┐ │
│  │  Local   │  │ TuShare  │  │  GM   │ │
│  │ Adapter  │  │ Adapter  │  │ ...   │ │
│  └──────────┘  └──────────┘  └───────┘ │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│      Utils Layer                        │
│  Date • Exchange • Contract Utilities   │
└─────────────────────────────────────────┘

详细架构说明请参阅 ARCHITECTURE.md

🚀 快速开始

一分钟上手

# 1. 安装（3 种方式任选其一）
pip install quantbox-cn                    # 从 PyPI 安装（推荐）
pip install quantbox-cn[goldminer]         # 包含掘金支持（Windows/Linux）

# 2. 启动 MongoDB
docker run -d --name quantbox-mongo -p 27017:27017 mongo:latest

# 3. 初始化配置
quantbox-config

# 4. 编辑配置文件，填入 Tushare token
vi ~/.quantbox/settings/config.toml

# 5. 测试安装
python -c "from quantbox.services import MarketDataService; print('✅ 安装成功！')"

💡 首次使用？ 请查看下方详细的 配置指南

完整安装指南

方式 1：从 PyPI 安装（推荐，适合普通用户）

# 基础安装
pip install quantbox-cn

# 安装掘金量化支持（仅 Windows/Linux）
pip install quantbox-cn[goldminer]

# 安装所有可选依赖（包括开发工具）
pip install quantbox-cn[all]

方式 2：使用 uv 安装（适合开发者）

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone https://github.com/curiousbull/quantbox.git
cd quantbox

# 安装基础依赖（自动创建虚拟环境）
uv sync

# 【可选】安装掘金量化 SDK（仅支持 Windows/Linux）
uv sync --extra goldminer

# 【可选】安装所有可选依赖（包括开发工具、GUI）
uv sync --extra all

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

方式 3：从源码安装（适合贡献者）

git clone https://github.com/curiousbull/quantbox.git
cd quantbox
pip install -e .              # 开发模式安装
pip install -e ".[dev]"       # 包含开发工具

📝 配置指南

第一步：安装 MongoDB

Quantbox 使用 MongoDB 作为本地数据存储。请选择以下任一方式安装：

方式 1：Docker（推荐）

# 拉取 MongoDB 镜像
docker pull mongo:latest

# 启动 MongoDB 容器
docker run -d \
  --name quantbox-mongo \
  -p 27017:27017 \
  -v ~/quantbox-data:/data/db \
  mongo:latest

# 验证运行状态
docker ps | grep quantbox-mongo

方式 2：本地安装

• macOS: brew install mongodb-community && brew services start mongodb-community
• Ubuntu: sudo apt install mongodb && sudo systemctl start mongodb
• Windows: 下载 MongoDB Community Server

方式 3：云服务

• 使用 MongoDB Atlas 免费套餐（512MB）

第二步：获取数据源 Token

Tushare Pro（必需）

Tushare 是主要的数据源，需要注册并获取 token：

1. 访问 Tushare Pro 注册账号
2. 登录后进入 个人中心 获取 token
3. 注意：免费用户有积分限制，建议充值获取更多积分

掘金量化（可选，仅支持 Windows/Linux）

如需使用掘金数据源：

1. 访问 掘金量化 注册账号
2. 安装掘金终端并获取 token
3. 安装 Python SDK：pip install quantbox-cn[goldminer]

⚠️ 注意：掘金 SDK 不支持 macOS

第三步：初始化配置

# 安装完成后，运行配置工具
quantbox-config

这将自动：

• 创建配置目录：~/.quantbox/settings/
• 生成配置文件：~/.quantbox/settings/config.toml
• 显示配置说明

第四步：编辑配置文件

打开配置文件并填入你的 token：

# macOS/Linux
vi ~/.quantbox/settings/config.toml

# Windows
notepad %USERPROFILE%\.quantbox\settings\config.toml

配置文件格式：

# Tushare Pro API 配置（必需）
[TSPRO]
token = "your_tushare_token_here"  # 替换为你的 Tushare token

# 掘金量化 API 配置（可选，Windows/Linux）
[GM]
token = ""  # 如果使用掘金，填入你的 token

# MongoDB 数据库配置
[MONGODB]
uri = "mongodb://localhost:27017"  # 本地 MongoDB
# uri = "mongodb+srv://user:[e-mail]"  # 云服务示例

第五步：验证安装

运行以下命令验证配置是否正确：

# 测试数据查询
python -c "
from quantbox.services import MarketDataService
service = MarketDataService()
print('✅ Quantbox 配置成功！')
print('获取交易日历示例：')
calendar = service.get_trade_calendar(exchanges='SHSE', start_date='2024-01-01', end_date='2024-01-05')
print(calendar)
"

如果看到交易日历数据输出，说明配置成功！

常见问题

Q: MongoDB 连接失败？

• 检查 MongoDB 是否运行：docker ps 或 brew services list
• 检查端口是否被占用：lsof -i :27017
• 尝试使用 IP 地址：mongodb://127.0.0.1:27017

Q: Tushare 报错 "token 无效"？

• 检查 token 是否复制完整（无多余空格）
• 检查配置文件路径是否正确
• 尝试重新运行：quantbox-config --force

Q: 提示积分不足？

• Tushare 免费用户有积分限制
• 建议充值获取更多积分，或减少请求频率

Q: macOS 上使用掘金？

• 掘金 SDK 不支持 macOS，请使用 Tushare 或其他数据源

📖 使用示例

应用初始化和缓存预热

import quantbox

# 方法1：推荐的标准初始化（自动预热缓存）
stats = quantbox.init(auto_warm=True, warm_verbose=False)
print(f"初始化完成，预热耗时: {stats['total_time']:.3f}s")

# 方法2：手动预热缓存
stats = quantbox.warm_caches(verbose=True)
print(f"预热了 {stats['functions_warmed']} 个函数，{stats['cache_entries']} 个缓存条目")

# 方法3：后台自动预热（不阻塞应用启动）
quantbox.auto_warm_on_import(enable=True)

缓存预热带来的性能提升：

• 🚀 应用启动后首次操作速度提升 95%+
• ⚡ 交易所代码转换从 ~1ms 降低到 ~0.02ms
• 📈 支持数百个常用函数组合的智能缓存

查询市场数据

from quantbox.services import MarketDataService

# 创建服务实例
service = MarketDataService()

# 获取交易日历
calendar = service.get_trade_calendar(
    exchanges=["SHSE", "SZSE"],
    start_date="2024-01-01",
    end_date="2024-01-31"
)
print(calendar)

# 获取期货合约信息
contracts = service.get_future_contracts(
    exchanges="SHFE",
    date="2024-01-15"
)
print(contracts)

# 获取期货日线数据（支持多种合约格式）
daily = service.get_future_daily(
    symbols="DCE.a2501",      # 完整格式：交易所.合约
    start_date="2024-01-01",
    end_date="2024-01-31"
)
# 也支持简单格式：symbols="a2501"
print(daily)

# 获取持仓数据
holdings = service.get_future_holdings(
    exchanges="DCE",
    date="2024-01-15"
)
print(holdings)

保存数据到本地

from quantbox.services import DataSaverService

# 创建保存服务实例
saver = DataSaverService()

# 保存交易日历
result = saver.save_trade_calendar(
    exchanges=["SHSE", "SZSE"],
    start_date="2024-01-01",
    end_date="2024-12-31"
)
print(f"插入: {result.inserted_count}, 更新: {result.modified_count}")

# 保存期货合约
result = saver.save_future_contracts(
    exchanges="SHFE",
    date="2024-01-15"
)

# 保存日线数据
result = saver.save_future_daily(
    exchanges="DCE",
    start_date="2024-01-01",
    end_date="2024-01-31"
)

⚡ 异步高性能版本（性能提升 10-20 倍）

quantbox 提供完整的异步实现，适用于大规模数据下载和并发查询场景。

异步查询数据

import asyncio
from quantbox.services import AsyncMarketDataService

async def main():
    # 创建异步服务实例
    service = AsyncMarketDataService()

    # 异步获取期货持仓（性能提升 12-17 倍）
    holdings = await service.get_future_holdings(
        exchanges=["SHFE", "DCE"],
        start_date="2024-01-01",
        end_date="2024-01-10",
        show_progress=True
    )
    print(f"获取 {len(holdings)} 条持仓数据")

asyncio.run(main())

异步保存数据

import asyncio
from quantbox.services import AsyncDataSaverService

async def main():
    # 创建异步保存服务
    saver = AsyncDataSaverService(show_progress=True)

    # 并发保存所有数据（性能提升 14 倍）
    results = await saver.save_all(
        start_date="2024-01-01",
        end_date="2024-01-10"
    )

    # 打印结果
    for key, result in results.items():
        print(f"{key}: 插入 {result.inserted_count}，更新 {result.modified_count}")

asyncio.run(main())

使用异步 Shell

# 启动异步交互式 Shell
quantbox-async

# 在 Shell 中执行命令
quantbox-async> save_all --start-date 2024-01-01 --end-date 2024-01-10
quantbox-async> save_future_holdings --exchanges SHFE,DCE --date 2024-01-05

使用异步 CLI

# 并发保存所有数据
quantbox-save-async save-all --start-date 2024-01-01

# 保存期货持仓（核心性能优化）
quantbox-save-async save-holdings --exchanges SHFE,DCE \
                                    --start-date 2024-01-01 \
                                    --end-date 2024-01-10

# 运行性能基准测试
quantbox-save-async benchmark --exchanges SHFE,DCE

性能对比

操作	同步版本	异步版本	提升倍数
期货持仓下载（10 天）	250s	15-20s	12-17x
完整数据保存 (save_all)	355s	25s	14x
并发查询多交易所	45s	8s	5.6x

Python 3.14 nogil 额外提升：在 nogil 模式下可再提升 50-60%

详细文档：

• 异步使用指南
• 异步实现报告
• nogil 测试指南

数据源切换

from quantbox.services import MarketDataService

# 默认：本地优先
service = MarketDataService()
data = service.get_trade_calendar()  # 先查本地，没有再查远程

# 强制使用远程数据源
data = service.get_trade_calendar(use_local=False)

# 强制使用本地数据源
data = service.get_trade_calendar(use_local=True)

更多示例请参阅 QUICK_START.md

📚 文档

• 快速开始指南 - 5分钟上手教程
• 缓存预热指南 - 详细的缓存预热使用示例
• 架构文档 - 详细的系统架构说明
• API 参考 - 完整的 API 文档
• 迁移指南 - 从旧版本迁移
• 编码规范 - 项目编码标准
• 重构设计 - 重构设计文档

🧪 测试

运行所有测试：

uv run pytest tests/ -v

运行核心测试（跳过数据库测试）：

uv run pytest tests/ -v -m "not db"

生成覆盖率报告：

uv run pytest tests/ --cov=quantbox --cov-report=html

🗂️ 项目结构

quantbox/
├── adapters/              # 数据适配器层
│   ├── base.py           # 适配器基类
│   ├── local_adapter.py  # MongoDB 适配器
│   ├── ts_adapter.py     # Tushare 适配器
│   ├── gm_adapter.py     # 掘金量化适配器
│   ├── formatters.py     # 公共格式转换工具
│   └── asynchronous/     # 异步适配器
├── services/             # 服务层
│   ├── market_data_service.py        # 数据查询服务
│   ├── data_saver_service.py         # 数据保存服务
│   ├── async_market_data_service.py  # 异步查询服务
│   └── async_data_saver_service.py   # 异步保存服务
├── config/               # 配置管理
│   ├── config_loader.py  # 配置加载器
│   ├── exchanges.toml    # 交易所配置
│   ├── instruments.toml  # 合约配置
│   ├── fees_margin.toml  # 手续费和保证金配置
│   └── templates/        # 配置模板
├── util/                 # 工具层
│   ├── date_utils.py     # 日期处理工具
│   ├── exchange_utils.py # 交易所代码工具
│   ├── contract_utils.py # 合约代码工具
│   ├── tools.py          # 通用工具函数
│   └── cache_warmup.py   # 缓存预热系统
├── gui/                  # 图形界面（可选）
├── cli.py                # 命令行工具（同步）
├── cli_async.py          # 命令行工具（异步）
├── shell.py              # 交互式 Shell（同步）
└── shell_async.py        # 交互式 Shell（异步）

🔄 API 变更

v2.0 新 API（推荐）

# ✅ 新版本 - 简洁清晰
from quantbox.services import MarketDataService

service = MarketDataService()
data = service.get_trade_calendar(exchanges="SHSE")

v1.x 旧 API（已移除）

# ❌ 旧版本 - 已在 v0.2.0 中完全移除
# from quantbox.fetchers import TSFetcher
# from quantbox.savers import MarketDataSaver

# 这些模块已不存在，请使用新的服务层 API

注意：旧的 fetchers/ 和 savers/ 模块已在 v0.2.0 中完全移除。

详细迁移指南请参阅 MIGRATION_GUIDE.md

🤝 贡献

我们欢迎所有形式的贡献！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交修改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

请确保：

• 所有测试通过
• 新增代码有相应的测试
• 遵循项目编码规范

📊 性能

缓存预热性能

• 预热耗时：~77ms（147个函数，1,491个缓存条目）
• 运行时提升：首次操作速度提升 95%+
• 代码转换：交易所代码转换从 ~1ms → ~0.02ms
• 缓存命中率：>95%（常用操作组合）

数据操作性能

• 查询速度：本地查询 < 10ms，远程查询 < 500ms
• 批量写入：10,000 条/秒（使用 bulk_write）
• 内存占用：< 100MB（正常运行）
• 并发支持：线程安全的数据访问

📝 更新日志

v0.2.0 (2025-11-12)

• 🎉 重大重构：全新的三层架构设计
• ✨ 新增：MarketDataService 和 DataSaverService（同步+异步）
• ⚡ 异步支持：完整异步实现，性能提升 10-20 倍
• 🗑️ 移除：删除旧的 fetchers/ 和 savers/ 模块
• 🔧 改进：统一的数据接口和错误处理
• 📚 文档：全面更新的使用文档
• ✅ 测试：187+ 测试用例，服务层覆盖率 100%/85%
• 🚀 工具：迁移到 uv 项目管理
• 🧹 清理：项目结构优化，移除临时文件和开发文件

完整更新日志请查看 docs/refactor_progress.md

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

• Tushare - 金融数据接口
• 掘金量化 - 量化交易平台
• uv - 现代化 Python 包管理器

📮 联系方式

• 问题反馈：GitHub Issues
• 功能建议：GitHub Discussions

---

Made with ❤️ by the Quantbox Team