panda-data 0.0.1__tar.gz

panda_data-0.0.1/PKG-INFO

@@ -0,0 +1,438 @@
+Metadata-Version: 2.4
+Name: panda_data
+Version: 0.0.1
+Summary: PandaAI DataQuant
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy<2.0,>=1.22
+Requires-Dist: python-snappy>=0.7.3
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: zstandard>=0.22.0
+Requires-Dist: duckdb
+Requires-Dist: pyarrow
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: jupyterlab>=3.5.0; extra == "dev"
+
+# 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 接口](#api-接口)
+- [使用示例](#使用示例)
+- [常见问题](#常见问题)
+- [技术支持](#技术支持)
+
+---
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+pip install panda_data
+```
+
+### 依赖要求
+
+| 依赖包 | 版本要求 |
+|--------|---------|
+| Python | >= 3.12 |
+| pandas | >= 2.0.0 |
+| numpy | >= 1.22, < 2.0 |
+
+### 基本使用
+
+```python
+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 方式可以避免在代码中硬编码密码，更安全：
+
+```python
+import panda_data
+
+# 使用 token 文件初始化
+panda_data.init_token()
+
+# 调用接口
+df = panda_data.get_abnormal(symbol=["000001.SZ"])
+```
+
+---
+
+## ⚙️ 配置说明
+
+### 代码配置
+
+在 `init()` 函数中传入配置参数：
+
+```python
+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` |
+
+### 代理配置
+
+```python
+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)` | 获取主要股东信息 |
+
+**示例：**
+```python
+# 获取行情数据
+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)` | 获取指定日期的异常股票 |
+
+**示例：**
+```python
+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)` | 获取沪港通数据 |
+
+---
+
+## 💡 使用示例
+
+```python
+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:** 通过代码或环境变量设置：
+
+```python
+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`：
+
+```python
+panda_data.init(
+    username="user",
+    password="pass",
+    base_url="http://service.example.com:8080",
+    use_gzip=True,
+)
+```
+
+### Q3: 如何处理超时？
+
+**A:** 设置 `timeout` 参数：
+
+```python
+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. 查看异常信息排查问题
+
+```python
+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 提供了完善的异常处理机制：
+
+```python
+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