ecapi-sdk (Python)

ECAPI 的 Python SDK，面向当前重构后的 REST/OpenAPI 契约。当前门面由 openapi.json 生成并覆盖全部 160 个接口，并随包提供 py.typed 与 client.pyi，方便 IDE 显示参数、必填字段和 docstring。

安装

pip install ecapi-sdk

仓库内更新 SDK 文档和类型提示：

python3 sdk/generate_sdk_api_reference.py
python3 -m py_compile sdk/python/ecapi-sdk/src/ecapi_sdk/client.py

快速开始

from ecapi_sdk import ECAPIClient, ECAPIError, is_ecapi_error

client = ECAPIClient(
    base_url="https://api.easecation.net",
    auth={"type": "apiKey", "apiKey": "ec_xxx"},
)

try:
    me = client.user.get_me()
    player = client.player.get_info({"displayName": "Steve"})
    wallet = client.player.get_wallet("player-ecid")
except ECAPIError as error:
    print(error.status, error.code, error.request_id, str(error))
    raise

认证方式

client.set_api_key("ec_xxx")
client.set_bearer_token("iam-jwt-token")
client.set_app_session_token("app-session-token")
client.clear_auth()

也可以在单次请求中传入 auth=... 覆盖默认认证；传 auth=None 表示本次不发送认证。

认证来自 IAM callback、短期 token 或其它动态来源时，可以使用 auth_provider，SDK 会在每次请求前调用它：

client = ECAPIClient(
    auth_provider=lambda: {"type": "apiKey", "apiKey": get_current_api_key()},
)

如果 auth_provider 返回 awaitable，且当前没有正在运行的 event loop，同步客户端会用 asyncio.run() 等待它；在已有 event loop 中请使用同步 provider 或在业务层先解析认证。

类型提示与文档

client.py 与 client.pyi 均从 OpenAPI 生成，query/body 会生成 TypedDict，字段必填性来自 OpenAPI。
API_REFERENCE.md 会列出方法、接口说明、权限、HTTP 方法、路径、必填参数和可选参数。
ECAPIError 会提取服务端错误 envelope 中的 code、request_id、details、field 和用户友好的 message。

常用调用

client.system.get_health()
client.system.get_liveness()
client.system.get_readiness()

client.player.search_ecid({"search": "Steve"})
client.player.cutoff_leaderboard.get_leaderboard({"game": "bedwar"})
client.server.leaderboard.get_top({
    "game": "labour",
    "scoreType": "ONLINE",
    "deadlineType": "WEEK",
})
client.player.leaderboard.get_rank("player-ecid", {
    "game": "labour",
    "scoreType": "ONLINE",
    "deadlineType": "MONTH",
})
client.punish.create({
    "type": "WARNING",
    "ecid": "player-ecid",
    "source": "console",
    "reason": "测试警告",
})

未封装或临时接口可使用统一入口：

client.request("GET", "/players/info", query={"displayName": "Steve"})

契约说明

本 SDK 不提供旧路径兼容别名，所有方法都调用新的 REST/OpenAPI 路径。OpenAPI 是路径、参数和权限说明的唯一事实源，完整方法请查看 API_REFERENCE.md。

Metadata

Release files for ecapi-sdk 3.7.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ecapi-sdk 3.7.7
File	Size	Uploaded
ecapi_sdk-3.7.7.tar.gz	33.5 kB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ecapi-sdk 3.7.7
File	Interpreter	ABI	Platform	Reset
ecapi_sdk-3.7.7-py3-none-any.whl 31.8 kB Oct 12, 2026	Python 3	none	any	Details

Total release size: 65.3 kB

Release files / ecapi_sdk-3.7.7.tar.gz

Download URL	ecapi_sdk-3.7.7.tar.gz
Size	33.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`8d819a3984c12e1e3bb710226a3437a76f9a90da50b05f68cde9e0bfd7f97e94`
BLAKE2b-256 checksum How to use checksums	`9a1a75e8617dbc22eed8c9840d846c0c68b078e66dc500c8916da5ff37cf14b0`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / ecapi_sdk-3.7.7-py3-none-any.whl

Download URL	ecapi_sdk-3.7.7-py3-none-any.whl
Size	31.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3588d65c636fe063e351a16eb8ecdc2a4b10724ff2c39821e7fbdbef168b5f27`
BLAKE2b-256 checksum How to use checksums	`5b18fe8f0d7f05d5b19a93a746efc08f3ce71c8cf9cedba3ba494432a3f9ae51`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`