datapush-sdk 0.1.0__py3-none-any.whl

datapush/__init__.py

@@ -0,0 +1,104 @@
+"""datapush SDK —— A 股行情数据（REST + WebSocket）与本地按需缓存。
+
+两种用法，前缀都是 `datapush`::
+
+    # 1) Python
+    import datapush
+    c = datapush.Client()                      # Key 自动读 DATAPUSH_API_KEY / ~/.datapush/config.json
+    bars = c.kline("000001", days=250)          # 一行拿到日K（自动缓存 + 增量刷新）
+    for m in c.watch("000001", types=["quote"]): ...
+
+    # 2) 命令行
+    $ datapush kline 000001 --days 250
+    $ datapush quote 000001
+    $ datapush cache info
+
+设计要点：
+- **零第三方运行时依赖**（只用标准库），`pip install datapush-sdk` 即刻可用；
+- **按需本地缓存**：只存不复权原始价 + 复权因子表，复权值读取时现算，除权后无需重下历史；
+- 实时接口（股票列表 / 基础信息 / 交易日 / 板块）**直连不缓存**。
+"""
+
+from __future__ import annotations
+
+from ._endpoints import PERIODS
+from ._version import __version__
+from .adjust import adjust_bars, pick_segment, turnover, verify_segments
+from .cache import Cache
+from .client import Client
+from .config import DEFAULT_BASE_URL, config_file, default_cache_file, home_dir
+from .errors import (
+    AuthError,
+    BadRequestError,
+    ConfigError,
+    DatapushError,
+    NetworkError,
+    NotFoundError,
+    OfflineError,
+    PermissionError,
+    ProtocolError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+    WSError,
+)
+from .models import (
+    AdjSegment,
+    AdjTable,
+    Bar,
+    Depth,
+    FactorTable,
+    KlinePage,
+    Quote,
+    StockDetail,
+    StockInfo,
+    WSEvent,
+)
+from .rest import ApiResponse, RestClient
+from .ws import WsClient
+
+__all__ = [
+    "__version__",
+    # 客户端
+    "Client",
+    "RestClient",
+    "WsClient",
+    "Cache",
+    "ApiResponse",
+    # 模型
+    "Bar",
+    "KlinePage",
+    "Quote",
+    "Depth",
+    "WSEvent",
+    "StockInfo",
+    "StockDetail",
+    "AdjTable",
+    "AdjSegment",
+    "FactorTable",
+    # 本地复权
+    "adjust_bars",
+    "pick_segment",
+    "turnover",
+    "verify_segments",
+    # 配置与常量
+    "PERIODS",
+    "DEFAULT_BASE_URL",
+    "home_dir",
+    "config_file",
+    "default_cache_file",
+    # 异常
+    "DatapushError",
+    "ConfigError",
+    "OfflineError",
+    "NetworkError",
+    "AuthError",
+    "QuotaError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "BadRequestError",
+    "ServerError",
+    "ProtocolError",
+    "WSError",
+]

datapush/_endpoints.py

@@ -0,0 +1,68 @@
+"""datapush 后端接口路径的**唯一来源**。
+
+CLI、SDK 与测试都从这里取路径，好处有三：
+
+1. 拼错路径在开发期就暴露（而不是线上 404）；
+2. `tests/test_endpoints_match_router.py` 可用本文件的路径集合与后端
+   `server_go/internal/router/router.go` 做对照，防止 SDK 与后端契约漂移；
+3. 文档里出现的路径可被 `grep` 一次核清。
+
+后端统一响应：`{"code": 0, "message": "ok", "data": ...}`（`code` 与 HTTP 状态码同值）。
+"""
+
+from __future__ import annotations
+
+# ---- 公开（无需 API Key）----
+HEALTH = "/health"
+STATS = "/api/v1/stats"
+MARKET_BOARD = "/api/v1/market/board"
+MARKET_FEATURED = "/api/v1/market/featured"
+
+# ---- 需 API Key ----
+STOCKS = "/api/v1/stocks"  # 列表：page / page_size（≤1000）
+STOCK = "/api/v1/stocks/{code}"  # 单只基础信息（12 字段）
+KLINE = "/api/v1/stocks/{code}/kline"  # 日K（offset/size/since/adj）
+MINUTE = "/api/v1/stocks/{code}/minute"  # 1 分钟 K 线（offset/size/since/adj）
+FIVEMINUTE = "/api/v1/stocks/{code}/fiveminute"  # 5 分钟 K 线
+XDXR = "/api/v1/stocks/{code}/xdxr"  # 复权因子表（segments + ltgb + latest_event_date）
+FACTOR_CATALOG = "/api/v1/factors"  # 量化因子目录（高级用户）
+FACTORS = "/api/v1/stocks/{code}/factors"  # 量化因子数组（日K + 因子列）
+TRADING_TODAY = "/api/v1/trading/today"  # 今日是否交易 / 交易日信息
+MARKET_BOARDS = "/api/v1/market/boards"  # 指数 / 板块清单
+
+# ---- WebSocket ----
+WS = "/ws"  # 需 API Key 的实时推送
+WS_BOARD = "/ws/board"  # 公开：首页行情面板广播
+
+#: 支持缓存的 K 线周期（与后端 `period` 取值一致）
+PERIODS = ("day", "1m", "5m")
+
+#: 「必须联网、不缓存」的接口（列表 / 基础信息 / 交易日 / 板块 / 公开接口）
+NO_CACHE_PATHS = frozenset(
+    {HEALTH, STATS, STOCKS, STOCK, TRADING_TODAY, MARKET_BOARDS, MARKET_BOARD, MARKET_FEATURED}
+)
+
+#: 全部后端路径模板（含 `{code}` 占位）——供防漂移测试对照 router.go
+PATH_TEMPLATES = (
+    HEALTH,
+    STATS,
+    MARKET_BOARD,
+    MARKET_FEATURED,
+    STOCKS,
+    STOCK,
+    KLINE,
+    MINUTE,
+    FIVEMINUTE,
+    XDXR,
+    FACTOR_CATALOG,
+    FACTORS,
+    TRADING_TODAY,
+    MARKET_BOARDS,
+    WS,
+    WS_BOARD,
+)
+
+
+def format_path(template: str, code: str = "") -> str:
+    """把 `{code}` 占位替换成标的代码（其余模板原样返回）。"""
+    return template.replace("{code}", code) if code else template

datapush/_version.py

@@ -0,0 +1,7 @@
+"""版本号唯一来源。
+
+`pyproject.toml` 通过 `[tool.setuptools.dynamic] version = { attr = "datapush._version.__version__" }`
+引用本文件，因此只要改这里，包元数据、`datapush.__version__` 与 CLI `datapush --version` 同步变化。
+"""
+
+__version__ = "0.1.0"

datapush/adjust.py

@@ -0,0 +1,114 @@
+"""本地复权计算：与 `pages/docs.html#xdxr` 的公式**逐字一致**。
+
+三步（客户端只需一次乘法）：
+
+1. **选段**：`segments` 按 `from` 降序，取第一个 `from <= bar.date` 的段；都不满足（或 `from` 为空）⇒ 兜底段；
+2. **换算**：`前复权价 = raw价 × seg.qfq`、`后复权价 = raw价 × seg.hfq`、`成交额`同理、`换手率 = cjl / ltgb × share_ratio × 100`；
+3. **自检**：`seg.hfq × P == seg.qfq`，其中 `P = 兜底段.qfq`。
+
+两条注意（都在文档里强调过）：
+
+- **按段因子一次乘完**（不要逐事件累乘、不要反复乘除），这样与服务端复权视图的数值口径一致；
+- **成交量 `cjl` 不缩放**（只有价格与成交额缩放），换手率与价格口径无关（分母是「当日流通股本」）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, List, Optional, Sequence, Union
+
+from .errors import ProtocolError
+from .models import AdjSegment, AdjTable, Bar
+
+__all__ = ["pick_segment", "scale_bar", "adjust_bars", "turnover", "verify_segments"]
+
+Segments = Union[AdjTable, Sequence[AdjSegment]]
+KIND_RAW, KIND_QFQ, KIND_HFQ = "raw", "qfq", "hfq"
+
+
+def _segments_of(table: Segments) -> List[AdjSegment]:
+    """把 `AdjTable` 或 `list[AdjSegment]` 统一成段列表（保持**降序**）。"""
+    if isinstance(table, AdjTable):
+        return list(table.segments)
+    return list(table)
+
+
+def pick_segment(table: Segments, date: str) -> AdjSegment:
+    """按日期选适用段；`date` 支持 `YYYY-MM-DD` 或完整时间戳（只取前 10 位）。"""
+    segs = _segments_of(table)
+    if not segs:
+        raise ProtocolError("复权因子表为空（至少应有一段兜底段）")
+    day = date[:10]
+    for seg in segs:  # 已按 from 降序：第一个满足 from <= day 的即是适用段
+        if seg.from_date and seg.from_date <= day:
+            return seg
+    return segs[-1]  # 兜底段（from 为空）
+
+
+def turnover(cjl: float, ltgb: float, share_ratio: float = 1.0) -> float:
+    """换手率 %：`cjl / ltgb × share_ratio × 100`（乘除顺序与服务端 `turnover()` 一致）。"""
+    if not ltgb or ltgb <= 0:
+        return 0.0
+    ratio = share_ratio if share_ratio and share_ratio > 0 else 1.0
+    return cjl / ltgb * ratio * 100.0
+
+
+def scale_bar(bar: Bar, seg: AdjSegment, kind: str = KIND_QFQ) -> Bar:
+    """按段因子换算一根 K 线（`kind=raw` 原样返回；`cjl` 恒不缩放）。"""
+    if kind == KIND_RAW:
+        return bar
+    factor = seg.qfq if kind == KIND_QFQ else seg.hfq
+    return Bar(
+        open=bar.open * factor,
+        close=bar.close * factor,
+        high=bar.high * factor,
+        low=bar.low * factor,
+        cjl=bar.cjl,  # 成交量不缩放
+        cje=bar.cje * factor,
+        hsl=bar.hsl,  # 换手率与价格口径无关：保持缓存里原始价自带的值（需要时用 recompute_hsl）
+        time=bar.time,
+    )
+
+
+def adjust_bars(
+    bars: Iterable[Bar],
+    table: Segments,
+    kind: str = KIND_QFQ,
+    *,
+    ltgb: Optional[float] = None,
+    recompute_hsl: bool = False,
+) -> List[Bar]:
+    """批量复权。
+
+    - `kind`：`raw` / `qfq` / `hfq`；
+    - `ltgb` + `recompute_hsl=True` 时，按 `cjl / ltgb × share_ratio × 100` **重算**换手率
+      （原始价缓存里已带 hsl，通常不必重算；需要与服务端因口径变化对齐时才用）。
+    """
+    segs = _segments_of(table)
+    if not segs:
+        raise ProtocolError("复权因子表为空（至少应有一段兜底段）")
+    out: List[Bar] = []
+    for bar in bars:
+        seg = pick_segment(segs, bar.time)
+        scaled = scale_bar(bar, seg, kind)
+        if recompute_hsl and ltgb:
+            scaled = Bar(
+                open=scaled.open,
+                close=scaled.close,
+                high=scaled.high,
+                low=scaled.low,
+                cjl=scaled.cjl,
+                cje=scaled.cje,
+                hsl=turnover(bar.cjl, ltgb, seg.share_ratio),
+                time=scaled.time,
+            )
+        out.append(scaled)
+    return out
+
+
+def verify_segments(table: Segments, tol: float = 1e-12) -> bool:
+    """自检 `hfq × P == qfq`（逐段；`P` = 兜底段 `qfq`）。"""
+    segs = _segments_of(table)
+    if not segs:
+        return False
+    p = segs[-1].qfq
+    return all(abs(seg.hfq * p - seg.qfq) <= tol for seg in segs)