tokease

灵鲸算力指数平台的 Python SDK。可以在本地查看查询参数，也可以用 API Key 把行情读成 pandas.DataFrame。

服务地址固定为 https://whale.tokease.cn。平台上的字段说明见 用户手册 · SDK。

安装

Python 3.10 及以上。pandas 随包安装，没有额外的可选依赖。

pip install tokease

API Key

查询必须带 Key。按下面的顺序取值：

1. Client(api_key=...)
2. 环境变量 TOKEASE_API_KEY
3. 环境变量 WHALEINDEX_API_KEY

没有 Key 时抛出 TokeaseError，不会发请求。Key 无效或权限不足时抛出 TokeaseAPIError。

import tokease

client = tokease.Client(api_key="tokease_xxxxxxxxxxxx_xxxxxxxx", timeout=30, max_retries=5)

timeout 默认 30 秒。遇到分钟限流（HTTP 429、业务码 42901）时最多再重试 max_retries 次，默认 5 次，退避为 2^次数 秒加少量随机抖动。每日额度用尽（42902）不会自动重试。

查看参数

这些函数不访问网络。

import tokease

tokease.list_datasets()
tokease.dataset_params("index_daily")
tokease.dataset_fields("index_daily")
tokease.describe("index_quote")
tokease.builtin_indices()
tokease.hardware_base_codes()

list_datasets() 只有 index_basic、index_daily、index_latest、index_quote、trade_calendar。未知数据集、未知参数、未知字段会在本地拒绝。builtin_indices() 是内置默认目录；线上名称和排序以 index_basic 的 sort_no 为准。

查询

五个方法都返回 DataFrame。日期可以写 YYYYMMDD、YYYY-MM-DD，或传入 datetime.date。trade_date 不能和 start_date / end_date 一起用。

basic = client.index_basic()
latest = client.index_latest()
daily = client.index_daily(
    index_code="Server_Index",
    start_date="20260801",
    end_date="20260831",
    fields=["trade_date", "index_code", "index_value", "change_rate"],
)
quotes = client.index_quote(
    index_code="Server_Index",
    specification="B300",
    start_date="20260801",
    end_date="20260831",
)
calendar = client.trade_calendar(start_date="20260801", end_date="20260831")

通用入口是 client.query(dataset, params, fields, limit=1000, offset=0, paginate=True)。

fields 省略时返回该数据集的全部列。paginate=True 时按 has_more 自动取完。limit 必须在 1 到 5000 之间。省略 index_code 只返回该 Key 有权查看的指数。

DataFrame

• trade_date、base_date 是 datetime64。
• calculated_at 是带 UTC 时区的时间。
• 点位、价格、权重、涨跌是 float64。change_rate 为 0.0123 时表示上涨 1.23%。
• sort_no 是可空整数，enabled 和 is_workday 是可空布尔。
• frame.attrs["dataset"] 是数据集名，frame.attrs["request_id"] 是最后一页的请求编号。

权限

SDK 使用 API Key，返回该 Key 允许看到的完整字段。网站上标成「仅公开点位」的指数，Key 具备对应 scope 时仍包含加权价格和规格报价。

• 免费 Key 默认延迟 7 个交易日，且不能读取 Hardware_Index。
• 会员 Key 可以读取最新数据和会员指数。Hardware_Index 没有规格报价。
• 新 Key 默认同时拥有 index:read、quote:read、calendar:read。

from tokease import TokeaseAPIError, TokeaseError

try:
    frame = client.index_daily(index_code="Server_Index", trade_date="20260820")
except TokeaseError as exc:
    print("参数或 Key 缺失:", exc)
except TokeaseAPIError as exc:
    print(exc.code, exc.status, exc.request_id)

发布

包版本等于仓库根目录 package.json 的 version。推送标签 v<version> 时，GitHub Actions 用 secret PYPI_API_TOKEN 发布到 PyPI。