Metadata-Version: 2.4
Name: tokease
Version: 1.14.2
Summary: 灵鲸算力指数平台 Python SDK：查看接口参数并查询行情数据
Author: WhaleIndex
Project-URL: Homepage, https://whale.tokease.cn/
Project-URL: Documentation, https://whale.tokease.cn/handbook/
Project-URL: Repository, https://github.com/fyinfor/WhaleIndex
Project-URL: Changelog, https://github.com/fyinfor/WhaleIndex/releases
Keywords: tokease,whaleindex,index,api
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2

# tokease

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

服务地址固定为 `https://whale.tokease.cn`。平台上的字段说明见 [用户手册 · SDK](https://whale.tokease.cn/handbook/sdk/python/)。

## 安装

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

```bash
pip install tokease
```

## API Key

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

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

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

```python
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`）不会自动重试。

## 查看参数

这些函数不访问网络。

```python
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` 一起用。

```python
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")
```

| 方法 | scope | 参数 |
| ---- | ---- | ---- |
| `index_basic` | `index:read` | `index_code` |
| `index_daily` | `index:read` | `index_code`，以及 `trade_date` 或日期区间 |
| `index_latest` | `index:read` | `index_code`。省略时每个可见指数一条最新日线 |
| `index_quote` | `quote:read` | 同日线，另加精确匹配的 `specification` |
| `trade_calendar` | `calendar:read` | `trade_date` 或日期区间 |

通用入口是 `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`。

```python
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。
