Metadata-Version: 2.4
Name: ecapi-sdk
Version: 3.2.5
Summary: ECAPI SDK for Python
Author: EaseCation
License: MIT
Project-URL: Homepage, https://github.com/easecation/easecation-api/tree/main/sdk/python/ecapi-sdk
Project-URL: Documentation, https://github.com/easecation/easecation-api/tree/main/sdk/python/ecapi-sdk#readme
Project-URL: Source, https://github.com/easecation/easecation-api
Project-URL: Issues, https://github.com/easecation/easecation-api/issues
Keywords: ecapi,easecation,sdk,python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# ecapi-sdk (Python)

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

## 安装

```bash
pip install ecapi-sdk
```

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

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

## 快速开始

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

## 认证方式

```python
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 会在每次请求前调用它：

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

## 常用调用

```python
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.punish.create({
    "type": "WARNING",
    "ecid": "player-ecid",
    "source": "console",
    "reason": "测试警告",
})
```

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

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

## 契约说明

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