跳到主要内容

Python SDK

SDK 包装 /v2，返回可转成 pandas、polars 或 Arrow 的表格。需要 Python 3.10 以上。

安装​

pip install "veinmesh[all] @ https://data.cyberun.cloud/docs/sdk/veinmesh-0.2.0-py3-none-any.whl"

只装需要的：veinmesh[pandas]、veinmesh[polars]、veinmesh[arrow]、 veinmesh[live] 或 [all]。基本套件只需要 httpx。

import veinmesh

client = veinmesh.Client()  # VEINMESH_API_KEY

Client(key=..., base_url=..., timeout=120, pending_timeout=3600, retries=3)。 pending_timeout 是等待数据准备的上限；None 代表一直等。忙碌响应与网络错误 会重试。

用 context manager 关闭连接池：

with veinmesh.Client() as client:
    venues = client.venues()

目录​

client.venues()
client.products(venue="SHFE")
client.instruments(venue="SHFE", product="SHFE.rb", kind="future")
client.instrument("SHFE.rb2701")   # 规格与数据集
client.datasets(venue="SHFE")
client.calendar("SHFE", "2026-10-19", "2026-10-23", product="SHFE.rb")
client.schemas()

instruments() 会跟完所有分页，返回完整清单。instrument() 返回规格与它的 数据集。

数据​

t = client.data("book.snapshot", ["SHFE.rb2701"], trading_day="2026-10-20")
t = client.data("book.snapshot", "SHFE.rb2701", from_day="2026-10-01", to_day="2026-10-20",
                fields=["last", "volume"], start=None, end=None)

data() 会把过长区间与商品清单拆成 API 接受的请求、跟 next_cursor，返回 一张先依商品再依时间排序的表。传 catalog_version 可固定版本。请求窗口与 商品数见限制。

K 线​

daily = client.bars("SHFE.rb.main", "1d", from_day="2025-01-02", to_day="2026-10-20",
                    adjust="diff")
eighteen = client.bars("SHFE.rb2701", 1080, trading_day="2026-10-20")

interval 是秒数（60、1080）或 timedelta，或 1d、1w、1mo、1q、 1y。其他键跟 /v2/bars 相同：type、anchor、adjust、transform、 fill、dataset、catalog_version。连续合约接受 diff 与 ratio。

表格​

data() 与 bars() 返回 Table：

len(t)                 # 列数
t.columns              # 字段名称
t[0]                   # 一列，dict
t.to_pandas()          # 小数默认转 float
t.to_polars()
t.to_arrow()
t.catalog_version

to_pandas(exact=True)（polars 与 Arrow 也有同一选项）保留精确 Decimal， 不转 float。

实时​

for message in client.stream("SHFE.rb2701"):
    for row in message.rows:
        print(row["ts"], row["last"])

client.stream(..., bars={"interval": 60}) 改收 K 线；message.bar 与 message.complete 描述该根 K 线。start 从当天的 RFC 3339 时间点开始。SDK 会重连并从最后收到的数据列接续。需要 websockets extra。

导出​

job = client.export("book.snapshot", ["SHFE.rb2701", "SHFE.rb2705"],
                    from_day="2026-09-01", to_day="2026-10-20", format="parquet")
df = job.wait().to_pandas()
files = job.download("./data")

job.wait(poll=10, timeout=None) 轮询到 done；download() 写出文件； to_pandas()、to_polars()、to_arrow() 会下载并合并。client.get_export(id) 可重开工作。

错误​

  • APIError 带 status 与 problem dict；code 是稳定部分。
  • PendingTimeout 代表等了 pending_timeout，数据还在准备。
  • ExportFailed 代表导出工作以 failed 结束；消息含工作与 problem。

错误码与重试方式见错误。