Metadata-Version: 2.4
Name: ashareapi
Version: 0.1.0
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
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线 / 财务 / 资金 / 龙虎榜 / 板块 / 因子选股** —— 30 个端点，**免费端点无需注册**。

```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", "exchange"]])

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)` | 搜索消歧 | — |

（完整 30 端点见 [端点清单](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）

除了 Python，我们还提供 **MCP 服务器**（Streamable HTTP）—— 一条 URL 接进 Claude Code / Cursor / Codex 等 19 家客户端：
**https://ashareapi.com/mcp**

## License

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