Skip to content

Commit e6afdee

Browse files
author
FutuAPI Developer
committed
feat: hhxg Python SDK v0.1.0 — A股日报快照 SDK
零配置、类型安全、AI 原生的 A 股市场数据 Python SDK。 - 21 个 Pydantic v2 模型，严格对齐 skill_snapshot.json schema v3 - HhxgClient: httpx + 内存缓存，同步 API - 7 个便捷函数: get_snapshot/market/hot_themes/sectors/ladder/hotmoney/news - 29 个测试全部通过 - hatchling 打包，支持 Python 3.9-3.13 - MIT 许可证
0 parents  commit e6afdee

16 files changed

Lines changed: 1234 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install dependencies
25+
run: |
26+
python -m pip install --upgrade pip
27+
pip install -e ".[dev]" 2>/dev/null || pip install -e .
28+
pip install pytest ruff
29+
30+
- name: Lint with ruff
31+
run: ruff check src/ tests/
32+
33+
- name: Run tests
34+
run: pytest tests/ -v

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
dist/
5+
build/
6+
.pytest_cache/
7+
.ruff_cache/
8+
*.egg
9+
.venv/
10+
venv/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 恢恢量化 (hhxg.top)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# hhxg — A 股日报快照 SDK
2+
3+
> 零配置、类型安全、AI 原生的 A 股市场数据 Python SDK
4+
5+
[![PyPI](https://img.shields.io/pypi/v/hhxg?color=blue)](https://pypi.org/project/hhxg/)
6+
[![Python](https://img.shields.io/pypi/pyversions/hhxg)](https://pypi.org/project/hhxg/)
7+
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
8+
[![CI](https://github.com/hhxg-top/hhxg-python/actions/workflows/ci.yml/badge.svg)](https://github.com/hhxg-top/hhxg-python/actions)
9+
10+
---
11+
12+
## 为什么选 hhxg？
13+
14+
| 特性 | tushare | akshare | **hhxg** |
15+
|------|---------|---------|----------|
16+
| 需要注册 | 是（Token） | 否 | **否** |
17+
| 需要配置 | 是 | 否 | **否** |
18+
| 返回类型 | DataFrame | DataFrame | **Pydantic 模型** |
19+
| 类型提示 | 无 | 无 | **完整类型安全** |
20+
| AI 友好 | 否 | 否 | **MCP + GPT + SDK** |
21+
| 数据范围 | 全量历史 | 全量历史 | **日报快照** |
22+
23+
**hhxg 的定位**：不追求全量历史数据，专注于**每日市场快照**——赚钱效应、热门题材、资金流向、连板天梯、游资龙虎榜、焦点新闻，一个函数调用获取全部。
24+
25+
---
26+
27+
## 30 秒上手
28+
29+
```bash
30+
pip install hhxg
31+
```
32+
33+
```python
34+
import hhxg
35+
36+
snapshot = hhxg.get_snapshot()
37+
print(f"赚钱效应: {snapshot.market.sentiment_index}%")
38+
print(f"最高连板: {snapshot.ladder.top_streak.name} {snapshot.ladder.max_streak}板")
39+
```
40+
41+
输出：
42+
43+
```
44+
赚钱效应: 61.8%
45+
最高连板: 豫能控股 7板
46+
```
47+
48+
---
49+
50+
## 完整 API
51+
52+
| 函数 | 返回类型 | 说明 |
53+
|------|----------|------|
54+
| `get_snapshot()` | `Snapshot` | 完整日报快照 |
55+
| `get_market()` | `Market` | 市场赚钱效应、涨跌分布 |
56+
| `get_hot_themes()` | `list[HotTheme]` | 热门题材及龙头股 |
57+
| `get_sectors()` | `list[SectorGroup]` | 行业/板块资金流向 |
58+
| `get_ladder()` | `LadderDetail` | 连板天梯（含晋级率） |
59+
| `get_hotmoney()` | `Hotmoney` | 游资龙虎榜（含席位明细） |
60+
| `get_news()` | `list[NewsItem]` | 焦点新闻 |
61+
62+
所有函数零配置、开箱即用，返回 Pydantic 模型，IDE 自动补全。
63+
64+
---
65+
66+
## 数据内容
67+
68+
每日快照涵盖：
69+
70+
- **市场赚钱效应** — 情绪指数、涨跌家数分布、结构差值
71+
- **热门题材** — TOP 题材及涨停数、净流入、龙头股
72+
- **行业/板块资金** — 强势/弱势板块、净流入排名、领涨股
73+
- **连板天梯** — 各级连板股票、晋级率、地域/概念分布
74+
- **游资龙虎榜** — 净买入 TOP、知名游资席位操作明细
75+
- **焦点新闻** — 市场焦点 + 宏观新闻
76+
- **AI 摘要** — 一句话概括当日市场
77+
78+
---
79+
80+
## 搭配 Pandas
81+
82+
```python
83+
import hhxg
84+
import pandas as pd
85+
86+
themes = hhxg.get_hot_themes()
87+
df = pd.DataFrame([
88+
{"题材": t.name, "涨停数": t.limitup_count, "净流入(亿)": t.net_yi}
89+
for t in themes
90+
])
91+
print(df.to_string(index=False))
92+
```
93+
94+
```
95+
题材 涨停数 净流入(亿)
96+
绿色电力 16 0.22
97+
风电 16 8.17
98+
小金属概念 15 19.38
99+
昨日高振幅 14 30.84
100+
最近多板 13 13.80
101+
核电 11 4.18
102+
```
103+
104+
---
105+
106+
## 高级用法
107+
108+
### 自定义客户端
109+
110+
```python
111+
from hhxg import HhxgClient
112+
113+
client = HhxgClient(
114+
base_url="https://your-mirror.com/snapshot.json",
115+
timeout=30.0,
116+
)
117+
snapshot = client.get_snapshot()
118+
```
119+
120+
### 强制刷新缓存
121+
122+
```python
123+
from hhxg import HhxgClient
124+
125+
client = HhxgClient()
126+
snapshot = client.get_snapshot(force=True) # 跳过内存缓存
127+
```
128+
129+
---
130+
131+
## AI 生态联动
132+
133+
hhxg 是[恢恢量化](https://hhxg.top) AI 生态的一部分：
134+
135+
| 接入方式 | 适用场景 | 状态 |
136+
|----------|----------|------|
137+
| **Python SDK**（本项目） | 量化研究、数据分析 | ✅ 可用 |
138+
| **MCP Server** | Claude Desktop / Cursor | 🚧 开发中 |
139+
| **GPT Action** | ChatGPT 自定义 GPT | 🚧 开发中 |
140+
141+
---
142+
143+
## 数据来源
144+
145+
数据由 [恢恢量化](https://hhxg.top) 每日盘后更新，覆盖 5000+ 只 A 股。
146+
147+
> 数据仅供研究参考，不构成投资建议。
148+
149+
---
150+
151+
## 更多功能
152+
153+
SDK 提供每日市场快照数据。如需以下高级功能，请访问 [hhxg.top](https://hhxg.top)：
154+
155+
- 可视化图表与趋势分析
156+
- AI 多因子选股工具
157+
- ETF 资金流向筛选
158+
- 历史数据回溯
159+
- AI 智能问答
160+
161+
---
162+
163+
## License
164+
165+
[MIT](LICENSE) © [恢恢量化](https://hhxg.top)

‎examples/pandas_analysis.py‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
"""Combine hhxg with pandas for deeper analysis."""
2+
3+
import hhxg
4+
5+
try:
6+
import pandas as pd
7+
except ImportError:
8+
raise SystemExit("This example requires pandas: pip install pandas")
9+
10+
snapshot = hhxg.get_snapshot()
11+
12+
# ---- Hot themes → DataFrame ----
13+
themes_data = [
14+
{
15+
"题材": t.name,
16+
"涨停数": t.limitup_count,
17+
"净流入(亿)": t.net_yi,
18+
"龙头": t.top_stocks[0].name if t.top_stocks else "",
19+
}
20+
for t in snapshot.hot_themes
21+
]
22+
df_themes = pd.DataFrame(themes_data)
23+
print("=== 热门题材 ===")
24+
print(df_themes.to_string(index=False))
25+
26+
# ---- Sector fund flow → DataFrame ----
27+
rows = []
28+
for group in snapshot.sectors:
29+
for item in group.strong:
30+
rows.append({"分组": group.label, "方向": "强势", "名称": item.name, "净流入(亿)": item.net_yi})
31+
for item in group.weak:
32+
rows.append({"分组": group.label, "方向": "弱势", "名称": item.name, "净流入(亿)": item.net_yi})
33+
df_sectors = pd.DataFrame(rows)
34+
print("\n=== 行业资金流 ===")
35+
print(df_sectors.to_string(index=False))
36+
37+
# ---- Hotmoney top buys ----
38+
if snapshot.hotmoney:
39+
buys = [
40+
{"股票": b.name, "净买入(亿)": b.net_yi, "占比%": b.ratio_pct}
41+
for b in snapshot.hotmoney.top_net_buy
42+
]
43+
df_buys = pd.DataFrame(buys)
44+
print(f"\n=== 游资净买入 TOP (合计 {snapshot.hotmoney.total_net_yi:.1f} 亿) ===")
45+
print(df_buys.to_string(index=False))

‎examples/quick_start.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
"""Quick start: 3 lines to get A-share market data."""
2+
3+
import hhxg
4+
5+
snapshot = hhxg.get_snapshot()
6+
print(f"日期: {snapshot.date}")
7+
print(f"赚钱效应: {snapshot.market.sentiment_index}% ({snapshot.market.sentiment_label})")
8+
print(f"涨停: {snapshot.market.limit_up} 炸板: {snapshot.market.fried}")
9+
print(f"\n热门题材:")
10+
for theme in snapshot.hot_themes[:5]:
11+
leaders = ", ".join(s.name for s in theme.top_stocks[:2])
12+
print(f" {theme.name} — 涨停 {theme.limitup_count} 家 | 龙头: {leaders}")

‎pyproject.toml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
[build-system]
2+
requires = ["hatchling"]
3+
build-backend = "hatchling.build"
4+
5+
[project]
6+
name = "hhxg"
7+
version = "0.1.0"
8+
description = "A-share daily market snapshot SDK — zero-config, type-safe, AI-native"
9+
readme = "README.md"
10+
license = "MIT"
11+
requires-python = ">=3.9"
12+
authors = [
13+
{ name = "恢恢量化", email = "hi@hhxg.top" },
14+
]
15+
keywords = [
16+
"A股",
17+
"stock",
18+
"quant",
19+
"finance",
20+
"market-data",
21+
"china-stock",
22+
"sdk",
23+
"mcp",
24+
"pydantic",
25+
"tushare",
26+
"akshare",
27+
]
28+
classifiers = [
29+
"Development Status :: 4 - Beta",
30+
"Intended Audience :: Developers",
31+
"Intended Audience :: Financial and Insurance Industry",
32+
"License :: OSI Approved :: MIT License",
33+
"Programming Language :: Python :: 3",
34+
"Programming Language :: Python :: 3.9",
35+
"Programming Language :: Python :: 3.10",
36+
"Programming Language :: Python :: 3.11",
37+
"Programming Language :: Python :: 3.12",
38+
"Programming Language :: Python :: 3.13",
39+
"Topic :: Office/Business :: Financial :: Investment",
40+
"Topic :: Software Development :: Libraries :: Python Modules",
41+
"Typing :: Typed",
42+
]
43+
dependencies = [
44+
"httpx>=0.25.0",
45+
"pydantic>=2.0.0",
46+
]
47+
48+
[project.urls]
49+
Homepage = "https://hhxg.top"
50+
Repository = "https://github.com/hhxg-top/hhxg-python"
51+
Documentation = "https://github.com/hhxg-top/hhxg-python#readme"
52+
Issues = "https://github.com/hhxg-top/hhxg-python/issues"
53+
Changelog = "https://github.com/hhxg-top/hhxg-python/releases"
54+
55+
[tool.hatch.build.targets.wheel]
56+
packages = ["src/hhxg"]
57+
58+
[tool.pytest.ini_options]
59+
testpaths = ["tests"]
60+
61+
[tool.ruff]
62+
target-version = "py39"
63+
line-length = 88
64+
65+
[tool.ruff.lint]
66+
select = ["E", "F", "I", "W", "UP", "B", "SIM"]

0 commit comments

Comments
 (0)