bihu-stock-data-client

壁虎量化 A 股数据服务的官方 Python SDK：28 个数据查询接口，显式方法名、完整类型注解、内置分页自动化，同为人类用户与 AI 助手设计。

特性

• 28 个数据接口：日K/分钟K、指数、申万行业、资金流、龙虎榜、财务报告、股东与股本、筹码分布、实时行情等
• 分页自动化：fetch_all=True 自动翻页全量拉取，max_rows 护栏防止失控；每个分页接口另有 xxx_iter() 生成器，逐页流式处理大数据集
• 列式数据自动解码：服务端 {column, item} 列式响应解码为 Records（list[dict] 子类，手感同普通列表，附带 total_count 等分页元信息，可一键 to_pandas()）
• 三级配置：显式参数 > 已有环境变量 > .env 文件
• 完善的异常层次：所有异常携带 trace_id，可直接反馈给服务方定位问题
• 传输层自动重试：429/5xx 指数退避重试；API Key 经 X-API-Key 请求头鉴权

安装

要求 Python ≥ 3.10。

pip install "bihu-stock-data-client @ git+https://github.com/bihu888/bihu-stock-data-client.git"

# 启用 pandas 转换（可选）
pip install "bihu-stock-data-client[pandas] @ git+https://github.com/bihu888/bihu-stock-data-client.git"

# 国内网络可用 Gitee 镜像
pip install "bihu-stock-data-client @ git+https://gitee.com/bihu888/bihu-stock-data-client.git"

从源码安装

git clone https://github.com/bihu888/bihu-stock-data-client.git
cd bihu-stock-data-client
pip install -e ".[dev]"   # dev = pytest / requests-mock / mypy 等开发依赖

快速上手

import bihu_stock_data_client as bsdc

client = bsdc.Client(api_key="你的 API Key")  # base_url 默认线上服务，本地联调可显式传入

# 单页查询（默认第 1 页、每页最多 1000 条）
rows = client.kline_daily(stock_code="000001.SZ", start_date="2025-01-01")
print(rows[0])            # {'stock_code': '000001.SZ', 'trade_date': '2025-01-02', 'close': ...}
print(rows.total_count)   # 符合条件的总条数

# 自动全量（客户端自动翻页）
all_rows = client.kline_daily(stock_code="000001.SZ", start_date="2020-01-01", fetch_all=True)

# 转 pandas（需安装 [pandas] extra）
df = rows.to_pandas()

配置

API Key 与服务地址由服务提供方分配，请前往 壁虎量化 获取。

以上环境变量也可写入项目根目录的 .env 文件，客户端构造时自动加载（依赖 python-dotenv）；已存在的环境变量优先级更高。可参考仓库内的 .env.example。

注意：StockDataClient 实例非线程安全（内部共享一个 requests.Session）；多线程请每线程使用独立实例，或通过 session= 注入自定义 Session。

接口一览

共 28 个查询方法。筛选参数均可选（标注"必填"的除外）；日期格式 yyyy-MM-dd；quarter_type：1=一季报、2=年中报、3=三季报、4=年报。所有分页接口都有对应的 xxx_iter() 流式方法（如 kline_daily_iter）。

K线行情

指数

股票与行业基础

申万行业数据

资金与成交

筹码

股本与股东

财务与分红

统计与日历

实时行情（当日数据）

分页与流式

分页接口的 pageNum/pageSize 为服务端必填（pageSize 上限 1000），SDK 提供四种用法：

# 1. 默认取第一页（page_num=1, page_size=1000）
rows = client.kline_daily(stock_code="000001.SZ")

# 2. 手动翻页
rows = client.kline_daily(stock_code="000001.SZ", page_num=2, page_size=500)

# 3. 自动全量：fetch_all=True，max_rows 护栏（默认 1_000_000）超限抛 PaginationLimitError
all_rows = client.kline_daily(stock_code="000001.SZ", start_date="2020-01-01",
                              fetch_all=True, max_rows=5_000_000)

# 4. 流式逐页（生成器，适合大数据集省内存）
for page in client.kline_daily_iter(stock_code="000001.SZ", start_date="2020-01-01"):
    ...  # 处理这一页，page 也是 Records

错误处理

所有异常继承 bsdc.StockDataError：

try:
    rows = client.kline_daily(stock_code="000001.SZ")
except bsdc.ApiError as e:
    print(f"服务端错误: {e.message}")  # e.code / e.status / e.trace_id 可直接反馈给服务方排查
except bsdc.StockDataError as e:
    print(f"其他错误: {e.message}")

更多示例

• examples/quickstart.py：单页查询、自动全量、错误处理
• examples/fetch_all_and_pandas.py：自动全量拉取 + 转 pandas

License

MIT