panda-data 0.0.7

PandaAI DataQuant

panda_data Python SDK 使用文档

项目状态: 🟢 生产环境
版本: v0.1.0
Python 版本: >= 3.12
最后更新: 2024-XX-XX

---

📋 项目概述

panda_data 是公司内部金融数据服务的 Python SDK，提供统一的 Python API 接口访问各类金融数据，所有接口返回 pandas.DataFrame 格式，便于数据分析和处理。

核心特性

• ✅ 统一返回 pandas.DataFrame 格式，无需数据转换
• ✅ 支持股票、基金、指数、行业、概念、财务、期货等多种数据类型
• ✅ 完善的错误处理和自动重试机制
• ✅ 支持代码配置和环境变量配置
• ✅ 支持代理、SSL 验证、Gzip 压缩等企业级特性

---

📑 快速导航

• 快速开始
• 配置说明
• API 接口
• 使用示例
• 常见问题
• 技术支持

---

🚀 快速开始

安装

pip install panda_data

依赖要求

依赖包	版本要求
Python	>= 3.12
pandas	>= 2.0.0
numpy	>= 1.22, < 2.0

基本使用

import panda_data

# 初始化连接
panda_data.init(
    username="your_username",
    password="your_password",
    base_url="http://java-service-host:8080",
)

# 获取数据
df = panda_data.get_market_data(
    symbol=["000001.SZ"],
    start_date="2024-01-01",
    end_date="2024-01-31"
)
print(df.head())

Token 初始化（推荐）

使用 Token 方式可以避免在代码中硬编码密码，更安全：

import panda_data

# 使用 token 文件初始化
panda_data.init_token()

# 调用接口
df = panda_data.get_abnormal(symbol=["000001.SZ"])

---

⚙️ 配置说明

代码配置

在 init() 函数中传入配置参数：

panda_data.init(
    username="user",
    password="pass",
    base_url="http://service.example.com:8080",
    timeout=60.0,           # 请求超时时间（秒）
    max_retries=5,          # 最大重试次数
    verify_ssl=True,        # 是否验证 SSL 证书
    use_gzip=True,         # 是否使用 Gzip 压缩
)

环境变量配置

支持通过环境变量配置，环境变量优先级高于代码配置：

环境变量	说明	默认值
HTTP_SERVICE_BASE_URL	服务基础 URL	http://localhost:8080
HTTP_TIMEOUT	请求超时时间（秒）	30
HTTP_MAX_RETRIES	自动重试次数	3
HTTP_VERIFY_SSL	是否验证 SSL 证书	true
HTTP_PROXY_TYPE	代理类型（"http" 或 "https"）	None
HTTP_PROXY_HOST	代理主机	None
HTTP_PROXY_PORT	代理端口	None
HTTP_USE_GZIP	是否使用 Gzip 压缩	false

代理配置

panda_data.init(
    username="user",
    password="pass",
    base_url="http://service.example.com:8080",
    proxy_type="http",
    proxy_host="proxy.example.com",
    proxy_port=8080,
)

---

📚 API 接口

股票数据

接口	说明
get_stock_detail(symbol, fields=None)	获取股票详情
get_all_symbols(market="cn")	获取所有股票代码
get_market_data(symbol, start_date, end_date, ...)	获取行情数据（日线）
get_market_min_data(symbol, start_date, end_date, ...)	获取分钟行情数据
get_stock_flow(symbol)	获取资金流向
get_main_shareholder(symbol)	获取主要股东信息

示例：

# 获取行情数据
df = panda_data.get_market_data(
    symbol=["000001.SZ", "000002.SZ"],
    start_date="2024-01-01",
    end_date="2024-01-31"
)

异常数据（龙虎榜）

接口	说明
get_abnormal(symbol, type, start_date, end_date, ...)	获取异常数据
get_abnormal_detail(symbol, type, start_date, end_date, ...)	获取异常明细
get_abnormal_types()	获取异常类型列表
get_abnormal_stocks(date, type=None)	获取指定日期的异常股票

示例：

df = panda_data.get_abnormal(
    symbol=["000001.SZ"],
    start_date="2024-01-01",
    end_date="2024-01-31"
)

基金数据

接口	说明
get_all_funds()	获取所有基金列表
get_fund_pro(symbol)	获取基金持仓
get_fund_nav(symbol)	获取基金净值

指数数据

接口	说明
get_index_symbol()	获取指数代码列表
get_index_indicator(symbol)	获取指数指标
get_index_weights(symbol)	获取指数权重
get_index_stock(symbol)	获取指数成分股
get_index_1m_market(symbol)	获取指数分钟行情

行业数据

接口	说明
get_industry_list()	获取行业列表
get_industry_stock(industry)	获取行业股票
get_stock_industry(symbol)	获取股票所属行业

概念数据

接口	说明
get_concept_list()	获取概念列表
get_concept_stock(concept)	获取概念股票

财务数据

接口	说明
get_financial_ex(symbol)	获取财务数据
get_financial_forecast(symbol)	获取业绩预告
get_financial_performance(symbol)	获取业绩快报

交易日历

接口	说明	返回类型
get_trading_calendar(start_date, end_date)	获取交易日历	DataFrame
get_trading_days(start_date, end_date)	获取交易日列表	DataFrame
is_trading_day(date)	判断是否为交易日	bool
get_previous_trading_date(date)	获取前一个交易日	str
get_next_trading_date(date)	获取下一个交易日	str
get_latest_trading_date()	获取最新交易日	str

其他数据

接口	说明
get_buy_back(symbol)	获取回购数据
get_securities_margin(symbol)	获取融资融券数据
get_future_list()	获取期货列表
get_future_factor_post(symbol)	获取期货因子数据
get_consensus_report(symbol)	获取一致预期
get_stock_connect(symbol)	获取沪港通数据

---

💡 使用示例

import panda_data
import pandas as pd

# 初始化
panda_data.init(
    username="your_username",
    password="your_password",
    base_url="http://service.example.com:8080",
)

# 获取股票行情数据
df = panda_data.get_market_data(
    symbol=["000001.SZ", "000002.SZ"],
    start_date="2024-01-01",
    end_date="2024-01-31",
    fields=["open", "high", "low", "close", "volume"]
)

# 数据分析
print(f"共获取 {len(df)} 条数据")
print(df.groupby("symbol")["close"].mean())

---

❓ 常见问题

Q1: 如何设置代理？

A: 通过代码或环境变量设置：

panda_data.init(
    username="user",
    password="pass",
    base_url="http://service.example.com:8080",
    proxy_type="http",
    proxy_host="proxy.example.com",
    proxy_port=8080,
)

Q2: 如何启用 Gzip 压缩？

A: 设置 use_gzip=True：

panda_data.init(
    username="user",
    password="pass",
    base_url="http://service.example.com:8080",
    use_gzip=True,
)

Q3: 如何处理超时？

A: 设置 timeout 参数：

panda_data.init(
    username="user",
    password="pass",
    base_url="http://service.example.com:8080",
    timeout=60.0,  # 60 秒超时
)

Q4: 返回的 DataFrame 为空怎么办？

A: 检查以下几点：

1. 确认参数是否正确（股票代码、日期格式等）
2. 确认请求的时间范围内是否有数据
3. 确认账号是否有权限访问该数据
4. 查看异常信息排查问题

try:
    df = panda_data.get_market_data(
        symbol=["000001.SZ"],
        start_date="2024-01-01",
        end_date="2024-01-31"
    )
    if df.empty:
        print("未找到数据，请检查参数")
except Exception as e:
    print(f"错误: {e}")

---

🛠️ 错误处理

SDK 提供了完善的异常处理机制：

from panda_data.exceptions import (
    ClientNotInitializedError,  # 客户端未初始化
    AuthenticationError,        # 认证失败
    ServiceError,              # 服务端错误
)

try:
    df = panda_data.get_abnormal(symbol=["000001.SZ"])
except ClientNotInitializedError:
    print("请先调用 panda_data.init() 初始化客户端")
except AuthenticationError:
    print("认证失败，请检查用户名和密码")
except ServiceError as e:
    print(f"服务端错误: {e}")

异常类型说明

异常类型	说明	解决方案
ClientNotInitializedError	客户端未初始化	调用 panda_data.init() 或 panda_data.init_token()
AuthenticationError	认证失败	检查用户名和密码是否正确
ServiceError	服务端错误	检查服务端状态和请求参数

---

🏗️ 架构说明

模块结构

panda_data/
├── client.py            # 客户端入口与连接管理
├── config/              # 配置加载与环境变量解析
├── core/                # 面向业务的服务封装
├── transport/           # HTTP 底层通信实现
├── readers/             # 各类数据 Reader
│   ├── abnormal_reader.py      # 异常数据
│   ├── kline_reader.py         # K线数据
│   ├── stock_reader.py         # 股票数据
│   └── ...
└── exceptions.py        # 异常定义

核心组件

• PandaServiceClient: 封装与 Java 服务的 HTTP 通信逻辑
• HTTPClient: 底层 HTTP 客户端，处理请求、响应、重试、代理等
• ClientFactory: 工厂模式管理各类 Reader
• Reader: 各类数据 Reader，封装特定数据接口的调用逻辑

通信协议

• 请求方法: POST
• 请求格式: JSON
• 响应格式: JSON
• 认证方式: HTTP Basic Authentication
• 压缩支持: 可选 Gzip 压缩

---

📞 技术支持

获取帮助

• 📧 技术支持: [待补充]
• 📝 问题反馈: [待补充]
• 📚 更多文档: [待补充]

相关资源

• 项目仓库: [待补充]
• 更新日志: [待补充]

---

文档维护: 数据团队
最后更新: 2024-XX-XX