Metadata-Version: 2.4
Name: ashareapi
Version: 0.1.8
Summary: A股数据 API 官方 Python SDK —— 行情 / K线 / 财务 / 资金 / 龙虎榜 / 板块 / 因子选股（含 MCP）
Author: ashareapi
License-Expression: MIT
Project-URL: Homepage, https://ashareapi.com
Project-URL: Documentation, https://ashareapi.com/docs/
Project-URL: Endpoint list, https://ashareapi.com/endpoints/
Project-URL: Changelog, https://ashareapi.com/changelog
Keywords: a-share,ashare,stock,quant,finance,mcp,stock-data-api,financial-data-api
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# ashareapi — A股数据 API 官方 Python SDK

**行情 / K线 / 财务 / 资金 / 龙虎榜 / 板块 / 因子选股** —— 32 个端点，**免费端点无需注册**。

```bash
pip install ashareapi            # 基础（返回 list[dict]）
pip install "ashareapi[pandas]"  # 加 DataFrame 支持（推荐）
```

## 30 秒上手

```python
from ashareapi import AShareAPI

cli = AShareAPI()                     # 免费端点无需 Key
df = cli.quote("sh600667")            # 实时行情 → DataFrame
print(df[["date", "last", "turnover"]])

print(cli.kline("600667.SH", count=5))  # 代码格式随便写（自动归一化）
print(cli.hot(limit=10))                # 热搜榜
```

**付费端点**（财务 / 资金 / 龙虎榜 / 选股等）需要 Key（[获取](https://ashareapi.com/pricing)，¥9.9 起）：

```python
cli = AShareAPI("ct-你的Key")          # 或设环境变量 ASHARE_API_KEY
df = cli.screen(preset="low_pe", orderby="ROETTM", limit=10)
print(df.head())
```

## 为什么用它

- **免费端点真的免 Key**：`quote / kline / hot / market-overview / changedist` 直接调，无需注册
- **代码格式兼容**：`sh600667` / `600667.SH` / `600667` 都认（不同写法的项目都能直接用）
- **多源自动切换**：后端 67 个数据源互为备份，取数失败会自动换源且**不扣调用次数**
- **错误分类清楚**：`AuthError` / `RateLimitError` / `UpstreamError` / `EmptyResultError`（无数据 ≠ 失败）—— 每类都告诉你该做什么
- **pandas 可选**：不想装 pandas 也能用（返回 `list[dict]`）

## 端点一览

| 方法 | 说明 | 免 Key |
|---|---|---|
| `quote(code)` | 实时行情快照 | ✅ |
| `kline(code, period, count)` | K 线（日/周/月）· **口径固定为前复权** | ✅ |
| `hot(limit)` | 热搜榜 | ✅ |
| `market_overview(type)` | 市场总览（画像/估值/风格轮动）| ✅ |
| `changedist()` | 涨跌分布（市场广度）| ✅ |
| `finance(code, num)` | 三大报表 | — |
| `fund(code)` | 资金流 + 龙虎榜 + 大宗 + 两融 | — |
| `technical(code)` | MA / MACD / KDJ / RSI / BOLL | — |
| `lhb(type)` | 龙虎榜分榜（机构 / 游资 / 活跃席位）| — |
| `screen(expr/preset, ...)` | 因子选股 | — |
| `search(q)` | 搜索消歧 | — |

> ⚠️ **K 线价格口径固定为前复权**（除权除息日不跳空；**没有** `adjust` 参数）—— **不要再自己复权**（会二次复权）。

（完整 32 端点见 [端点清单](https://ashareapi.com/endpoints)）

## 错误处理

```python
from ashareapi import AShareAPI, AuthError, RateLimitError, UpstreamError, EmptyResultError

cli = AShareAPI()
try:
    df = cli.fund("sh600667")
except AuthError as e:          # 401 / 缺 Key → 去拿 Key
    print(e)
except RateLimitError as e:     # 429 → 降频 / 解 PoW 挑战提额 / 升级档位
    print(e)
except UpstreamError as e:      # 上游取数失败（已自动换源、不扣次数）→ 重试一次通常就好
    print(e)
except EmptyResultError as e:   # 当前无数据（如当天无大宗交易）→ 不计费，换条件或稍后再试
    print(e)
```

## 也用 AI Agent（MCP / Agent Skill）

除了 Python SDK，我们还提供两种 **AI Agent** 接入方式：

- **MCP 服务器**（Streamable HTTP）—— 服务器地址 **`https://api.ashareapi.com/mcp`**
  （⚠️ 填**这个**接口地址；站点介绍页 `ashareapi.com/mcp` **不是**接口）
- **各客户端配置写法**（Claude Code / Cursor / VS Code / Codex 等 **19 家**，键名差异都核对过官方文档）：
  <https://ashareapi.com/mcp>
- **Agent Skill**（给 AI Agent 读的接口说明书 + 分发包，装进 skills 目录即用）：<https://ashareapi.com/skill>

> 免费工具/端点**无需 Key**；付费工具在请求头带 `Authorization: Bearer <你的 Key>`。

## 版本记录

**当前版本：`0.1.8`**（2026-09-28）

| 版本 | 变更 |
|---|---|
| `0.1.8` | 文档措辞修订：价格口径（前复权）在 README / 方法文档 / CHANGELOG 中表述统一 · MCP 地址与 Agent Skill 说明更明确 |
| `0.1.7` | 文档：明确 **MCP 服务器地址** `https://api.ashareapi.com/mcp` · 新增 **Agent Skill** 说明（`/skill`）· 变更记录链接改为可直接点开的绝对地址 |
| `0.1.6` | 文档：`kline()` 写明**价格口径**（前复权 · 无 `adjust` 参数 · 勿二次复权）|
| `0.1.5` | 文档：换手率字段示例更新为 `turnover` · 补齐 `0.1.3` / `0.1.4` 两行 · 元数据 `Changelog` 指向站内更新日志 |
| `0.1.4` | 修 `finance()` 返回值退化（**原样返回表列表**）· `shareholder()` / `calendar()` 多段结构锁定 · User-Agent 版本号不再漂移 |
| `0.1.3` | 文档修订（`snapshot()` / `orderbook()` 边界）· 新增 `CHANGELOG.md` + `MANIFEST.in` |
| `0.1.2` | 新增 `snapshot()`（全字段画像）· 方法数 31 → 32 |
| `0.1.1` | 新增 `orderbook()`（五档盘口）· 方法数 30 → 31 |
| `0.1.0` | 首个版本（30 个方法 · 5 个免费端点）|

> ⚠️ **端点本身永远是最新的**（服务端演进，**无需升级 SDK**）—— 升级只是为了用上**新增的便利方法**。

完整变更记录 → 包内 `CHANGELOG.md` · [站内更新日志](https://ashareapi.com/changelog) · [PyPI 版本历史](https://pypi.org/project/ashareapi/#history)

## License

MIT · 数据仅供研究参考，不构成投资建议
