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

依赖要求

基本使用

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 压缩
)

环境变量配置

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

代理配置

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 接口

股票数据

示例：

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

异常数据（龙虎榜）

示例：

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

基金数据

指数数据

行业数据

概念数据

财务数据

交易日历

其他数据

💡 使用示例

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}")

异常类型说明

🏗️ 架构说明

模块结构

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