Metadata-Version: 2.4
Name: zizhenghua-quant
Version: 1.1.0
Summary: Official Python SDK for Quant Data API (A-share market data)
Author-email: Zizhenghua <support@zizhenghua.com>
License: MIT
Project-URL: Homepage, https://zizhenghua.com
Project-URL: Documentation, https://zizhenghua.com/swagger-ui/index.html
Project-URL: Repository, https://github.com/Zizhenghua/quant-data-sdk
Project-URL: Issues, https://github.com/Zizhenghua/quant-data-sdk/issues
Project-URL: Changelog, https://github.com/Zizhenghua/quant-data-sdk/blob/main/CHANGELOG.md
Keywords: quant,stock,a-share,finance,api,akshare,backtest
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Provides-Extra: async
Requires-Dist: httpx>=0.25.0; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: pandas>=1.5.0; extra == "all"
Requires-Dist: httpx>=0.25.0; extra == "all"
Dynamic: license-file

# Quant Data SDK

[![PyPI](https://img.shields.io/pypi/v/zizhenghua-quant.svg)](https://pypi.org/project/zizhenghua-quant/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/Zizhenghua/quant-data-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/Zizhenghua/quant-data-sdk/actions/workflows/test.yml)
[![Python](https://img.shields.io/pypi/pyversions/zizhenghua-quant.svg)](https://pypi.org/project/zizhenghua-quant/)

Official Python SDK for [Quant Data API](https://zizhenghua.com).

A 股行情、财务、行业、因子数据的官方 Python SDK。

---

## ✨ Features

- 🚀 一行代码获取 A 股数据
- 🤖 AI 代码生成（自然语言 → 策略代码）
- 🖥️ 自带 CLI（`quant-data` 命令）
- 📊 pandas 集成（`get_kline_df()` 等）
- ⚡ 异步支持（`AsyncQuantDataClient`）
- 🔐 自动处理 API Key 认证
- 🔁 内置重试、超时、错误处理
- 📝 完整的类型提示（type hints）
- 📦 支持上下文管理器（`with` 语法）
- 🆓 支持匿名调用（无需注册）

---

## 📦 Installation

```bash
# 基础
pip install zizhenghua-quant

# 带 pandas（DataFrame 支持）
pip install "zizhenghua-quant[pandas]"

# 带异步（httpx）
pip install "zizhenghua-quant[async]"

# 全部
pip install "zizhenghua-quant[all]"
```

---

## 🚀 Quick Start

### 1. 获取 API Key（可选）

匿名也能用，但限额较低。注册后可获得更高限额。

1. 访问 https://zizhenghua.com 注册账号
2. 登录后进入「账号设置」→「API Key 管理」
3. 点击「+ 创建新 Key」，复制保存（只显示一次）

### 2. 调用

```python
from quant_data_sdk import QuantDataClient

# 匿名（30 次/天 AI，10 次/分钟数据）
client = QuantDataClient()

# 或注册（100 次/天 AI，1000 次/天数据）
client = QuantDataClient(api_key="your_api_key_here")

# 获取贵州茅台实时行情
data = client.stock.get_realtime("600519")
print(data)
```

---

## 📖 使用示例

### 数据接口

```python
from quant_data_sdk import QuantDataClient

client = QuantDataClient(api_key="your_key")

# 实时行情
data = client.stock.get_realtime("600519")

# K 线
kline = client.stock.get_kline("600519", "2024-01-01", "2024-12-31")

# 多条件选股
stocks = client.stock.filter_stocks(minTurnover=5, minRoe=15)

# 市场统计
stats = client.market.get_stats()

# 行业数据
sectors = client.sector.get_performance()

# 财务指标
fin = client.fin.get_latest("600519")

# 多因子排名
ranking = client.factor.get_ranking(topN=20)
```

### pandas 集成

```python
# K 线 → DataFrame
df = client.stock.get_kline_df("600519", "2024-01-01", "2024-12-31")
df["ma5"] = df["close"].rolling(5).mean()
df["ma20"] = df["close"].rolling(20).mean()

# 涨幅榜 → DataFrame
df = client.stock.get_ranking_df()

# 行业 → DataFrame
df = client.sector.get_performance_df()
```

### 异步

```python
import asyncio
from quant_data_sdk import AsyncQuantDataClient

async def main():
    async with AsyncQuantDataClient() as client:
        results = await asyncio.gather(
            client.stock.get_realtime("600519"),
            client.stock.get_realtime("601318"),
            client.stock.get_realtime("300750"),
        )
        for r in results:
            print(r["name"], r["latestPrice"])

asyncio.run(main())
```

### AI 代码生成

```python
# 通用方法
result = client.ai.generate_code(
    prompt="我想查看茅台23年到25年的布林带回测情况",
    language="python"
)
code = client.ai.extract_code(result["raw"])

# 快捷方法
client.ai.generate_bollinger("600519", "2023-01-01", "2025-12-31")
client.ai.generate_ma_cross("600519", "2023-01-01", "2025-12-31", fast=5, slow=20)
client.ai.generate_rsi("600519", "2023-01-01", "2025-12-31", oversold=30, overbought=70)
client.ai.generate_macd("600519", "2023-01-01", "2025-12-31")
client.ai.generate_kdj("600519", "2023-01-01", "2025-12-31")
```

### 上下文管理器

```python
with QuantDataClient(api_key="your_key") as client:
    data = client.stock.get_realtime("600519")
    print(data)
# 自动关闭
```

### 自定义 base URL

```python
# 本地开发
client = QuantDataClient(
    api_key="your_key",
    base_url="http://127.0.0.1:8080/api"
)
```

---

## 🖥️ CLI

安装后自带 `quant-data` 命令行工具。

### 数据查询

```bash
# 实时行情
quant-data stock realtime 600519

# 批量
quant-data stock realtime 600519 601318 001359

# K 线
quant-data stock kline 600519 --start 2024-01-01 --end 2024-12-31

# 涨幅榜
quant-data stock ranking

# 选股
quant-data stock filter --min-turnover 5 --min-roe 15 --limit 20

# 市场统计
quant-data market stats

# 行业涨跌幅
quant-data sector performance

# 财务指标
quant-data fin latest 600519

# 多因子排名
quant-data factor ranking --top 5
```

### 导出文件

```bash
# 导出 K 线为 CSV
quant-data stock kline 600519 --start 2024-01-01 --end 2024-12-31 -o kline.csv

# 导出涨幅榜为 JSON
quant-data stock ranking -o ranking.json

# `-o` 可以放任意位置
quant-data -o ranking.json stock ranking
```

### AI 生成

```bash
# 生成策略代码
quant-data ai generate "写一个双均线策略"

# 保存到文件
quant-data ai generate "写一个双均线策略" -o backtest.py

# Java 版本
quant-data ai generate "写一个双均线策略" --language java -o Backtest.java
```

### 用 API Key

```bash
quant-data --api-key your_key stock realtime 600519
```

---

## 📊 限流

| 用户 | 数据接口 | AI 接口 |
|------|---------|--------|
| 匿名 | 10 次/分钟，10,000 行/分钟 | 30 次/天 |
| 注册 | 300 次/分钟，600,000 行/分钟，1000 次/天 | 100 次/天 |

超限时抛 `RateLimitError`，并提示注册。

---

## ❌ 错误处理

```python
from quant_data_sdk import QuantDataClient
from quant_data_sdk.exceptions import (
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

client = QuantDataClient(api_key="your_key")

try:
    data = client.stock.get_realtime("600519")
except AuthenticationError as e:
    print(f"认证失败: {e}")
except RateLimitError as e:
    print(f"限流: {e}")
except NotFoundError as e:
    print(f"资源不存在: {e}")
except ValidationError as e:
    print(f"参数错误: {e}")
```

---

## 📚 Documentation

- [快速开始](examples/quickstart.py)
- [K 线](examples/stock_kline.py)
- [选股](examples/filter_stocks.py)
- [AI 生成](examples/ai_generate.py)
- [API 文档](https://zizhenghua.com/swagger-ui/index.html)

---

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## 📄 License

[MIT](LICENSE)

---

## ⚠️ Disclaimer

数据仅供量化学习与策略回测研究之用，不构成任何投资建议。

AI 生成的代码不保证正确性，请自行检查后再使用。
