ecapi-sdk 0.1.3__tar.gz → 3.1.1__tar.gz

ecapi_sdk-3.1.1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: ecapi-sdk
+Version: 3.1.1
+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("legacy-or-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": "测试警告",
+})
+client.punish.set_parkour_punishment({
+    "ecid": "player-ecid",
+    "map": "parkour_01",
+    "start": 1717200000,
+    "end": 1717286400,
+    "usetime": 12345,
+})
+```
+
+未封装或临时接口可使用统一入口：
+
+```python
+client.request("GET", "/players/info", query={"displayName": "Steve"})
+```
+
+## 契约说明
+
+本 SDK 不提供旧路径兼容别名，所有方法都调用新的 REST/OpenAPI 路径。OpenAPI 是路径、参数和权限说明的唯一事实源，完整方法请查看 `API_REFERENCE.md`。

ecapi_sdk-3.1.1/README.md

@@ -0,0 +1,96 @@
+# 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("legacy-or-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": "测试警告",
+})
+client.punish.set_parkour_punishment({
+    "ecid": "player-ecid",
+    "map": "parkour_01",
+    "start": 1717200000,
+    "end": 1717286400,
+    "usetime": 12345,
+})
+```
+
+未封装或临时接口可使用统一入口：
+
+```python
+client.request("GET", "/players/info", query={"displayName": "Steve"})
+```
+
+## 契约说明
+
+本 SDK 不提供旧路径兼容别名，所有方法都调用新的 REST/OpenAPI 路径。OpenAPI 是路径、参数和权限说明的唯一事实源，完整方法请查看 `API_REFERENCE.md`。

{ecapi_sdk-0.1.3 → ecapi_sdk-3.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ecapi-sdk"
-version = "0.1.3"
+version = "3.1.1"
 description = "ECAPI SDK for Python"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -34,4 +34,3 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 ecapi_sdk = ["py.typed", "*.pyi"]
-

ecapi_sdk-3.1.1/src/ecapi_sdk/__init__.py

@@ -0,0 +1,3 @@
+from .client import ECAPIClient, ECAPIError, is_ecapi_error
+
+__all__ = ["ECAPIClient", "ECAPIError", "is_ecapi_error"]