StockDB Python SDK

针对 free-stockdb 项目的第三方只读 Python SDK，提供 K 线查询（多周期 / 复权 / 字段投影 / DataFrame）、股票清单与板块（概念 / 申万行业）双向检索，以及原生三级键只读门面。

⚠️ 非官方项目：本项目由社区开发者维护，与 free-stockdb 官方无隶属关系，亦非其官方 SDK。使用前请自行评估风险，相关问题请在本仓库提交 issue，而非上游项目。

• 纯 HTTP 实现：不依赖任何原生二进制，Windows / macOS / Linux 通用，Python 3.10+ 即装即用。
• 只读定位：本 SDK 只做数据读取；私有数据写入与管线不在 HTTP 协议内，不提供。
• 一次依赖到位：httpx + pandas，无可选 extras。

安装

pip install stockdb-sdk

前提：本机（或局域网内）已运行 stockdb 服务（默认 127.0.0.1:7899）。远程端点用 sdk.init() 指定。

快速开始

import stockdb_sdk as sdk

sdk.init(host="127.0.0.1", port=7899)   # 默认端点，本机可省略

# 日 K（默认前复权、时间升序）
rows = sdk.get("600633", start="20260701", end="20260824")

# 5 分钟线 + 字段投影 + DataFrame
df = sdk.get("600633", freq="5m", start="20260824", end="20260824",
             fields="date,close,high,low", as_df=True)

# 批量 / 代码前缀（可带交易所后缀），返回 {代码: 行列表}
batch = sdk.get(["600633", "000001.SZ"], start="20260818", end="20260824")
banks = sdk.get("60003*", start="20260818", end="20260824")

# 股票清单与板块
codes = sdk.codes()                # 在市代码（升序）
boards = sdk.boards("600633")      # 该股所属板块
members = sdk.members("AI芯片")    # 板块成员代码

异步版本与同步完全同构（代码列表并发请求）：

rows = await sdk.get_async("600633", start="20260701")
data = await sdk.get_async(["600633", "000001"], start="20260818")

API

get(code, *, start=None, end=None, freq="1d", fq="qfq", fields=None, as_df=False)

K 线查询，返回时间升序的行列表（dict）；get_async 为异步版。

返回形态：单个代码 → 行列表；前缀与列表 → {代码: 行列表}。日 K 行约 21 个字段（open/high/low/close/volume/amount/turnover/pct_chg/pe_ttm/pb/total_mv/...），分钟行 8 个字段（open/high/low/close/volume/amount）。

周期与复权说明：

• 1d / 1m 为库内原生周期；5m/15m/30m/60m 由 1 分钟聚合、1w/1M 由日 K 聚合，聚合行固定输出 date/open/high/low/close/pre_close/pct_chg/volume/amount（+code/name）。
• 分钟聚合按交易时段分桶（09:30-11:30、13:00-15:00），60 分钟线为 09:30 / 10:30 / 13:00 / 14:00 四段，午休不跨桶，收盘 K 并入最后一桶。
• 停牌占位行在聚合前丢弃：服务端分钟表对停牌日会写入 OHLC 全 None 或全 0、volume=0 的占位 bar，这类行没有可聚合的价格，聚合（5m~60m、1w、1M）时直接跳过，某桶因此为空则整桶不输出；原生 1m / 1d 查询仍如实返回原始行。
• 复权因子按调用取用、原地折算：少于 64 只代码逐只小请求，更多则一次全量请求（约 5MB）解析后只保留当次所需，用完即弃，不设跨调用缓存；qfq 锚定最新、hfq 按累计因子放大历史。

内存契约（面向全市场数据管道）

本 SDK 为"查遍所有标的"的训练/回测场景设计，除板块索引外不在调用之间保留任何行情或因子数据；单次调用的峰值内存即该次返回的数据本身：

• 复权因子零驻留（见上）；members() 只做 keys 扫描 + 单板块取值，同样零驻留。
• boards() 反向查找必须遍历全部板块成员表，首次调用建立有界索引（约 1300 个板块，10-20MB）并保留复用；不调用即不占用。
• 窄前缀（命中 ≤ 64 只）先枚举在市+退市代码清单，再逐只精准查询——避免为 60063* 这类前缀拉取全市场数据；更宽的前缀走全市场单请求后客户端过滤。
• 同步多代码（≥ 4 只）自动启用最多 8 线程并发请求；异步版 asyncio.gather 并发，复权取数也全异步，不阻塞事件循环。

codes() / delisted()

在市 / 已退市股票代码列表（升序）。

boards(code)

一只股票所属的全部板块，返回 [{code, name, category, source}, ...]，category 为 "概念" / "申万一级" ~ "申万三级"。

members(board, category=None)

板块成员代码列表。board 接受名称（"AI芯片"，先精确后模糊）或板块代码（"801170.SL"）；名称模糊命中多个板块时须用 category 消歧，否则报错并列出候选。

rd —— 原生只读门面

直接面向 表[:键1[:键2]] 三级键模型，与 HTTP 协议一一对应：

rd = sdk.rd
rd.get("日k:600633:20260625")            # 精确键 -> 单行 dict
rd.get("日k:600633:2026062*")            # 通配（仅最后一段）-> [[键, 值], ...]
rd.vals("日k", "600633", "2026062*")     # 只取值列
rd.keys("日k", "600633")                 # 完整键列表（仅精确键）
rd.len("日k", "600633")                  # 5421

内置数据表：日k / 分钟k（行情）、股票代码 / 退市（代码表）、复权（除权事件与累计因子）、板块（概念与申万行业）。

行为要点（实测固化）

• 服务端区间查询返回降序，本 SDK 统一交付时间升序。
• 服务端不支持前缀+区间组合查询：窄前缀走枚举+逐只请求，宽前缀（"6*"、"*"）的响应体积与「市场 × 区间」成正比，大区间全市场查询请留意内存。
• 代码列表去重后逐代码请求，请求数 = 代码数；异步版并发。
• 无服务端字段投影，fields 在客户端完成。

数据质量说明（实测服务端特性，v0.3.1 审计）

SDK 层已验证：聚合零丢失（Σ1m = Σ5m = Σ60m 精确相等）、OHLC 极值与开收盘跨表勾稽一致、复权公式与 复权 因子表逐行吻合、舍入不破坏 OHLC 不等式。以下为服务端数据本身的已知特性，SDK 原样透传、不做静默"修复"，使用方需知悉：

• 历史 pre_close 不可信：多数股票历史段的 pre_close 被混入前复权价（如 000001 仅最近 ~50 行与真实前收一致，688981 全程一致）；pct_chg 为交易所标准口径（除权调整），全程可信。需要前收/涨跌幅时建议自行按 close 链式计算。SDK 聚合输出的 pre_close/pct_chg 除首根 bar 外均为链式自算，不受此影响。
• 分钟表与日 K 表是两个独立数据源：同日 Σvolume/Σamount 存在 ~0.1% 量级口径差（实测 75 标的日中 49% 的天 >0.01%，最大 0.935% 出现在 ETF），方向双向；日 K amount 为万元取整。跨周期对账请以单一来源为准。
• ETF 个别日期 volume 单位为"手"：如 510300 在 2024-09-26 ~ 10-09 的日 K volume 恰小 100 倍（amount 正常）。
• 退市代码表有大量重复行（实测 866 行仅 339 个唯一代码）：delisted() 已在 SDK 侧去重；在市与退市清单另有 13 个代码交集（如 000004），全市场同步时需去重。
• 分钟 bar 每交易日 242 根（09:30-11:30 含两端 121 根 + 13:00-15:00 含两端 121 根），收盘分钟与前一分钟在聚合时并入同一桶，无数据丢失。

开发

pip install -e .[dev]
pytest                # 单元测试 + 集成测试（需本地 stockdb 服务运行中）

版本发布：更新 pyproject.toml 与 __init__.py 双版本号 → 打 tag vX.Y.Z → CI 自动构建纯 Python wheel（py3-none-any）并发布到 PyPI。

License

Proprietary，见 LICENSE。