Metadata-Version: 2.4
Name: tokease
Version: 1.14.0
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 后可以查询 `index_basic`、`index_daily`、`index_latest`、`index_quote`、`trade_calendar`。返回范围由 Key 的权限决定。

## 安装

发布到 PyPI 之后：

```bash
pip install tokease
```

在仓库里开发：

```bash
pip install -e python/tokease
```

## 查看接口参数

```python
import tokease

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

`dataset_params` 返回的名称与 `POST /api/v1/query` 的参数白名单一致。未知参数会在本地直接拒绝，不会发给服务端。

## 查询数据

```python
import tokease

client = tokease.Client(api_key="tokease_xxxxxxxxxxxx_xxxxxxxx")
daily = client.index_daily(
    index_code="Server_Index",
    start_date="20260801",
    end_date="20260831",
    fields=["trade_date", "index_code", "index_value", "change_rate"],
)
```

`index_basic`、`index_daily`、`index_latest`、`index_quote`、`trade_calendar` 直接返回 `pandas.DataFrame`。日期列是 `datetime64`，点位、价格和涨跌是数值。

API Key 也可以通过环境变量 `TOKEASE_API_KEY` 传入。服务地址是 `pyproject.toml` 里的 `Homepage`，当前为 `https://whale.tokease.cn`。

默认会按 `has_more` 自动翻页。只要单页时传入 `paginate=False`。`request_id` 写在 `DataFrame.attrs["request_id"]`。

Key 无效或权限不足时抛出 `TokeaseAPIError`。省略 `index_code` 时，服务端只返回该 Key 有权查看的指数。

## 发布到 PyPI

版本号始终等于仓库根目录 `package.json` 的 `version`，不要在 Python 包里另写一份。PyPI 上每个版本只能上传一次。

发布使用 PyPI API Token，不使用 GitHub 受信发布。在 PyPI 账号设置里创建令牌，范围选 **Entire account**，再写入本仓库的 Actions secret `PYPI_API_TOKEN`。之后推送与系统版本一致的标签即可发布。本地 `.githooks/pre-push` 会先核对，版本不一致时标签推不上去：

```bash
git tag v1.13.1
git push origin v1.13.1
```

也可以在 GitHub Actions 里手动运行 **Publish tokease**，选择 `pypi` 或 `testpypi`。TestPyPI 需要在 test.pypi.org 另建一个 API Token，并换成对应的 secret。
