probar 0.1.0__tar.gz

probar-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# probar 本地缓存(后续版本落盘缓存目录)
+.probar_cache/
+
+# mkdocs 文档站构建输出
+site/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store

probar-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+本项目遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.1.0] - 2026-06-21
+
+首个公开发布。**稳定公共 API 仅含已实现接口**(下列);命名空间里的占位接口与路线图项**不属于** v0.1.0 稳定承诺。
+
+### Added
+
+- 按数据源拆分的独立命名空间:`pb.dc`(东方财富)/ `pb.tdx`(通达信)/ `pb.ths`(同花顺)。各源数据独立、口径可能不一致,按需选源;**不做"主源",不做跨源故障转移**。
+- 东方财富(`pb.dc`)已实现:`quote` / `quotes` / `kline` / `intraday` / `fund_flow` / `lhb` / `financials` / `securities`(全市场代码表)。
+- 共享基础设施:结构化异常模型、证券代码归一化、令牌桶限流、TTL 缓存、HTTP 传输(重试+限流)、能力矩阵 `pb.capabilities()`。
+- 离线解析测试(冻结真实响应 fixture)、GitHub CI(ruff / mypy / pytest)与每日 canary smoke。
+- 通达信(`pb.tdx`)已实现:`quotes` / `quote` 批量实时五档,**clean-room 自写二进制 TCP 协议(纯标准库 `socket`/`struct`/`zlib`,零第三方依赖)** + 服务器池业务探针;其余接口已声明、分批落地。同花顺(`pb.ths`)命名空间已声明接口面(stub),计划 v0.3 落地。
+- 东财抗限频优化:`dc.quotes` 改 push2 `ulist` 批量端点(一次多只、自动分批 ≤100),`dc.securities` 接 TTL 缓存(默认 1h、未拉满抛 `SchemaChanged` 不缓存残表),`dc.kline` 修复 `limit` 兜底(东财 beg=0 忽略 lmt 时只取最近 limit 根)。
+- 本地接口可视化测试台(`probar[playground]`,`python -m probar.playground`):网页列出全部接口,可选接口、填参数、运行,查看输入/输出 + 来源 + 耗时。
+- 工程规范 `docs/ENGINEERING_GUIDE.md` + 《项目总体方案》`docs/PROJECT_PLAN.md`(运维/发布/演进 + 决策记录)+ 贡献指南 + `.github` issue/PR 模板 + `SECURITY.md`。
+
+### 说明
+
+- 本库封装非官方/逆向接口,详见 README 免责声明。
+- 发布采用 PyPI Trusted Publishing(OIDC),见 `.github/workflows/release.yml`。
+
+[0.1.0]: https://github.com/anbeaman/probar/releases/tag/v0.1.0

probar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 probar contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

probar-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: probar
+Version: 0.1.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)

probar-0.1.0/README.md

@@ -0,0 +1,101 @@
+# 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)

probar-0.1.0/probar/__init__.py

@@ -0,0 +1,54 @@
+"""probar —— 稳定、可观测的 A 股数据接入层。
+
+按数据源拆分独立命名空间,每个命名空间只暴露该源**真实支持**的接口:
+
+    pb.dc    东方财富(HTTP/JSON,数据最全:实时 / 复权K / 资金流 / 龙虎榜 / 财报)
+    pb.tdx   通达信(自写二进制协议,行情底座:批量实时五档 / 历史分钟 / 历史逐笔)
+    pb.ths   同花顺(题材增强:问财 / 概念,best-effort 反爬,实验性)
+
+    pb.capabilities()   返回三源能力矩阵(DataFrame)
+
+各源数据**各自独立、口径可能不一致**:用户按需选源,probar 不做"主源"也不做跨源替换。
+设计原则见 README。本库为非官方/逆向接口封装,使用前请阅读免责声明。
+"""
+
+from ._version import __version__
+from .core.capabilities import capabilities
+from .core.errors import (
+    NetworkError,
+    NoData,
+    NotSupported,
+    ProbarError,
+    RateLimited,
+    SchemaChanged,
+)
+from .providers.eastmoney import EastMoney
+from .providers.tdx import Tdx
+from .providers.ths import Ths
+
+# 默认实例:绑定到各命名空间。高级用户可自建实例传入配置,如
+#     from probar import EastMoney
+#     dc = EastMoney(timeout=5, proxy="http://127.0.0.1:7890")
+dc = EastMoney()
+tdx = Tdx()
+ths = Ths()
+
+__all__ = [
+    "__version__",
+    "capabilities",
+    # 命名空间(默认实例)
+    "dc",
+    "tdx",
+    "ths",
+    # Provider 类(自定义配置时使用)
+    "EastMoney",
+    "Tdx",
+    "Ths",
+    # 异常
+    "ProbarError",
+    "NetworkError",
+    "RateLimited",
+    "NotSupported",
+    "NoData",
+    "SchemaChanged",
+]

probar-0.1.0/probar/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

probar-0.1.0/probar/core/__init__.py

@@ -0,0 +1,4 @@
+"""probar 共享基础设施层(L1):错误模型、数据契约、传输、限流、缓存、日历、代码归一化、能力矩阵。
+
+各数据源命名空间(dc/tdx/ths)都建立在这一层之上。
+"""

probar-0.1.0/probar/core/cache.py

@@ -0,0 +1,36 @@
+"""极简 TTL 内存缓存。
+
+盘中快照走短 TTL,避免重复请求打爆数据源;历史数据的落盘缓存留待后续版本
+(diskcache / sqlite)。
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any
+
+
+class TTLCache:
+    def __init__(self, ttl: float = 2.0, maxsize: int = 4096) -> None:
+        self.ttl = ttl
+        self.maxsize = maxsize
+        self._d: dict[Any, tuple[float, Any]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: Any) -> Any | None:
+        with self._lock:
+            item = self._d.get(key)
+            if item is None:
+                return None
+            expire, value = item
+            if expire < time.monotonic():
+                self._d.pop(key, None)
+                return None
+            return value
+
+    def set(self, key: Any, value: Any, ttl: float | None = None) -> None:
+        with self._lock:
+            if len(self._d) >= self.maxsize:
+                self._d.clear()  # 简单粗暴的逐出策略,scaffold 够用
+            self._d[key] = (time.monotonic() + (ttl if ttl is not None else self.ttl), value)

probar-0.1.0/probar/core/calendar.py

@@ -0,0 +1,17 @@
+"""交易日历(占位实现)。
+
+v0.1 仅按工作日粗判;接入交易所节假日表(以及午休/集合竞价时段判断)留待后续版本。
+TODO(v0.2): 内置或拉取 SSE/SZSE 节假日数据,补 ``is_open_now`` / ``previous_trading_day``。
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+
+def is_trading_day(d: date | datetime | None = None) -> bool:
+    """是否为交易日(当前仅排除周末,**未含法定节假日**)。"""
+    d = d or date.today()
+    if isinstance(d, datetime):
+        d = d.date()
+    return d.weekday() < 5

probar-0.1.0/probar/core/capabilities.py

@@ -0,0 +1,63 @@
+"""三源能力矩阵 —— 定稿。
+
+这是对三个**数据源本身**能力的参考记录(某源能不能提供某类数据),不是方法清单:
+各命名空间(pb.dc/tdx/ths)按路线图暴露其中**已实现或计划实现**的方法子集;
+真实可调用的方法以 ``dir(pb.dc)`` / IDE 自动补全为准。
+
+
+档位:
+    FULL ✅   强,可做主实现
+    PART 🔸   部分/弱/需二次计算
+    SOFT ⚠️   反爬脆,best-effort(同花顺多数能力)
+    NONE ❌   无,命名空间里不提供该接口
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+FULL, PART, SOFT, NONE = "✅", "🔸", "⚠️", "❌"
+
+# capability -> {dc, tdx, ths}
+CAPABILITIES: dict[str, dict[str, str]] = {
+    "实时快照 quote":           {"dc": FULL, "tdx": FULL, "ths": SOFT},
+    "五档盘口(仅L1)":           {"dc": FULL, "tdx": FULL, "ths": SOFT},
+    "当日分时 intraday":         {"dc": FULL, "tdx": FULL, "ths": SOFT},
+    "历史分时 intraday_hist":    {"dc": PART, "tdx": FULL, "ths": SOFT},
+    "当日逐笔 ticks":            {"dc": PART, "tdx": FULL, "ths": SOFT},
+    "历史逐笔 ticks_hist":       {"dc": NONE, "tdx": PART, "ths": NONE},
+    "K线 日/周/月":              {"dc": FULL, "tdx": FULL, "ths": SOFT},
+    "K线 分钟":                  {"dc": PART, "tdx": FULL, "ths": SOFT},
+    "前/后复权 adjust":          {"dc": FULL, "tdx": PART, "ths": SOFT},
+    "资金流 fund_flow":          {"dc": FULL, "tdx": NONE, "ths": SOFT},
+    "龙虎榜 lhb":                {"dc": FULL, "tdx": NONE, "ths": SOFT},
+    "北向/沪深港通 hsgt":        {"dc": PART, "tdx": NONE, "ths": SOFT},
+    "财务报表/业绩 financials":  {"dc": FULL, "tdx": PART, "ths": SOFT},
+    "股东/解禁/分红":            {"dc": FULL, "tdx": PART, "ths": SOFT},
+    "板块/概念成分":             {"dc": FULL, "tdx": PART, "ths": SOFT},
+    "细粒度概念题材":            {"dc": PART, "tdx": PART, "ths": SOFT},
+    "自然语言选股 wencai":       {"dc": NONE, "tdx": NONE, "ths": SOFT},
+    "证券代码表 securities":     {"dc": FULL, "tdx": FULL, "ths": PART},
+    "除权除息 xdxr":             {"dc": FULL, "tdx": FULL, "ths": SOFT},
+    "多市场(港美/期货/基金/转债)": {"dc": FULL, "tdx": PART, "ths": SOFT},
+}
+
+# 同花顺整体为反爬 best-effort:内容(题材/问财)是三源最强,但抓取可靠性最低。
+NOTES = {
+    "ths": "全程反爬(hexin-v),best-effort;问财与细粒度概念题材为其独有价值。",
+    "tdx": "无资金流/龙虎榜/北向(协议无此数据域);复权需用 xdxr 自算;逐笔为分笔明细非 L2。",
+    "dc": "数据最全(实时/复权/资金流/龙虎榜/财报);北向实时盘中已停披露,仅 EOD/额度。",
+}
+
+
+def capabilities() -> pd.DataFrame:
+    """返回能力矩阵(行=能力,列=dc/tdx/ths)。"""
+    import pandas as pd
+
+    df = pd.DataFrame(CAPABILITIES).T
+    df = df[["dc", "tdx", "ths"]]
+    df.index.name = "capability"
+    return df

probar-0.1.0/probar/core/errors.py

@@ -0,0 +1,32 @@
+"""结构化异常模型。
+
+调用方可按类型精确处理:网络抖动重试、限频退避、源不支持降级、无数据跳过。
+其中 ``SchemaChanged`` 通常意味着上游接口字段变更 —— 正是每日 canary 巡检要替用户
+最先发现的那一类。
+"""
+
+from __future__ import annotations
+
+
+class ProbarError(Exception):
+    """probar 所有异常的基类。"""
+
+
+class NetworkError(ProbarError):
+    """网络/超时/连接失败(已穷尽重试)。"""
+
+
+class RateLimited(ProbarError):
+    """被数据源限频(如 HTTP 429)。"""
+
+
+class NotSupported(ProbarError):
+    """该数据源不支持此接口(能力矩阵中标记为无)。"""
+
+
+class NoData(ProbarError):
+    """请求合法但无数据(停牌 / 未上市 / 区间无成交)。"""
+
+
+class SchemaChanged(ProbarError):
+    """上游响应结构与预期契约不符,接口可能已变更。"""

probar-0.1.0/probar/core/http.py

@@ -0,0 +1,69 @@
+"""基于 httpx 的同步 HTTP 传输层:统一超时、限流、退避重试、默认请求头。
+
+只负责"把请求安全地发出去、把 JSON 拿回来",不关心字段语义(解析交给各 provider)。
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from .errors import NetworkError, RateLimited
+from .rate_limit import TokenBucket
+
+DEFAULT_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+    ),
+    "Accept": "*/*",
+}
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        timeout: float = 8.0,
+        rate: float = 10.0,
+        proxy: str | None = None,
+        headers: dict[str, str] | None = None,
+        retries: int = 3,
+    ) -> None:
+        self._bucket = TokenBucket(rate)
+        self._retries = max(1, retries)
+        client_kwargs: dict[str, Any] = {
+            "timeout": timeout,
+            "headers": {**DEFAULT_HEADERS, **(headers or {})},
+            "follow_redirects": True,
+        }
+        if proxy:  # 仅在显式传入时才加,避免老版 httpx 不识别 proxy/proxies 之别
+            client_kwargs["proxy"] = proxy
+        self._client = httpx.Client(**client_kwargs)
+
+    def get_json(
+        self, url: str, params: dict[str, Any] | None = None, *, referer: str | None = None
+    ) -> Any:
+        """限流 + 重试地发起 GET 并解析 JSON。失败穷尽重试后抛 :class:`NetworkError`。"""
+        headers = {"Referer": referer} if referer else None
+        last_err: Exception | None = None
+        for attempt in range(self._retries):
+            self._bucket.acquire()
+            try:
+                resp = self._client.get(url, params=params, headers=headers)
+                if resp.status_code == 429:
+                    raise RateLimited(f"429 Too Many Requests: {url}")
+                resp.raise_for_status()
+                # 非 JSON(被 WAF 拦截返回 HTML 等)时 .json() 抛 ValueError,纳入重试与分类
+                return resp.json()
+            except RateLimited:
+                raise
+            except (httpx.TransportError, httpx.HTTPStatusError, ValueError) as err:
+                last_err = err
+                time.sleep(0.3 * (attempt + 1))
+        raise NetworkError(f"GET {url} 失败(已重试 {self._retries} 次): {last_err!r}")
+
+    def close(self) -> None:
+        self._client.close()