probar 0.1.0__py3-none-any.whl

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/_version.py

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

probar/core/__init__.py

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

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/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/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/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/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()

probar/core/models.py

@@ -0,0 +1,79 @@
+"""数据契约(统一核心 schema)。
+
+设计取舍:大表行情**不做逐行 pydantic 校验**,只用轻量的
+"列存在 + dtype" 断言;严格校验留给 canary / ``validate=True``。各源同名接口返回
+同一套**核心列**,源特有的额外字段放进 ``df.attrs['extras']`` 或 ``raw``。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from .errors import SchemaChanged
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+# 同名接口的核心列契约(跨源一致)
+KLINE_COLUMNS = [
+    "symbol",
+    "date",
+    "open",
+    "high",
+    "low",
+    "close",
+    "volume",
+    "amount",
+    "pct_chg",
+    "turnover",
+]
+
+QUOTE_COLUMNS = [
+    "symbol",
+    "name",
+    "price",
+    "open",
+    "high",
+    "low",
+    "prev_close",
+    "volume",
+    "amount",
+    "pct_chg",
+]
+
+# 全市场证券列表(securities)
+SECURITIES_COLUMNS = ["symbol", "code", "name", "market", "asset_type"]
+
+# 通达信实时五档快照(quote):核心列 + L1 盘口五档 + 内外盘/现手/服务器时间。
+# name 恒为 None(TDX 行情协议不返回名称);inner_vol/outer_vol 为内盘/外盘。
+TDX_QUOTE_COLUMNS = [
+    *QUOTE_COLUMNS,  # symbol,name,price,open,high,low,prev_close,volume,amount,pct_chg
+    "bid1", "bid_vol1", "ask1", "ask_vol1",
+    "bid2", "bid_vol2", "ask2", "ask_vol2",
+    "bid3", "bid_vol3", "ask3", "ask_vol3",
+    "bid4", "bid_vol4", "ask4", "ask_vol4",
+    "bid5", "bid_vol5", "ask5", "ask_vol5",
+    "cur_vol", "inner_vol", "outer_vol", "servertime",
+]
+
+
+def ensure_columns(
+    df: pd.DataFrame, required: Iterable[str], *, source: str, interface: str
+) -> pd.DataFrame:
+    """校验 DataFrame 至少包含 ``required`` 列,否则抛 :class:`SchemaChanged`。"""
+    missing = [c for c in required if c not in df.columns]
+    if missing:
+        raise SchemaChanged(
+            f"[{source}.{interface}] 响应缺少字段 {missing};上游接口可能已变更。"
+            f" 实得列: {list(df.columns)}"
+        )
+    return df
+
+
+def stamp(df: pd.DataFrame, *, source: str, **meta: object) -> pd.DataFrame:
+    """在 ``df.attrs`` 写入来源等溯源信息(provenance)。"""
+    df.attrs["source"] = source
+    for k, v in meta.items():
+        df.attrs[k] = v
+    return df

probar/core/rate_limit.py

@@ -0,0 +1,35 @@
+"""线程安全的令牌桶限流器,用于对每个数据源做"友好爬取",降低被限频/封 IP 的风险。"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+
+class TokenBucket:
+    """经典令牌桶。``rate`` 为每秒补充的令牌数,``capacity`` 为桶容量(默认等于 rate)。"""
+
+    def __init__(self, rate: float, capacity: float | None = None) -> None:
+        if rate <= 0:
+            raise ValueError(f"rate 必须 > 0,得到 {rate!r}")
+        self.rate = float(rate)
+        # 容量至少为 1,否则低频限流(rate<1)下 acquire(1) 永远取不到令牌而死锁
+        self.capacity = float(capacity if capacity is not None else max(rate, 1.0))
+        self._tokens = self.capacity
+        self._last = time.monotonic()
+        self._lock = threading.Lock()
+
+    def acquire(self, n: float = 1.0) -> None:
+        """阻塞直到取到 ``n`` 个令牌。``n`` 超过桶容量会永远取不到,直接报错。"""
+        if n > self.capacity:
+            raise ValueError(f"单次请求 {n} 个令牌超过桶容量 {self.capacity}")
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                self._tokens = min(self.capacity, self._tokens + (now - self._last) * self.rate)
+                self._last = now
+                if self._tokens >= n:
+                    self._tokens -= n
+                    return
+                wait = (n - self._tokens) / self.rate
+            time.sleep(wait)

probar/core/symbols.py

@@ -0,0 +1,89 @@
+"""证券代码归一化。
+
+统一内部表示为 ``Symbol(code, market)``,market ∈ {SH, SZ, BJ}。
+对外规范文本形如 ``600519.SH`` / ``000001.SZ``;并提供到各数据源的格式转换:
+
+    to_eastmoney_secid("600519.SH") -> "1.600519"
+    to_tdx("000001.SZ")            -> (0, "000001")
+
+接受的输入:``600519`` / ``600519.SH`` / ``SH600519`` / ``sh.600519`` 等。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SH, SZ, BJ = "SH", "SZ", "BJ"
+_MARKETS = {SH, SZ, BJ}
+
+
+@dataclass(frozen=True)
+class Symbol:
+    code: str
+    market: str  # SH / SZ / BJ
+
+    @property
+    def ts_code(self) -> str:
+        """tushare 风格规范代码,如 ``600519.SH``。"""
+        return f"{self.code}.{self.market}"
+
+    def __str__(self) -> str:
+        return self.ts_code
+
+
+def _infer_market(code: str) -> str:
+    """按代码前缀推断交易所(覆盖主板/创业板/科创板/北交所/ETF/可转债等常见段)。"""
+    if code.startswith(("50", "51", "52", "56", "58", "60", "68", "90", "11", "70")):
+        return SH
+    if code.startswith(("00", "30", "12", "15", "16", "18", "20", "39", "13")):
+        return SZ
+    if code.startswith(("43", "82", "83", "87", "88", "92")):
+        return BJ
+    # 兜底:6 开头归上交所,其余归深交所
+    return SH if code[:1] == "6" else SZ
+
+
+def normalize(symbol: str) -> Symbol:
+    """把任意常见写法归一为 :class:`Symbol`。"""
+    s = str(symbol).strip().upper().replace(" ", "").replace(".", "")
+    # 形如 SH600519 / 600519SH —— 去掉市场前后缀后,剩余部分必须是纯数字代码
+    if s[:2] in _MARKETS:
+        code, market = s[2:], s[:2]
+    elif s[-2:] in _MARKETS:
+        code, market = s[:-2], s[-2:]
+    elif s.isdigit():
+        code = s
+        market = _infer_market(s)
+    else:
+        raise ValueError(f"无法解析证券代码: {symbol!r}")
+    if not code.isdigit():
+        raise ValueError(f"无法解析证券代码: {symbol!r}")
+    return Symbol(code, market)
+
+
+_EM_MARKET = {SH: "1", SZ: "0", BJ: "0"}
+_TDX_MARKET = {SZ: 0, SH: 1, BJ: 2}
+_TDX_MARKET_REV = {0: SZ, 1: SH, 2: BJ}
+
+
+def to_eastmoney_secid(symbol: str) -> str:
+    """东方财富 secid,如 ``1.600519`` / ``0.000001``。"""
+    sym = normalize(symbol)
+    return f"{_EM_MARKET[sym.market]}.{sym.code}"
+
+
+def to_tdx(symbol: str) -> tuple[int, str]:
+    """通达信 (market, code),market: 0=深 1=沪 2=北。"""
+    sym = normalize(symbol)
+    return _TDX_MARKET[sym.market], sym.code
+
+
+def from_tdx(market: int, code: str) -> Symbol:
+    """通达信 (market, code) -> :class:`Symbol`。market: 0=深 1=沪 2=北。
+
+    把行情响应里的数字 market 还原为 probar 规范市场,避免 TDX 的数字 market 编码外泄到公共 API。
+    """
+    try:
+        return Symbol(str(code), _TDX_MARKET_REV[int(market)])
+    except (KeyError, TypeError, ValueError):
+        raise ValueError(f"无法识别的通达信 market={market!r} code={code!r}") from None

probar/playground/__init__.py

@@ -0,0 +1 @@
+"""probar 接口可视化测试台(可选,需 `pip install "probar[playground]"`)。"""

probar/playground/__main__.py

@@ -0,0 +1,24 @@
+"""`python -m probar.playground` 启动本地测试台。"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="probar 接口可视化测试台")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8787)
+    args = parser.parse_args()
+
+    try:
+        import uvicorn
+    except ImportError as e:  # noqa: B904
+        raise SystemExit("缺少依赖,请先安装:pip install \"probar[playground]\"") from e
+
+    print(f"probar 测试台: http://{args.host}:{args.port}")
+    uvicorn.run("probar.playground.app:app", host=args.host, port=args.port, reload=False)
+
+
+if __name__ == "__main__":
+    main()