datapush-sdk 0.1.0__tar.gz

datapush_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 datapush
+
+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.

datapush_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: datapush-sdk
+Version: 0.1.0
+Summary: datapush A 股行情 SDK：实时推送 + 历史 K 线 + 复权因子 + 本地按需缓存（CLI 与 Python 两种用法）
+Author-email: datapush <support@datapush.vip>
+License: MIT
+Project-URL: Homepage, https://api.datapush.vip
+Project-URL: Documentation, https://api.datapush.vip/dp/docs
+Project-URL: Source, https://api.datapush.vip
+Project-URL: Bug Tracker, https://api.datapush.vip
+Keywords: datapush,a-share,stock,market-data,kline,quote,websocket,quant,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == "pandas"
+Dynamic: license-file
+
+# datapush-sdk
+
+**datapush A 股行情 SDK**（Python）：REST 历史 + WebSocket 实时 + **本地按需缓存**。
+**零第三方依赖**（只用标准库），`pip install` 后即可用 **命令行** 与 **Python 两种方式**使用，前缀都是 `datapush`。
+
+```bash
+pip install datapush-sdk
+datapush config set-key sk-xxx     # 保存 API Key（也可用环境变量 DATAPUSH_API_KEY）
+datapush kline 000001              # 一行拿到最近 30 个交易日日K（自动缓存）
+```
+
+```python
+import datapush
+c = datapush.Client()              # Key 自动读；缓存默认开启
+page = c.kline("000001", days=250)  # 一行拿数据；第二次调用命中缓存
+for bar in page:
+    print(bar.time, bar.close)
+```
+
+---
+
+## 1. 安装与配置
+
+```bash
+pip install datapush-sdk            # 运行时零依赖
+pip install "datapush-sdk[pandas]"  # 可选：需要 to_pandas()
+```
+
+API Key 的解析优先级（高 → 低）：**显式参数 → 环境变量 `DATAPUSH_API_KEY` → `~/.datapush/config.json`**。
+推荐用 CLI 保存一次即可：`datapush config set-key sk-xxx`（也可 `datapush config show` 查看，Key 会打码）。
+
+服务地址默认 `https://api.datapush.vip`，可用 `--base-url` / `DATAPUSH_BASE_URL` / 配置文件覆盖。
+
+## 2. 本地按需缓存（默认开启，用户无感）
+
+- **只存不复权原始价**（`adj=none`）+ 复权因子表 ⇒ 历史永不失效、只需追加；
+- **复权在本地算**：`kind="qfq"|"hfq"|"raw"`，除权后自动正确、**无需重下历史**；
+- **增量续拉**：用游标 `latest_time` 只拉新增（当日 forming bar 同键覆盖写，天然幂等）；
+- **范围自动补拉**：这次要 30 天、下次要 250 天，会自动把缺的那段补上；
+- **断网可读**：`Client(offline=True)` 或 `--offline` 只读本地缓存；
+- 缓存位置：`~/.datapush/cache/datapush.db`（SQLite 单文件）；可用 `--cache-dir` / `DATAPUSH_CACHE_DIR`
+  / 配置文件 `cache_dir` 指定；`DATAPUSH_NO_CACHE=1` 或 `--no-cache` 彻底关闭。
+
+```bash
+datapush cache info                 # 路径 / 大小 / 标的数 / 根数 / 时间范围
+datapush cache path                 # 只打印缓存文件路径（脚本友好）
+datapush cache prune --days 90      # 只保留最近 90 天
+datapush cache clear --code 000001  # 清掉某只票
+datapush update 000001 --period 1m  # 手动增量（平时查询时自动做）
+```
+
+**股票列表 / 基础信息 / 交易日 / 板块** 属于实时数据，**直连不缓存**（流量很小）：
+`datapush codes`（全市场代码，约 6 页 / 约 1MB）、`datapush stock 000001`。
+
+## 3. Python 用法速查
+
+```python
+import datapush
+c = datapush.Client()                       # 也可 Client(api_key=..., cache=False, offline=True)
+
+# 历史
+c.codes()                                   # 全市场代码（实时）
+c.stocks(all=True)                          # 全市场列表（实时）；c.stocks(page=1, page_size=20) 单页
+c.stock("000001")                           # 基础信息 12 字段（实时）
+c.kline("000001", days=250)                 # 日K（前复权）
+c.kline("000001", days=250, kind="hfq")     # 后复权（本地因子表算）
+c.kline("000001", start="2026-01-01", end="2026-09-26", kind="raw")
+c.minute("000001", days=1)                  # 1 分钟 K 线（当日）
+c.fiveminute("000001", days=5)              # 5 分钟 K 线
+c.kline("000001", since="2026-09-26 14:59") # 增量（闭区间，含该根）
+c.xdxr("000001")                            # 复权因子表（TTL 1 天，除权后自动刷新）
+c.factors("000001", size=30, fields="close,ma5")   # 量化因子（高级用户）
+c.factor_catalog()                          # 因子目录
+
+# 实时（WebSocket）
+q = c.quote("000001")                       # 一次快照（WS 首帧；REST 没有该接口）
+for e in c.watch(["000001", "600108"], types=["quote", "k1"], seconds=30):
+    if e.type == "quote":
+        print(e.quote.price)
+
+# 导出与缓存
+c.kline("000001", days=250).to_csv("000001.csv")
+c.kline("000001", days=250).to_dicts()      # list[dict]
+c.to_pandas(c.kline("000001", days=250))    # 需要 pandas
+c.cache_info(); c.update("000001", period="day"); c.close()
+```
+
+## 4. CLI 速查
+
+```bash
+datapush kline 000001 [--days 250 | --size 100 --offset 0 | --start 2026-01-01 --end 2026-09-26 | --since "..."]
+                     [--period day|1m|5m] [--kind qfq|hfq|raw] [--limit 60] [--csv out.csv] [--json] [--no-refresh]
+datapush minute 000001 --days 1
+datapush fiveminute 000001 --days 5
+datapush xdxr 000001 [--refresh]
+datapush stocks [--page 1 --page-size 20] [--all]
+datapush codes [--market sh|sz|bj] [--prefixed]        # 默认一行一个，可直接管道
+datapush stock 000001
+datapush factors 000001 --size 30 [--fields close,ma5] [--daily-kline 0]
+datapush quote 000001 [--types quote|depth]
+datapush watch 000001 600108 [--types quote,k1] [--seconds 30]
+datapush update 000001 --period 1m
+datapush cache info|path|clear|prune
+datapush config set-key sk-xxx | config show | config path | config set cache_dir D:/datapush-cache
+datapush doctor                                        # 一键排障
+datapush get /api/v1/stocks/000001/xdxr --param k=v     # 通用逃生舱（调试新接口）
+```
+
+通用选项可写在命令前或命令后：`--json`（原始 JSON，便于管道）、`--csv FILE`、`--api-key`、`--base-url`、
+`--timeout`、`--cache-dir`、`--no-cache`、`--offline`。
+退出码：`0` 成功 / `1` 业务或网络错误 / `2` 参数错误。
+
+## 5. 本地复权（与官方文档公式一致）
+
+`adj=none` 取原始价 + `xdxr()` 取因子表 ⇒ **一次乘法**：
+
+```
+段 = segments 里第一个 from ≤ bar.date（都不满足 ⇒ from 为空的兜底段）
+前复权价 = raw价 × seg.qfq      后复权价 = raw价 × seg.hfq
+换手率   = cjl / ltgb × seg.share_ratio × 100        自检：seg.hfq × P == seg.qfq（P = 兜底段 qfq）
+```
+
+SDK 已内置：`datapush.adjust_bars(bars, table, kind=...)`、`datapush.pick_segment(table, date)`、
+`datapush.verify_segments(table)`。细节见官方文档「复权因子表（本地复权计算）」。
+
+## 6. 常见问题
+
+- **`import datapush` 不是我装的这个包？** PyPI 上另有一个无关的 `datapush`（MySQL 数据生成器）。
+  两者同装会互相覆盖顶层模块，此时用别名：`import datapush_sdk as datapush`。
+- **需要 Key 但没有？** 先 `datapush config set-key sk-xxx`（注册后在控制台复制）；`datapush doctor` 可自查。
+- **返回 402 / 429？** 402 = 积分不足；429 = 分钟接口限流（10 QPS/用户，SDK 已按 `Retry-After` 自动退避重试）。
+- **能离线用吗？** 能：缓存过的标的用 `offline=True`/`--offline` 可读；实时接口必须联网。
+- **WS 单连接能订阅多少？** 最多 50 个 code（SDK 会自动分批订阅）；普通用户最多 10 个连接。
+
+## 7. 兼容性与许可
+
+- Python **3.9+**（Windows / macOS / Linux），运行时**零第三方依赖**；`py.typed` 已附带，支持类型检查。
+- License: **MIT**。接口与字段含义以官方文档为准（`https://api.datapush.vip/dp/docs`）。

datapush_sdk-0.1.0/README.md

@@ -0,0 +1,138 @@
+# datapush-sdk
+
+**datapush A 股行情 SDK**（Python）：REST 历史 + WebSocket 实时 + **本地按需缓存**。
+**零第三方依赖**（只用标准库），`pip install` 后即可用 **命令行** 与 **Python 两种方式**使用，前缀都是 `datapush`。
+
+```bash
+pip install datapush-sdk
+datapush config set-key sk-xxx     # 保存 API Key（也可用环境变量 DATAPUSH_API_KEY）
+datapush kline 000001              # 一行拿到最近 30 个交易日日K（自动缓存）
+```
+
+```python
+import datapush
+c = datapush.Client()              # Key 自动读；缓存默认开启
+page = c.kline("000001", days=250)  # 一行拿数据；第二次调用命中缓存
+for bar in page:
+    print(bar.time, bar.close)
+```
+
+---
+
+## 1. 安装与配置
+
+```bash
+pip install datapush-sdk            # 运行时零依赖
+pip install "datapush-sdk[pandas]"  # 可选：需要 to_pandas()
+```
+
+API Key 的解析优先级（高 → 低）：**显式参数 → 环境变量 `DATAPUSH_API_KEY` → `~/.datapush/config.json`**。
+推荐用 CLI 保存一次即可：`datapush config set-key sk-xxx`（也可 `datapush config show` 查看，Key 会打码）。
+
+服务地址默认 `https://api.datapush.vip`，可用 `--base-url` / `DATAPUSH_BASE_URL` / 配置文件覆盖。
+
+## 2. 本地按需缓存（默认开启，用户无感）
+
+- **只存不复权原始价**（`adj=none`）+ 复权因子表 ⇒ 历史永不失效、只需追加；
+- **复权在本地算**：`kind="qfq"|"hfq"|"raw"`，除权后自动正确、**无需重下历史**；
+- **增量续拉**：用游标 `latest_time` 只拉新增（当日 forming bar 同键覆盖写，天然幂等）；
+- **范围自动补拉**：这次要 30 天、下次要 250 天，会自动把缺的那段补上；
+- **断网可读**：`Client(offline=True)` 或 `--offline` 只读本地缓存；
+- 缓存位置：`~/.datapush/cache/datapush.db`（SQLite 单文件）；可用 `--cache-dir` / `DATAPUSH_CACHE_DIR`
+  / 配置文件 `cache_dir` 指定；`DATAPUSH_NO_CACHE=1` 或 `--no-cache` 彻底关闭。
+
+```bash
+datapush cache info                 # 路径 / 大小 / 标的数 / 根数 / 时间范围
+datapush cache path                 # 只打印缓存文件路径（脚本友好）
+datapush cache prune --days 90      # 只保留最近 90 天
+datapush cache clear --code 000001  # 清掉某只票
+datapush update 000001 --period 1m  # 手动增量（平时查询时自动做）
+```
+
+**股票列表 / 基础信息 / 交易日 / 板块** 属于实时数据，**直连不缓存**（流量很小）：
+`datapush codes`（全市场代码，约 6 页 / 约 1MB）、`datapush stock 000001`。
+
+## 3. Python 用法速查
+
+```python
+import datapush
+c = datapush.Client()                       # 也可 Client(api_key=..., cache=False, offline=True)
+
+# 历史
+c.codes()                                   # 全市场代码（实时）
+c.stocks(all=True)                          # 全市场列表（实时）；c.stocks(page=1, page_size=20) 单页
+c.stock("000001")                           # 基础信息 12 字段（实时）
+c.kline("000001", days=250)                 # 日K（前复权）
+c.kline("000001", days=250, kind="hfq")     # 后复权（本地因子表算）
+c.kline("000001", start="2026-01-01", end="2026-09-26", kind="raw")
+c.minute("000001", days=1)                  # 1 分钟 K 线（当日）
+c.fiveminute("000001", days=5)              # 5 分钟 K 线
+c.kline("000001", since="2026-09-26 14:59") # 增量（闭区间，含该根）
+c.xdxr("000001")                            # 复权因子表（TTL 1 天，除权后自动刷新）
+c.factors("000001", size=30, fields="close,ma5")   # 量化因子（高级用户）
+c.factor_catalog()                          # 因子目录
+
+# 实时（WebSocket）
+q = c.quote("000001")                       # 一次快照（WS 首帧；REST 没有该接口）
+for e in c.watch(["000001", "600108"], types=["quote", "k1"], seconds=30):
+    if e.type == "quote":
+        print(e.quote.price)
+
+# 导出与缓存
+c.kline("000001", days=250).to_csv("000001.csv")
+c.kline("000001", days=250).to_dicts()      # list[dict]
+c.to_pandas(c.kline("000001", days=250))    # 需要 pandas
+c.cache_info(); c.update("000001", period="day"); c.close()
+```
+
+## 4. CLI 速查
+
+```bash
+datapush kline 000001 [--days 250 | --size 100 --offset 0 | --start 2026-01-01 --end 2026-09-26 | --since "..."]
+                     [--period day|1m|5m] [--kind qfq|hfq|raw] [--limit 60] [--csv out.csv] [--json] [--no-refresh]
+datapush minute 000001 --days 1
+datapush fiveminute 000001 --days 5
+datapush xdxr 000001 [--refresh]
+datapush stocks [--page 1 --page-size 20] [--all]
+datapush codes [--market sh|sz|bj] [--prefixed]        # 默认一行一个，可直接管道
+datapush stock 000001
+datapush factors 000001 --size 30 [--fields close,ma5] [--daily-kline 0]
+datapush quote 000001 [--types quote|depth]
+datapush watch 000001 600108 [--types quote,k1] [--seconds 30]
+datapush update 000001 --period 1m
+datapush cache info|path|clear|prune
+datapush config set-key sk-xxx | config show | config path | config set cache_dir D:/datapush-cache
+datapush doctor                                        # 一键排障
+datapush get /api/v1/stocks/000001/xdxr --param k=v     # 通用逃生舱（调试新接口）
+```
+
+通用选项可写在命令前或命令后：`--json`（原始 JSON，便于管道）、`--csv FILE`、`--api-key`、`--base-url`、
+`--timeout`、`--cache-dir`、`--no-cache`、`--offline`。
+退出码：`0` 成功 / `1` 业务或网络错误 / `2` 参数错误。
+
+## 5. 本地复权（与官方文档公式一致）
+
+`adj=none` 取原始价 + `xdxr()` 取因子表 ⇒ **一次乘法**：
+
+```
+段 = segments 里第一个 from ≤ bar.date（都不满足 ⇒ from 为空的兜底段）
+前复权价 = raw价 × seg.qfq      后复权价 = raw价 × seg.hfq
+换手率   = cjl / ltgb × seg.share_ratio × 100        自检：seg.hfq × P == seg.qfq（P = 兜底段 qfq）
+```
+
+SDK 已内置：`datapush.adjust_bars(bars, table, kind=...)`、`datapush.pick_segment(table, date)`、
+`datapush.verify_segments(table)`。细节见官方文档「复权因子表（本地复权计算）」。
+
+## 6. 常见问题
+
+- **`import datapush` 不是我装的这个包？** PyPI 上另有一个无关的 `datapush`（MySQL 数据生成器）。
+  两者同装会互相覆盖顶层模块，此时用别名：`import datapush_sdk as datapush`。
+- **需要 Key 但没有？** 先 `datapush config set-key sk-xxx`（注册后在控制台复制）；`datapush doctor` 可自查。
+- **返回 402 / 429？** 402 = 积分不足；429 = 分钟接口限流（10 QPS/用户，SDK 已按 `Retry-After` 自动退避重试）。
+- **能离线用吗？** 能：缓存过的标的用 `offline=True`/`--offline` 可读；实时接口必须联网。
+- **WS 单连接能订阅多少？** 最多 50 个 code（SDK 会自动分批订阅）；普通用户最多 10 个连接。
+
+## 7. 兼容性与许可
+
+- Python **3.9+**（Windows / macOS / Linux），运行时**零第三方依赖**；`py.typed` 已附带，支持类型检查。
+- License: **MIT**。接口与字段含义以官方文档为准（`https://api.datapush.vip/dp/docs`）。

datapush_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datapush-sdk"
+dynamic = ["version"]
+description = "datapush A 股行情 SDK：实时推送 + 历史 K 线 + 复权因子 + 本地按需缓存（CLI 与 Python 两种用法）"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "datapush", email = "support@datapush.vip" }]
+keywords = [
+  "datapush",
+  "a-share",
+  "stock",
+  "market-data",
+  "kline",
+  "quote",
+  "websocket",
+  "quant",
+  "sdk",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# 仅开发/发布用；运行 SDK 本身零依赖（标准库）
+dev = ["pytest>=7", "build>=1.0", "twine>=4.0"]
+# 可选：把结果集转成 DataFrame（不装也能用 to_list/to_csv/to_json）
+pandas = ["pandas>=1.3"]
+
+[project.urls]
+Homepage = "https://api.datapush.vip"
+Documentation = "https://api.datapush.vip/dp/docs"
+Source = "https://api.datapush.vip"
+"Bug Tracker" = "https://api.datapush.vip"
+
+[project.scripts]
+datapush = "datapush.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+datapush = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "datapush._version.__version__" }

datapush_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

datapush_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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"