tokease 1.13.2__tar.gz

tokease-1.13.2/MANIFEST.in

@@ -0,0 +1,2 @@
+include tokease_build.py
+include src/tokease/_pkg_version.txt

tokease-1.13.2/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: tokease
+Version: 1.13.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
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == "pandas"
+
+# tokease
+
+词易算力指数平台的 Python SDK。不发请求也能查看每个接口的输入参数和输出字段；配置 API Key 后可以查询 `index_basic`、`index_daily`、`index_quote`、`trade_cal`，以及无需 Key 的公开行情接口。
+
+## 安装
+
+发布到 PyPI 之后：
+
+```bash
+pip install tokease
+pip install "tokease[pandas]"
+```
+
+在仓库里开发：
+
+```bash
+pip install -e python/tokease
+```
+
+## 查看接口参数
+
+```python
+import tokease
+
+tokease.apis()
+tokease.apis("query")
+tokease.api_params("index_daily")
+tokease.api_fields("index_daily")
+tokease.describe("index_quote")
+```
+
+`api_params` 返回的名称与 `POST /api/v1/query` 的参数白名单一致。未知参数会在本地直接拒绝，不会发给服务端。
+
+## 查询数据
+
+```python
+import tokease
+
+client = tokease.Client(api_key="tokease_xxxxxxxxxxxx_xxxxxxxx")
+frame = client.index_daily(
+    index_code="Server_Index",
+    start_date="20260801",
+    end_date="20260831",
+    fields=["trade_date", "index_code", "index_value", "change_rate"],
+).to_dataframe()
+```
+
+API Key 也可以通过环境变量 `TOKEASE_API_KEY` 传入。服务地址是 `pyproject.toml` 里的 `Homepage`，当前为 `https://whale.tokease.cn`。
+
+默认会按 `has_more` 自动翻页。只要单页时传入 `paginate=False`。
+
+公开接口不需要 API Key：
+
+```python
+client = tokease.Client()
+client.public_indices()
+client.public_index_latest("Server_Index")
+```
+
+## 发布到 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。

tokease-1.13.2/README.md

@@ -0,0 +1,71 @@
+# tokease
+
+词易算力指数平台的 Python SDK。不发请求也能查看每个接口的输入参数和输出字段；配置 API Key 后可以查询 `index_basic`、`index_daily`、`index_quote`、`trade_cal`，以及无需 Key 的公开行情接口。
+
+## 安装
+
+发布到 PyPI 之后：
+
+```bash
+pip install tokease
+pip install "tokease[pandas]"
+```
+
+在仓库里开发：
+
+```bash
+pip install -e python/tokease
+```
+
+## 查看接口参数
+
+```python
+import tokease
+
+tokease.apis()
+tokease.apis("query")
+tokease.api_params("index_daily")
+tokease.api_fields("index_daily")
+tokease.describe("index_quote")
+```
+
+`api_params` 返回的名称与 `POST /api/v1/query` 的参数白名单一致。未知参数会在本地直接拒绝，不会发给服务端。
+
+## 查询数据
+
+```python
+import tokease
+
+client = tokease.Client(api_key="tokease_xxxxxxxxxxxx_xxxxxxxx")
+frame = client.index_daily(
+    index_code="Server_Index",
+    start_date="20260801",
+    end_date="20260831",
+    fields=["trade_date", "index_code", "index_value", "change_rate"],
+).to_dataframe()
+```
+
+API Key 也可以通过环境变量 `TOKEASE_API_KEY` 传入。服务地址是 `pyproject.toml` 里的 `Homepage`，当前为 `https://whale.tokease.cn`。
+
+默认会按 `has_more` 自动翻页。只要单页时传入 `paginate=False`。
+
+公开接口不需要 API Key：
+
+```python
+client = tokease.Client()
+client.public_indices()
+client.public_index_latest("Server_Index")
+```
+
+## 发布到 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。

tokease-1.13.2/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "tokease_build"
+backend-path = ["."]
+
+[project]
+name = "tokease"
+dynamic = ["version"]
+description = "词易算力指数平台 Python SDK：查看接口参数并查询行情数据"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "WhaleIndex" }]
+keywords = ["tokease", "whaleindex", "index", "api"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=2"]
+
+[project.urls]
+Homepage = "https://whale.tokease.cn/"
+Documentation = "https://whale.tokease.cn/handbook/"
+Repository = "https://github.com/fyinfor/WhaleIndex"
+Changelog = "https://github.com/fyinfor/WhaleIndex/releases"
+
+[tool.setuptools.dynamic]
+version = { attr = "tokease.version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tokease*"]
+
+[tool.setuptools.package-data]
+tokease = ["_pkg_version.txt"]

tokease-1.13.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokease-1.13.2/src/tokease/__init__.py

@@ -0,0 +1,31 @@
+"""词易算力指数平台 Python SDK。"""
+
+from tokease.catalog import (
+    APISpec,
+    Field,
+    Param,
+    api_fields,
+    api_params,
+    apis,
+    describe,
+    get_api,
+)
+from tokease.client import Client, QueryResult
+from tokease.errors import TokeaseAPIError, TokeaseError
+from tokease.version import __version__
+
+__all__ = [
+    "__version__",
+    "APISpec",
+    "Client",
+    "Field",
+    "Param",
+    "QueryResult",
+    "TokeaseAPIError",
+    "TokeaseError",
+    "api_fields",
+    "api_params",
+    "apis",
+    "describe",
+    "get_api",
+]

tokease-1.13.2/src/tokease/_pkg_version.txt

@@ -0,0 +1 @@
+1.13.2

tokease-1.13.2/src/tokease/catalog.py

@@ -0,0 +1,393 @@
+"""算力指数平台接口参数目录。
+
+参数名、字段名与服务端白名单一致，见 ``POST /api/v1/query`` 与公开行情接口。
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from tokease.errors import TokeaseError
+
+QUERY_PATH = "/api/v1/query"
+DEFAULT_LIMIT = 1000
+MAX_LIMIT = 5000
+
+
+@dataclass(frozen=True)
+class Param:
+    """单个输入参数。"""
+
+    name: str
+    type: str
+    required: bool
+    description: str
+    location: str = "params"
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Field:
+    """单个输出字段。"""
+
+    name: str
+    type: str
+    description: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class APISpec:
+    """一个数据集或公开接口的完整说明。"""
+
+    name: str
+    kind: str
+    summary: str
+    method: str
+    path: str
+    params: tuple[Param, ...]
+    fields: tuple[Field, ...]
+    scope: str | None = None
+    timeliness: str = "none"
+    default_fields: tuple[str, ...] = ()
+    sort: tuple[str, ...] = ()
+    # 不能同时出现的参数组。例如 trade_date 不能和 start_date/end_date 一起用。
+    exclusive: tuple[tuple[str, ...], ...] = ()
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "summary": self.summary,
+            "method": self.method,
+            "path": self.path,
+            "scope": self.scope,
+            "timeliness": self.timeliness,
+            "params": [item.as_dict() for item in self.params],
+            "fields": [item.as_dict() for item in self.fields],
+            "default_fields": list(self.default_fields),
+            "sort": list(self.sort),
+        }
+
+
+def _param(name: str, description: str, *, required: bool = False, type: str = "str", location: str = "params") -> Param:
+    return Param(name=name, type=type, required=required, description=description, location=location)
+
+
+def _field(name: str, type: str, description: str) -> Field:
+    return Field(name=name, type=type, description=description)
+
+
+_DATE = "日期，YYYYMMDD 或 YYYY-MM-DD，含边界"
+
+_APIS: dict[str, APISpec] = {
+    "index_basic": APISpec(
+        name="index_basic",
+        kind="query",
+        summary="指数基本信息",
+        method="POST",
+        path=QUERY_PATH,
+        scope="index:read",
+        timeliness="none",
+        params=(_param("index_code", "指数代码，精确匹配，如 Server_Index"),),
+        fields=(
+            _field("index_code", "str", "唯一指数代码，例如 Server_Index"),
+            _field("index_name", "str", "指数中文名称"),
+            _field("description", "str", "指数说明；未填写时为空字符串"),
+            _field("base_date", "str|null", "基准日期，YYYYMMDD"),
+            _field("base_value", "decimal", "基准点位"),
+            _field("visibility", "str", "公开范围：private / index_only / aggregate / member"),
+            _field("enabled", "bool", "是否启用"),
+        ),
+        default_fields=("index_code", "index_name", "description", "base_date", "base_value", "visibility", "enabled"),
+        sort=("sort_no", "index_code"),
+    ),
+    "index_daily": APISpec(
+        name="index_daily",
+        kind="query",
+        summary="指数日线（点位 / 加权价格）",
+        method="POST",
+        path=QUERY_PATH,
+        scope="index:read",
+        timeliness="member",
+        params=(
+            _param("index_code", "指数代码，如 Server_Index"),
+            _param("trade_date", "交易日期，不能与 start_date/end_date 同用"),
+            _param("start_date", f"开始{_DATE}"),
+            _param("end_date", f"结束{_DATE}"),
+        ),
+        fields=(
+            _field("trade_date", "str", "交易日期，YYYYMMDD"),
+            _field("index_code", "str", "指数代码"),
+            _field("weighted_price", "decimal", "整体加权价格 Σ(price × weight)"),
+            _field("index_value", "decimal", "当日指数点位"),
+            _field("previous_price", "decimal|null", "上一可计算报价日的整体价格"),
+            _field("previous_index", "decimal|null", "上一可计算报价日的指数点位"),
+            _field("change_rate", "decimal", "涨跌比例，0.0123 表示 1.23%"),
+            _field("calculated_at", "str", "计算时间，RFC 3339"),
+        ),
+        default_fields=(
+            "trade_date",
+            "index_code",
+            "weighted_price",
+            "index_value",
+            "previous_price",
+            "previous_index",
+            "change_rate",
+            "calculated_at",
+        ),
+        sort=("trade_date", "index_code"),
+        exclusive=(("trade_date",), ("start_date", "end_date")),
+    ),
+    "index_quote": APISpec(
+        name="index_quote",
+        kind="query",
+        summary="规格报价明细",
+        method="POST",
+        path=QUERY_PATH,
+        scope="quote:read",
+        timeliness="member",
+        params=(
+            _param("index_code", "指数代码，如 Server_Index"),
+            _param("trade_date", "报价日期，不能与 start_date/end_date 同用"),
+            _param("start_date", f"开始{_DATE}"),
+            _param("end_date", f"结束{_DATE}"),
+            _param("specification", "规格名称，精确匹配，如 B300"),
+        ),
+        fields=(
+            _field("trade_date", "str", "报价日期，YYYYMMDD"),
+            _field("index_code", "str", "指数代码"),
+            _field("specification", "str", "规格名称"),
+            _field("weight", "decimal", "权重，同日同指数合计为 1"),
+            _field("price", "decimal", "规格报价"),
+        ),
+        default_fields=("trade_date", "index_code", "specification", "weight", "price"),
+        sort=("trade_date", "index_code", "specification"),
+        exclusive=(("trade_date",), ("start_date", "end_date")),
+    ),
+    "trade_cal": APISpec(
+        name="trade_cal",
+        kind="query",
+        summary="交易日历",
+        method="POST",
+        path=QUERY_PATH,
+        scope="calendar:read",
+        timeliness="none",
+        params=(
+            _param("trade_date", "日期，不能与 start_date/end_date 同用"),
+            _param("start_date", f"开始{_DATE}"),
+            _param("end_date", f"结束{_DATE}"),
+        ),
+        fields=(
+            _field("trade_date", "str", "日期，YYYYMMDD"),
+            _field("is_workday", "bool", "是否为指数工作日"),
+            _field("remark", "str", "节假日或特殊说明"),
+        ),
+        default_fields=("trade_date", "is_workday", "remark"),
+        sort=("trade_date",),
+        exclusive=(("trade_date",), ("start_date", "end_date")),
+    ),
+    "public_config": APISpec(
+        name="public_config",
+        kind="public",
+        summary="公开系统配置",
+        method="GET",
+        path="/api/v1/public/config",
+        params=(),
+        fields=(
+            _field("registration_enabled", "bool", "是否开放自助注册"),
+            _field("site_url", "str", "网站卡片链接"),
+            _field("site_name", "str", "网站卡片名称"),
+            _field("sms_login_enabled", "bool", "是否开放手机验证码登录"),
+            _field("sms_registration_enabled", "bool", "注册时是否要求短信验证"),
+            _field("sms_password_reset_enabled", "bool", "是否开放短信找回密码"),
+            _field("sms_international_enabled", "bool", "是否允许国际号码"),
+            _field("sms_code_length", "int", "验证码位数"),
+            _field("sms_resend_seconds", "int", "注册等场景的验证码发送间隔（秒）"),
+            _field("sms_login_resend_seconds", "int", "登录场景的验证码发送间隔（秒）"),
+        ),
+        default_fields=(
+            "registration_enabled",
+            "site_url",
+            "site_name",
+            "sms_login_enabled",
+            "sms_registration_enabled",
+            "sms_password_reset_enabled",
+            "sms_international_enabled",
+            "sms_code_length",
+            "sms_resend_seconds",
+            "sms_login_resend_seconds",
+        ),
+    ),
+    "public_indices": APISpec(
+        name="public_indices",
+        kind="public",
+        summary="公开指数列表及最新点位",
+        method="GET",
+        path="/api/v1/public/indices",
+        timeliness="member",
+        params=(),
+        fields=(
+            _field("index_code", "str", "指数代码"),
+            _field("index_name", "str", "指数名称"),
+            _field("description", "str", "指数说明"),
+            _field("base_date", "str", "基准日期"),
+            _field("base_value", "str", "基准点位"),
+            _field("visibility", "str", "公开范围"),
+            _field("sort_no", "int", "展示顺序"),
+            _field("enabled", "bool", "是否启用"),
+            _field("latest", "object|null", "最新日数据；aggregate 指数才含 weighted_price"),
+        ),
+        default_fields=(
+            "index_code",
+            "index_name",
+            "description",
+            "base_date",
+            "base_value",
+            "visibility",
+            "sort_no",
+            "enabled",
+            "latest",
+        ),
+    ),
+    "public_index_daily": APISpec(
+        name="public_index_daily",
+        kind="public",
+        summary="公开指数日线序列",
+        method="GET",
+        path="/api/v1/public/index-daily/{index_code}",
+        timeliness="member",
+        params=(
+            _param("index_code", "指数代码", required=True, location="path"),
+            _param("start_date", f"开始{_DATE}", location="query"),
+            _param("end_date", f"结束{_DATE}", location="query"),
+        ),
+        fields=(
+            _field("trade_date", "str", "交易日期，YYYY-MM-DD"),
+            _field("index_code", "str", "指数代码"),
+            _field("weighted_price", "decimal|null", "整体加权价格，仅 aggregate 指数返回"),
+            _field("index_value", "decimal", "当日指数点位"),
+            _field("change_rate", "decimal", "涨跌比例"),
+            _field("calculated_at", "str", "计算时间，RFC 3339"),
+        ),
+        default_fields=("trade_date", "index_code", "weighted_price", "index_value", "change_rate", "calculated_at"),
+    ),
+    "public_index_quotes": APISpec(
+        name="public_index_quotes",
+        kind="public",
+        summary="公开规格报价序列，仅 aggregate 指数",
+        method="GET",
+        path="/api/v1/public/index-quotes/{index_code}",
+        timeliness="member",
+        params=(
+            _param("index_code", "指数代码", required=True, location="path"),
+            _param("start_date", f"开始{_DATE}", location="query"),
+            _param("end_date", f"结束{_DATE}", location="query"),
+        ),
+        fields=(
+            _field("trade_date", "str", "交易日期，YYYY-MM-DD"),
+            _field("index_code", "str", "指数代码"),
+            _field("specification", "str", "规格名称"),
+            _field("weight", "decimal", "权重"),
+            _field("price", "decimal", "报价"),
+            _field("weighted_price", "decimal", "price × weight"),
+        ),
+        default_fields=("trade_date", "index_code", "specification", "weight", "price", "weighted_price"),
+    ),
+    "public_index_latest": APISpec(
+        name="public_index_latest",
+        kind="public",
+        summary="公开指数最新点位",
+        method="GET",
+        path="/api/v1/public/index-daily/{index_code}/latest",
+        timeliness="member",
+        params=(_param("index_code", "指数代码", required=True, location="path"),),
+        fields=(
+            _field("trade_date", "str", "交易日期，YYYY-MM-DD"),
+            _field("index_code", "str", "指数代码"),
+            _field("weighted_price", "decimal|null", "整体加权价格，仅 aggregate 指数返回"),
+            _field("index_value", "decimal", "当日指数点位"),
+            _field("change_rate", "decimal", "涨跌比例"),
+            _field("calculated_at", "str", "计算时间，RFC 3339"),
+        ),
+        default_fields=("trade_date", "index_code", "weighted_price", "index_value", "change_rate", "calculated_at"),
+    ),
+    "public_membership": APISpec(
+        name="public_membership",
+        kind="public",
+        summary="当前会话的会员权益",
+        method="GET",
+        path="/api/v1/public/membership",
+        params=(),
+        fields=(
+            _field("active", "bool", "是否有效会员"),
+            _field("tier", "str", "等级代码"),
+            _field("expires_at", "str|null", "到期时间"),
+            _field("latest", "bool", "当前身份是否可查看最新已发布数据"),
+            _field("delay_days", "int", "免费用户延迟交易日数"),
+            _field("cutoff", "str|null", "当前可见的数据截止日"),
+            _field("first_eligible", "bool", "是否仍享有首月优惠资格"),
+            _field("free_benefits", "object", "免费用户权益"),
+            _field("benefits", "object", "当前身份的实际权益"),
+            _field("tiers", "array", "全部会员等级及其权益"),
+            _field("plans", "array", "上架套餐"),
+            _field("payment_enabled", "bool", "在线支付开关"),
+            _field("methods", "array", "可用支付方式"),
+        ),
+        default_fields=(
+            "active",
+            "tier",
+            "expires_at",
+            "latest",
+            "delay_days",
+            "cutoff",
+            "first_eligible",
+            "free_benefits",
+            "benefits",
+            "tiers",
+            "plans",
+            "payment_enabled",
+            "methods",
+        ),
+    ),
+}
+
+
+def apis(kind: str | None = None) -> list[str]:
+    """返回接口名称。``kind`` 可取 ``query`` 或 ``public``。"""
+    if kind is None:
+        return list(_APIS)
+    if kind not in {"query", "public"}:
+        raise TokeaseError("kind 只能是 query 或 public")
+    return [name for name, spec in _APIS.items() if spec.kind == kind]
+
+
+def get_api(api_name: str) -> APISpec:
+    """返回指定接口的完整说明。"""
+    try:
+        return _APIS[api_name]
+    except KeyError as exc:
+        known = ", ".join(_APIS)
+        raise TokeaseError(f"未知接口 {api_name!r}，可选：{known}") from exc
+
+
+def api_params(api_name: str) -> tuple[Param, ...]:
+    """返回指定接口的输入参数。"""
+    return get_api(api_name).params
+
+
+def api_fields(api_name: str) -> tuple[Field, ...]:
+    """返回指定接口的输出字段。"""
+    return get_api(api_name).fields
+
+
+def describe(api_name: str | None = None) -> dict[str, Any] | list[dict[str, Any]]:
+    """返回一个或全部接口的参数、字段与权限说明。"""
+    if api_name is None:
+        return [spec.as_dict() for spec in _APIS.values()]
+    return get_api(api_name).as_dict()