Metadata-Version: 2.4
Name: probar
Version: 0.4.0
Summary: 稳定、可观测的 A 股数据接入层 —— 覆盖东方财富、通达信、同花顺
Project-URL: Homepage, https://github.com/anbeaman/probar
Project-URL: Issues, https://github.com/anbeaman/probar/issues
Author: anbeaman
License: MIT
License-File: LICENSE
Keywords: a-share,eastmoney,quant,stock,tdx,tonghuashun,行情,量化
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.0
Provides-Extra: async
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: playground
Requires-Dist: fastapi>=0.110; extra == 'playground'
Requires-Dist: uvicorn>=0.29; extra == 'playground'
Provides-Extra: tdx
Provides-Extra: ths
Description-Content-Type: text/markdown

# probar

稳定、可观测的 **A 股数据接入层** —— 覆盖东方财富、通达信、同花顺,既能做量化,也能取盘中实时行情。

> 设计目标不是"接口最多",而是 **接口坏了能最快发现、最快修、用户最少踩坑**。
> 数据层优先:回测交给 backtrader / vnpy 等框架,probar 专注把三源数据统一、可靠地喂出来。

[![ci](https://github.com/anbeaman/probar/actions/workflows/ci.yml/badge.svg)](https://github.com/anbeaman/probar/actions/workflows/ci.yml)

## 安装

```bash
pip install probar                # 核心:东方财富(pb.dc) + 通达信(pb.tdx)
pip install "probar[ths]"         # 实验性:同花顺 / 问财(pb.ths,反爬 best-effort)
pip install "probar[async]"       # 异步全市场扫描(v0.2)
pip install "probar[playground]"  # 本地接口可视化测试台
```

## 接口测试台(本地)

一个可视化网页,列出全部接口,可选接口、填参数、运行,查看输入/输出(表格 + 来源 + 耗时):

```bash
pip install "probar[playground]"
python -m probar.playground        # 打开 http://127.0.0.1:8787
```

左侧选数据源/接口(●已实现 / ○未实现)→ 填参数 → 运行。仅本地开发测试用,会真实联网取数。

## 按数据源拆分的命名空间

每个命名空间**只暴露该源真实支持的接口**。`pb.capabilities()` 记录三源能力(参考),
各命名空间暴露其中已实现或计划实现的方法子集。

> **已实现**:`pb.dc` 的 `quote / quotes / kline / intraday / fund_flow / lhb / financials / securities`(东财全链路);
> `pb.tdx` 的 `quotes / quote`(批量实时五档,clean-room 自写二进制协议、纯标准库零依赖)。
> 其余接口已在命名空间中声明,调用抛 `NotImplementedError` 并注明计划版本;`pb.ths`(同花顺,实验性)计划 v0.3。

```python
import probar as pb

# 东方财富(HTTP/JSON,数据最全)
pb.dc.quote("600519.SH")
pb.dc.kline("600519.SH", freq="1d", adjust="qfq")
pb.dc.fund_flow("000001.SZ")

# 通达信(自写二进制协议:批量实时五档;历史分钟/逐笔规划中)
pb.tdx.quotes(["000001.SZ", "600519.SH"])   # 一次多只,含 L1 五档盘口

# 同花顺(题材增强:问财 / 概念;实验性,v0.3 规划)
# pb.ths.wencai("近5日主力净流入为正且市值<100亿")   # 规划中(stub,当前抛 NotImplementedError)

# 能力矩阵(各源能力参考;各源数据独立,不互相替换)
pb.capabilities()
```

高级用户可自建实例传入配置:

```python
from probar import EastMoney
dc = EastMoney(timeout=5, proxy="http://127.0.0.1:7890")
dc.kline("000001.SZ")
```

## 三源分工

| 源 | 命名空间 | 定位 | 强项 | 短板 |
|---|---|---|---|---|
| 东方财富 | `pb.dc` | 综合最全(HTTP) | 实时/复权K/资金流/龙虎榜/财报/多市场最全 | 历史逐笔无;北向实时已停披露 |
| 通达信 | `pb.tdx` | 行情底座 | 批量实时、历史分钟、**历史逐笔** | 无资金流/龙虎榜/北向;复权需自算 |
| 同花顺 | `pb.ths` | 题材增强(实验) | **问财 NL 选股**、最细概念题材 | 全程反爬,best-effort |

完整能力矩阵见 `pb.capabilities()` 或 [`probar/core/capabilities.py`](probar/core/capabilities.py)。

## 路线图

- **v0.1**:东财全链路(`quote/quotes/kline/intraday/fund_flow/lhb/financials/securities`)+ 统一 schema + 命名空间骨架 + 离线测试 + CI + PyPI。
- **v0.2**(进行中):通达信 **clean-room 二进制协议**(已落地 `quotes/quote` 五档 + 服务器池业务探针)→ 续做 `kline/intraday/ticks/xdxr`;异步全市场 + 国内 canary 节点。
- **v0.3**:数据质量标记 + 状态页 + 同花顺(问财/概念,实验性)。
- 暂缓:港美/期货/基金、指标层。

## 稳定性 / 每日维护

- 离线层:解析器单测(冻结样本)+ schema 契约 + ruff/mypy,见 [`ci.yml`](.github/workflows/ci.yml)。
- 实网层:每日 canary([`scripts/canary.py`](scripts/canary.py))打真实接口并**分类失败**(网络/限频/schema/数据)。
  GitHub runner 在境外会有误报,故 v0.1 为 soft smoke;v0.2 迁国内节点做主巡检。

## 免责声明

本库封装的是各平台**非官方 / 逆向**接口,仅供学习与研究使用。数据版权归东方财富、
通达信、同花顺等平台所有;使用者须遵守各平台服务条款,自行承担合规与风险。本库已内置
限流以做"友好访问",**不保证接口长期可用**,不对数据准确性或由此产生的任何损失负责。

## 开发协作

本项目维护实行**多方交叉复核**:任何实质性变更在交付前都会经过独立复核、显式标注分歧。
工程规范见 [docs/ENGINEERING_GUIDE.md](docs/ENGINEERING_GUIDE.md)、贡献见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## License

[MIT](LICENSE)
