jietng 0.1.0__tar.gz

jietng-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matsuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jietng-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: jietng
+Version: 0.1.0
+Summary: Python SDK for the JiETNG maimai DX (舞萌DX) score management API.
+Author-email: Matsuki <matsuk1@proton.me>
+License: MIT
+Project-URL: Homepage, https://jietng.matsuk1.com
+Project-URL: Repository, https://github.com/Matsuk1/JiETNG
+Project-URL: Documentation, https://jietng.matsuk1.com/developer-api
+Project-URL: Issues, https://github.com/Matsuk1/JiETNG/issues
+Keywords: maimai,maimai-dx,舞萌DX,舞萌查分器,查分器,rating-calculator,best-50,b50,score-tracker,line-bot,jietng
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# jietng — Python SDK
+
+[`pip install jietng`](https://pypi.org/project/jietng/) — Python 客户端，封装 [JiETNG](https://jietng.matsuk1.com) 舞萌DX 查分器的 HTTP API。
+
+支持同步 / 异步两套客户端、覆盖全部 v2 端点（用户 / 权限 / 同步 / 搜歌 / 成绩图 / 导出 …）、类型注解齐全。
+
+## 安装
+
+```bash
+pip install jietng
+```
+
+需要 Python ≥ 3.8、httpx ≥ 0.25。
+
+## 获取 Token
+
+JiETNG API 通过 Bearer Token 鉴权。申请方式见 <https://jietng.matsuk1.com/developer-api> —— 发邮件到 `matsuk1@proton.me` 索取。
+
+## 快速开始
+
+### 同步
+
+```python
+from jietng import jietngClient
+
+with jietngClient(token="your_token") as client:
+    users = client.users.list()
+    print(users["count"], "registered users")
+
+    # 取 B50 成绩图（返回 PNG bytes）
+    png = client.images.records("U1234567890", command="b50")
+    with open("b50.png", "wb") as f:
+        f.write(png)
+
+    # 触发后台同步
+    task = client.users.trigger_sync("U1234567890")
+    print("queued:", task["task_id"])
+
+    # 导出成绩为 JSON / XML，文件名由服务端推荐（含玩家名 + 时间戳）
+    path = client.exports.save("U1234567890", fmt="json")
+    print("exported to", path)
+```
+
+### 异步
+
+```python
+import asyncio
+from jietng import AsyncjietngClient
+
+async def main():
+    async with AsyncjietngClient(token="your_token") as client:
+        print(await client.songs.search("PANDORA", ver="jp", max_results=3))
+        png = await client.images.plate("U1234567890", title="真神")
+        with open("plate.png", "wb") as f:
+            f.write(png)
+
+asyncio.run(main())
+```
+
+## 资源总览
+
+| 命名空间 | 主要方法 |
+|---|---|
+| `client.users` | `list / get / create / delete / trigger_sync / bind / update_bind / get_rebind_url / get_settings_url` |
+| `client.permissions` | `request / list_requests / accept / reject / revoke / revoke_self` |
+| `client.songs` | `search / info` |
+| `client.tasks` | `get` |
+| `client.versions` | `list` |
+| `client.dxdata` | `get` |
+| `client.images` | `user_song / records / plate / achievement` |
+| `client.exports` | `download / save` |
+
+所有方法的形参 / 返回结构与 [JiETNG API 文档](https://jietng.matsuk1.com/developer-api) 一一对应。
+
+## 错误处理
+
+所有 HTTP 非 2xx 状态都会抛 `APIError` 子类。可以按需 catch 具体类型：
+
+```python
+from jietng import jietngClient, NotFoundError, PermissionDeniedError, RateLimitedError, QueueFullError
+
+try:
+    png = client.images.records("U_unknown", command="b50")
+except NotFoundError:
+    print("user has no records yet")
+except PermissionDeniedError:
+    print("your token doesn't have access to this user")
+except RateLimitedError:
+    print("slow down")
+except QueueFullError:
+    print("server task queue is full, retry later")
+```
+
+完整异常层级：
+
+```
+jietngError                  # 基类
+└─ APIError                  # 任意 HTTP 非 2xx
+   ├─ ValidationError        # 400
+   ├─ AuthenticationError    # 401
+   ├─ PermissionDeniedError  # 403
+   ├─ NotFoundError          # 404
+   ├─ RateLimitedError       # 429
+   ├─ ServerError            # 500
+   └─ QueueFullError         # 503
+```
+
+每个异常实例都带 `status_code` / `error` / `message` / `payload` 字段，方便排查。
+
+## 自定义
+
+```python
+client = jietngClient(
+    token="your_token",
+    base_url="https://your-self-hosted.example.com/api/v2",   # 自托管时
+    timeout=60.0,
+    extra_headers={"X-App-Name": "MyBot"},
+)
+```
+
+## 许可
+
+MIT。代码：<https://github.com/Matsuk1/JiETNG/tree/main/client>

jietng-0.1.0/README.md

@@ -0,0 +1,123 @@
+# jietng — Python SDK
+
+[`pip install jietng`](https://pypi.org/project/jietng/) — Python 客户端，封装 [JiETNG](https://jietng.matsuk1.com) 舞萌DX 查分器的 HTTP API。
+
+支持同步 / 异步两套客户端、覆盖全部 v2 端点（用户 / 权限 / 同步 / 搜歌 / 成绩图 / 导出 …）、类型注解齐全。
+
+## 安装
+
+```bash
+pip install jietng
+```
+
+需要 Python ≥ 3.8、httpx ≥ 0.25。
+
+## 获取 Token
+
+JiETNG API 通过 Bearer Token 鉴权。申请方式见 <https://jietng.matsuk1.com/developer-api> —— 发邮件到 `matsuk1@proton.me` 索取。
+
+## 快速开始
+
+### 同步
+
+```python
+from jietng import jietngClient
+
+with jietngClient(token="your_token") as client:
+    users = client.users.list()
+    print(users["count"], "registered users")
+
+    # 取 B50 成绩图（返回 PNG bytes）
+    png = client.images.records("U1234567890", command="b50")
+    with open("b50.png", "wb") as f:
+        f.write(png)
+
+    # 触发后台同步
+    task = client.users.trigger_sync("U1234567890")
+    print("queued:", task["task_id"])
+
+    # 导出成绩为 JSON / XML，文件名由服务端推荐（含玩家名 + 时间戳）
+    path = client.exports.save("U1234567890", fmt="json")
+    print("exported to", path)
+```
+
+### 异步
+
+```python
+import asyncio
+from jietng import AsyncjietngClient
+
+async def main():
+    async with AsyncjietngClient(token="your_token") as client:
+        print(await client.songs.search("PANDORA", ver="jp", max_results=3))
+        png = await client.images.plate("U1234567890", title="真神")
+        with open("plate.png", "wb") as f:
+            f.write(png)
+
+asyncio.run(main())
+```
+
+## 资源总览
+
+| 命名空间 | 主要方法 |
+|---|---|
+| `client.users` | `list / get / create / delete / trigger_sync / bind / update_bind / get_rebind_url / get_settings_url` |
+| `client.permissions` | `request / list_requests / accept / reject / revoke / revoke_self` |
+| `client.songs` | `search / info` |
+| `client.tasks` | `get` |
+| `client.versions` | `list` |
+| `client.dxdata` | `get` |
+| `client.images` | `user_song / records / plate / achievement` |
+| `client.exports` | `download / save` |
+
+所有方法的形参 / 返回结构与 [JiETNG API 文档](https://jietng.matsuk1.com/developer-api) 一一对应。
+
+## 错误处理
+
+所有 HTTP 非 2xx 状态都会抛 `APIError` 子类。可以按需 catch 具体类型：
+
+```python
+from jietng import jietngClient, NotFoundError, PermissionDeniedError, RateLimitedError, QueueFullError
+
+try:
+    png = client.images.records("U_unknown", command="b50")
+except NotFoundError:
+    print("user has no records yet")
+except PermissionDeniedError:
+    print("your token doesn't have access to this user")
+except RateLimitedError:
+    print("slow down")
+except QueueFullError:
+    print("server task queue is full, retry later")
+```
+
+完整异常层级：
+
+```
+jietngError                  # 基类
+└─ APIError                  # 任意 HTTP 非 2xx
+   ├─ ValidationError        # 400
+   ├─ AuthenticationError    # 401
+   ├─ PermissionDeniedError  # 403
+   ├─ NotFoundError          # 404
+   ├─ RateLimitedError       # 429
+   ├─ ServerError            # 500
+   └─ QueueFullError         # 503
+```
+
+每个异常实例都带 `status_code` / `error` / `message` / `payload` 字段，方便排查。
+
+## 自定义
+
+```python
+client = jietngClient(
+    token="your_token",
+    base_url="https://your-self-hosted.example.com/api/v2",   # 自托管时
+    timeout=60.0,
+    extra_headers={"X-App-Name": "MyBot"},
+)
+```
+
+## 许可
+
+MIT。代码：<https://github.com/Matsuk1/JiETNG/tree/main/client>

jietng-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jietng"
+version = "0.1.0"
+description = "Python SDK for the JiETNG maimai DX (舞萌DX) score management API."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Matsuki", email = "matsuk1@proton.me" }]
+requires-python = ">=3.8"
+dependencies = ["httpx>=0.25"]
+keywords = [
+    "maimai", "maimai-dx", "舞萌DX", "舞萌查分器", "查分器",
+    "rating-calculator", "best-50", "b50", "score-tracker",
+    "line-bot", "jietng",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://jietng.matsuk1.com"
+Repository = "https://github.com/Matsuk1/JiETNG"
+Documentation = "https://jietng.matsuk1.com/developer-api"
+Issues = "https://github.com/Matsuk1/JiETNG/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+jietng = ["py.typed"]

jietng-0.1.0/setup.cfg

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

jietng-0.1.0/src/jietng/__init__.py

@@ -0,0 +1,55 @@
+"""jietng — Python SDK for the JiETNG maimai DX score management API.
+
+Quick start::
+
+    from jietng import jietngClient
+
+    client = jietngClient(token="your_token_here")
+    users = client.users.list()
+    b50_png = client.images.records("U1234567890", command="b50")
+
+Async usage::
+
+    import asyncio
+    from jietng import AsyncjietngClient
+
+    async def main():
+        async with AsyncjietngClient(token="your_token_here") as client:
+            png = await client.images.records("U1234567890", command="b50")
+
+    asyncio.run(main())
+
+See https://jietng.matsuk1.com/developer-api for API details and how to
+obtain an access token.
+"""
+
+__version__ = "0.1.0"
+
+from .client import jietngClient
+from .async_client import AsyncjietngClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    jietngError,
+    NotFoundError,
+    PermissionDeniedError,
+    QueueFullError,
+    RateLimitedError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "jietngClient",
+    "AsyncjietngClient",
+    "jietngError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitedError",
+    "ServerError",
+    "QueueFullError",
+]

jietng-0.1.0/src/jietng/_http.py

@@ -0,0 +1,78 @@
+"""HTTP 底层 / Shared HTTP helpers for sync & async clients."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Tuple
+
+import httpx
+
+from . import __version__
+from .exceptions import APIError, from_response
+
+
+DEFAULT_BASE_URL = "https://jietng-endpoint.matsuk1.com/api/v2"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _build_headers(token: str, extra: Optional[Mapping[str, str]] = None) -> dict:
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "User-Agent": f"jietng-py-sdk/{__version__}",
+        "Accept": "application/json",
+    }
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _parse_json_safe(resp: httpx.Response) -> Any:
+    """尽量返回 JSON；失败返回原始 bytes 或文本字符串。"""
+    ctype = (resp.headers.get("content-type") or "").lower()
+    if "application/json" in ctype:
+        try:
+            return resp.json()
+        except Exception:
+            return resp.text
+    if ctype.startswith(("image/", "application/octet-stream", "application/xml")):
+        return resp.content
+    if "text/" in ctype:
+        return resp.text
+    # 兜底：尝试 JSON，否则原始字节
+    try:
+        return resp.json()
+    except Exception:
+        return resp.content
+
+
+def _check_response(resp: httpx.Response) -> Any:
+    """成功 → 返回解析后的内容；失败 → 抛对应 APIError 子类。"""
+    payload = _parse_json_safe(resp)
+    if 200 <= resp.status_code < 300:
+        return payload
+    raise from_response(resp.status_code, payload)
+
+
+def _binary_response(resp: httpx.Response) -> bytes:
+    """专给图片/导出文件用：成功返回 bytes，失败仍抛对应异常。"""
+    if 200 <= resp.status_code < 300:
+        return resp.content
+    payload = _parse_json_safe(resp)
+    raise from_response(resp.status_code, payload)
+
+
+def _attachment_filename(resp: httpx.Response) -> Optional[str]:
+    """从 Content-Disposition 头里解析 filename / filename* (RFC 6266)。"""
+    cd = resp.headers.get("content-disposition", "")
+    if not cd:
+        return None
+    # filename*=UTF-8''XXX 优先（CJK 安全）
+    for part in cd.split(";"):
+        part = part.strip()
+        if part.lower().startswith("filename*=utf-8''"):
+            from urllib.parse import unquote
+            return unquote(part.split("''", 1)[1])
+    for part in cd.split(";"):
+        part = part.strip()
+        if part.lower().startswith("filename="):
+            value = part[len("filename="):].strip('"')
+            return value
+    return None

jietng-0.1.0/src/jietng/async_client.py

@@ -0,0 +1,235 @@
+"""异步客户端 / Async client（与 sync 客户端 API 形态完全一致，方法都 async）。"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Tuple
+
+import httpx
+
+from ._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    _attachment_filename,
+    _binary_response,
+    _build_headers,
+    _check_response,
+)
+
+
+class _BaseAsyncResource:
+    __slots__ = ("_client",)
+
+    def __init__(self, client: "AsyncjietngClient"):
+        self._client = client
+
+
+class AsyncUsersResource(_BaseAsyncResource):
+    async def list(self) -> dict:
+        return await self._client._request("GET", "/users")
+
+    async def get(self, user_id: str) -> dict:
+        return await self._client._request("GET", f"/users/{user_id}")
+
+    async def create(self, **fields: Any) -> dict:
+        return await self._client._request("POST", "/users", json=fields)
+
+    async def delete(self, user_id: str) -> dict:
+        return await self._client._request("DELETE", f"/users/{user_id}")
+
+    async def trigger_sync(self, user_id: str) -> dict:
+        return await self._client._request("POST", f"/users/{user_id}/tasks")
+
+    async def get_rebind_url(self, user_id: str) -> dict:
+        return await self._client._request("GET", f"/users/{user_id}/rebind-url")
+
+    async def get_settings_url(self, user_id: str) -> dict:
+        return await self._client._request("GET", f"/users/{user_id}/settings-url")
+
+    async def bind(self, user_id: str, **fields: Any) -> dict:
+        return await self._client._request("POST", f"/users/{user_id}/bind", json=fields)
+
+    async def update_bind(self, user_id: str, **fields: Any) -> dict:
+        return await self._client._request("PUT", f"/users/{user_id}/bind", json=fields)
+
+
+class AsyncPermissionsResource(_BaseAsyncResource):
+    async def request(self, user_id: str, requester_name: Optional[str] = None) -> dict:
+        body = {"requester_name": requester_name} if requester_name else {}
+        return await self._client._request("POST", f"/users/{user_id}/permissions", json=body)
+
+    async def list_requests(self, user_id: str) -> dict:
+        return await self._client._request("GET", f"/users/{user_id}/permissions/requests")
+
+    async def accept(self, user_id: str, request_id: str) -> dict:
+        return await self._client._request(
+            "PATCH",
+            f"/users/{user_id}/permissions/requests/{request_id}",
+            json={"action": "accept"},
+        )
+
+    async def reject(self, user_id: str, request_id: str) -> dict:
+        return await self._client._request(
+            "PATCH",
+            f"/users/{user_id}/permissions/requests/{request_id}",
+            json={"action": "reject"},
+        )
+
+    async def revoke(self, user_id: str, token_id: str) -> dict:
+        return await self._client._request("DELETE", f"/users/{user_id}/permissions/{token_id}")
+
+    async def revoke_self(self, user_id: str) -> dict:
+        return await self._client._request("DELETE", f"/users/{user_id}/permissions/self")
+
+
+class AsyncSongsResource(_BaseAsyncResource):
+    async def search(
+        self,
+        q: str,
+        ver: str = "jp",
+        max_results: int = 6,
+        user_id: Optional[str] = None,
+    ) -> dict:
+        params = {"q": q, "ver": ver, "max_results": max_results}
+        if user_id:
+            params["user_id"] = user_id
+        return await self._client._request("GET", "/songs/search", params=params)
+
+    async def info(self, song_id: str) -> bytes:
+        return await self._client._request("GET", f"/songs/{song_id}/image", binary=True)
+
+
+class AsyncTasksResource(_BaseAsyncResource):
+    async def get(self, task_id: str) -> dict:
+        return await self._client._request("GET", f"/tasks/{task_id}")
+
+
+class AsyncVersionsResource(_BaseAsyncResource):
+    async def list(self) -> dict:
+        return await self._client._request("GET", "/versions")
+
+
+class AsyncDxdataResource(_BaseAsyncResource):
+    async def get(self) -> dict:
+        return await self._client._request("GET", "/dxdata")
+
+
+class AsyncImagesResource(_BaseAsyncResource):
+    async def user_song(self, user_id: str, song_id: str) -> bytes:
+        return await self._client._request(
+            "GET", f"/users/{user_id}/songs/{song_id}/image", binary=True,
+        )
+
+    async def records(self, user_id: str, command: str = "b50") -> bytes:
+        return await self._client._request(
+            "GET", f"/users/{user_id}/image",
+            params={"command": command}, binary=True,
+        )
+
+    async def plate(self, user_id: str, title: str, filter_mode: Optional[str] = None) -> bytes:
+        params: dict = {"title": title}
+        if filter_mode:
+            params["filter"] = filter_mode
+        return await self._client._request(
+            "GET", f"/users/{user_id}/plate", params=params, binary=True,
+        )
+
+    async def achievement(
+        self,
+        user_id: str,
+        level: str,
+        rank: Optional[str] = None,
+        filter_mode: Optional[str] = None,
+    ) -> bytes:
+        params: dict = {"level": level}
+        if rank:
+            params["rank"] = rank
+        if filter_mode:
+            params["filter"] = filter_mode
+        return await self._client._request(
+            "GET", f"/users/{user_id}/achievement", params=params, binary=True,
+        )
+
+
+class AsyncExportsResource(_BaseAsyncResource):
+    async def download(self, user_id: str, fmt: str = "json") -> Tuple[bytes, Optional[str]]:
+        return await self._client._request_with_filename(
+            "GET", f"/users/{user_id}/export", params={"fmt": fmt},
+        )
+
+    async def save(self, user_id: str, fmt: str = "json", path: Optional[str] = None) -> str:
+        content, suggested = await self.download(user_id, fmt=fmt)
+        target = path or suggested or f"jietng-{user_id}.{fmt}"
+        with open(target, "wb") as f:
+            f.write(content)
+        return target
+
+
+# ============================================================
+# 主 async client
+# ============================================================
+
+class AsyncjietngClient:
+    """异步 JiETNG API 客户端。
+
+    Example::
+
+        import asyncio
+        from jietng import AsyncjietngClient
+
+        async def main():
+            async with AsyncjietngClient(token="your_token") as client:
+                users = await client.users.list()
+                png = await client.images.records("U123", command="b50")
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ):
+        if not token:
+            raise ValueError("token is required")
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._headers = _build_headers(token, extra_headers)
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+        self.users = AsyncUsersResource(self)
+        self.permissions = AsyncPermissionsResource(self)
+        self.songs = AsyncSongsResource(self)
+        self.tasks = AsyncTasksResource(self)
+        self.versions = AsyncVersionsResource(self)
+        self.dxdata = AsyncDxdataResource(self)
+        self.images = AsyncImagesResource(self)
+        self.exports = AsyncExportsResource(self)
+
+    async def __aenter__(self) -> "AsyncjietngClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, *, binary: bool = False, **kwargs: Any) -> Any:
+        resp = await self._http.request(method, path, **kwargs)
+        if binary:
+            return _binary_response(resp)
+        return _check_response(resp)
+
+    async def _request_with_filename(
+        self, method: str, path: str, **kwargs: Any,
+    ) -> Tuple[bytes, Optional[str]]:
+        resp = await self._http.request(method, path, **kwargs)
+        content = _binary_response(resp)
+        return content, _attachment_filename(resp)

jietng-0.1.0/src/jietng/client.py

@@ -0,0 +1,290 @@
+"""同步客户端 / Sync client."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Tuple
+
+import httpx
+
+from ._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    _attachment_filename,
+    _binary_response,
+    _build_headers,
+    _check_response,
+)
+
+
+# ============================================================
+# Resource 命名空间
+# ============================================================
+
+class _BaseResource:
+    """资源基类，仅持有 client 引用。"""
+    __slots__ = ("_client",)
+
+    def __init__(self, client: "jietngClient"):
+        self._client = client
+
+
+class UsersResource(_BaseResource):
+    """用户相关：列表 / 详情 / 绑定 / 同步 等。"""
+
+    def list(self) -> dict:
+        """``GET /users`` —— 列出所有已注册用户。"""
+        return self._client._request("GET", "/users")
+
+    def get(self, user_id: str) -> dict:
+        """``GET /users/{user_id}`` —— 取单个用户数据。"""
+        return self._client._request("GET", f"/users/{user_id}")
+
+    def create(self, **fields: Any) -> dict:
+        """``POST /users`` —— 创建用户（管理员 token）。"""
+        return self._client._request("POST", "/users", json=fields)
+
+    def delete(self, user_id: str) -> dict:
+        """``DELETE /users/{user_id}`` —— 删除用户。"""
+        return self._client._request("DELETE", f"/users/{user_id}")
+
+    def trigger_sync(self, user_id: str) -> dict:
+        """``POST /users/{user_id}/tasks`` —— 触发一次 maimai 数据拉取（异步入队）。"""
+        return self._client._request("POST", f"/users/{user_id}/tasks")
+
+    def get_rebind_url(self, user_id: str) -> dict:
+        """``GET /users/{user_id}/rebind-url``"""
+        return self._client._request("GET", f"/users/{user_id}/rebind-url")
+
+    def get_settings_url(self, user_id: str) -> dict:
+        """``GET /users/{user_id}/settings-url``"""
+        return self._client._request("GET", f"/users/{user_id}/settings-url")
+
+    def bind(self, user_id: str, **fields: Any) -> dict:
+        """``POST /users/{user_id}/bind`` —— 首次绑定 SEGA 账号。"""
+        return self._client._request("POST", f"/users/{user_id}/bind", json=fields)
+
+    def update_bind(self, user_id: str, **fields: Any) -> dict:
+        """``PUT /users/{user_id}/bind`` —— 更新已绑定信息。"""
+        return self._client._request("PUT", f"/users/{user_id}/bind", json=fields)
+
+
+class PermissionsResource(_BaseResource):
+    """对某个用户的访问权限管理。"""
+
+    def request(self, user_id: str, requester_name: Optional[str] = None) -> dict:
+        """``POST /users/{user_id}/permissions`` —— 请求访问权限。"""
+        body = {"requester_name": requester_name} if requester_name else {}
+        return self._client._request("POST", f"/users/{user_id}/permissions", json=body)
+
+    def list_requests(self, user_id: str) -> dict:
+        """``GET /users/{user_id}/permissions/requests`` —— owner 查看待处理请求。"""
+        return self._client._request("GET", f"/users/{user_id}/permissions/requests")
+
+    def accept(self, user_id: str, request_id: str) -> dict:
+        """``PATCH …/permissions/requests/{request_id}`` —— owner 接受请求。"""
+        return self._client._request(
+            "PATCH",
+            f"/users/{user_id}/permissions/requests/{request_id}",
+            json={"action": "accept"},
+        )
+
+    def reject(self, user_id: str, request_id: str) -> dict:
+        """``PATCH …/permissions/requests/{request_id}`` —— owner 拒绝请求。"""
+        return self._client._request(
+            "PATCH",
+            f"/users/{user_id}/permissions/requests/{request_id}",
+            json={"action": "reject"},
+        )
+
+    def revoke(self, user_id: str, token_id: str) -> dict:
+        """``DELETE /users/{user_id}/permissions/{token_id}`` —— owner 撤销某个 token 的权限。"""
+        return self._client._request("DELETE", f"/users/{user_id}/permissions/{token_id}")
+
+    def revoke_self(self, user_id: str) -> dict:
+        """``DELETE /users/{user_id}/permissions/self`` —— 当前 token 主动放弃对该用户的权限。"""
+        return self._client._request("DELETE", f"/users/{user_id}/permissions/self")
+
+
+class SongsResource(_BaseResource):
+    """歌曲搜索 + 单曲信息。"""
+
+    def search(
+        self,
+        q: str,
+        ver: str = "jp",
+        max_results: int = 6,
+        user_id: Optional[str] = None,
+    ) -> dict:
+        """``GET /songs/search``"""
+        params = {"q": q, "ver": ver, "max_results": max_results}
+        if user_id:
+            params["user_id"] = user_id
+        return self._client._request("GET", "/songs/search", params=params)
+
+    def info(self, song_id: str) -> dict:
+        """``GET /songs/{song_id}/image`` —— 返回歌曲信息图片（PNG bytes）。"""
+        return self._client._request("GET", f"/songs/{song_id}/image", binary=True)
+
+
+class TasksResource(_BaseResource):
+    def get(self, task_id: str) -> dict:
+        """``GET /tasks/{task_id}``"""
+        return self._client._request("GET", f"/tasks/{task_id}")
+
+
+class VersionsResource(_BaseResource):
+    def list(self) -> dict:
+        """``GET /versions``"""
+        return self._client._request("GET", "/versions")
+
+
+class DxdataResource(_BaseResource):
+    def get(self) -> dict:
+        """``GET /dxdata``"""
+        return self._client._request("GET", "/dxdata")
+
+
+class ImagesResource(_BaseResource):
+    """图片生成系列（返回 PNG bytes）。"""
+
+    def user_song(self, user_id: str, song_id: str) -> bytes:
+        """``GET /users/{user_id}/songs/{song_id}/image``"""
+        return self._client._request(
+            "GET", f"/users/{user_id}/songs/{song_id}/image", binary=True,
+        )
+
+    def records(self, user_id: str, command: str = "b50") -> bytes:
+        """``GET /users/{user_id}/image?command=…`` —— b50/rct50/apb50/… 等成绩图。"""
+        return self._client._request(
+            "GET", f"/users/{user_id}/image",
+            params={"command": command}, binary=True,
+        )
+
+    def plate(self, user_id: str, title: str, filter_mode: Optional[str] = None) -> bytes:
+        """``GET /users/{user_id}/plate?title=…&filter=…``"""
+        params: dict = {"title": title}
+        if filter_mode:
+            params["filter"] = filter_mode
+        return self._client._request(
+            "GET", f"/users/{user_id}/plate", params=params, binary=True,
+        )
+
+    def achievement(
+        self,
+        user_id: str,
+        level: str,
+        rank: Optional[str] = None,
+        filter_mode: Optional[str] = None,
+    ) -> bytes:
+        """``GET /users/{user_id}/achievement?level=…&rank=…&filter=…``"""
+        params: dict = {"level": level}
+        if rank:
+            params["rank"] = rank
+        if filter_mode:
+            params["filter"] = filter_mode
+        return self._client._request(
+            "GET", f"/users/{user_id}/achievement", params=params, binary=True,
+        )
+
+
+class ExportsResource(_BaseResource):
+    """成绩导出（JSON / XML）。"""
+
+    def download(self, user_id: str, fmt: str = "json") -> Tuple[bytes, Optional[str]]:
+        """``GET /users/{user_id}/export?fmt=json|xml``
+
+        Returns:
+            (content_bytes, suggested_filename) —— filename 取自服务端
+            Content-Disposition；可能为 None。
+        """
+        return self._client._request_with_filename(
+            "GET", f"/users/{user_id}/export", params={"fmt": fmt},
+        )
+
+    def save(self, user_id: str, fmt: str = "json", path: Optional[str] = None) -> str:
+        """便捷方法：直接保存到本地。返回最终写入的文件路径。
+
+        Args:
+            user_id: 用户 ID
+            fmt: ``json`` 或 ``xml``
+            path: 完整文件路径；不传则用服务端推荐的文件名写到当前目录
+        """
+        content, suggested = self.download(user_id, fmt=fmt)
+        target = path or suggested or f"jietng-{user_id}.{fmt}"
+        with open(target, "wb") as f:
+            f.write(content)
+        return target
+
+
+# ============================================================
+# 主 client
+# ============================================================
+
+class jietngClient:
+    """同步 JiETNG API 客户端。
+
+    Example::
+
+        from jietng import jietngClient
+
+        client = jietngClient(token="your_token")
+        users = client.users.list()
+        b50_png = client.images.records("U123", command="b50")
+        with open("b50.png", "wb") as f:
+            f.write(b50_png)
+    """
+
+    def __init__(
+        self,
+        token: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        if not token:
+            raise ValueError("token is required")
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._headers = _build_headers(token, extra_headers)
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+        # Resource 命名空间
+        self.users = UsersResource(self)
+        self.permissions = PermissionsResource(self)
+        self.songs = SongsResource(self)
+        self.tasks = TasksResource(self)
+        self.versions = VersionsResource(self)
+        self.dxdata = DxdataResource(self)
+        self.images = ImagesResource(self)
+        self.exports = ExportsResource(self)
+
+    # ---- context manager ----
+
+    def __enter__(self) -> "jietngClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ---- 内部请求方法 ----
+
+    def _request(self, method: str, path: str, *, binary: bool = False, **kwargs: Any) -> Any:
+        resp = self._http.request(method, path, **kwargs)
+        if binary:
+            return _binary_response(resp)
+        return _check_response(resp)
+
+    def _request_with_filename(
+        self, method: str, path: str, **kwargs: Any,
+    ) -> Tuple[bytes, Optional[str]]:
+        resp = self._http.request(method, path, **kwargs)
+        content = _binary_response(resp)
+        return content, _attachment_filename(resp)

jietng-0.1.0/src/jietng/exceptions.py

@@ -0,0 +1,94 @@
+"""异常类型 / Exception hierarchy.
+
+All API failures raise a subclass of :class:`jietngError`. Use specific
+subclasses (``NotFoundError``, ``RateLimitedError`` …) to handle expected
+failure modes; fall back to ``APIError`` for the generic case.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class jietngError(Exception):
+    """SDK 基类异常。所有错误最终都是它或其子类。"""
+
+
+class APIError(jietngError):
+    """HTTP API 返回了非 2xx。
+
+    Attributes:
+        status_code: HTTP 状态码
+        error: 服务器返回的 ``error`` 字段（若有）
+        message: 服务器返回的 ``message`` 字段（若有）
+        payload: 完整的响应 JSON（若服务器返回的是 JSON），方便排查
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        error: Optional[str] = None,
+        message: Optional[str] = None,
+        payload: Any = None,
+    ):
+        self.status_code = status_code
+        self.error = error
+        self.message = message
+        self.payload = payload
+        head = f"[{status_code}]"
+        if error:
+            head += f" {error}"
+        if message:
+            head += f": {message}"
+        super().__init__(head)
+
+
+class AuthenticationError(APIError):
+    """401 - token 缺失 / 无效 / 已撤销。"""
+
+
+class PermissionDeniedError(APIError):
+    """403 - 当前 token 对该用户没有访问权限。"""
+
+
+class NotFoundError(APIError):
+    """404 - 用户 / 任务 / 资源不存在。"""
+
+
+class ValidationError(APIError):
+    """400 - 参数缺失或不合法。"""
+
+
+class RateLimitedError(APIError):
+    """429 - 频率限制触发。"""
+
+
+class ServerError(APIError):
+    """500 - 服务器内部错误。"""
+
+
+class QueueFullError(APIError):
+    """503 - 服务端任务队列已满，请稍后再试。"""
+
+
+# status_code → 异常类
+_STATUS_MAP = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitedError,
+    500: ServerError,
+    503: QueueFullError,
+}
+
+
+def from_response(status_code: int, payload: Any) -> APIError:
+    """根据 HTTP 状态码 + payload 构造对应异常实例。"""
+    cls = _STATUS_MAP.get(status_code, APIError)
+    error = None
+    message = None
+    if isinstance(payload, dict):
+        error = payload.get("error")
+        message = payload.get("message")
+    return cls(status_code, error=error, message=message, payload=payload)

jietng-0.1.0/src/jietng.egg-info/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: jietng
+Version: 0.1.0
+Summary: Python SDK for the JiETNG maimai DX (舞萌DX) score management API.
+Author-email: Matsuki <matsuk1@proton.me>
+License: MIT
+Project-URL: Homepage, https://jietng.matsuk1.com
+Project-URL: Repository, https://github.com/Matsuk1/JiETNG
+Project-URL: Documentation, https://jietng.matsuk1.com/developer-api
+Project-URL: Issues, https://github.com/Matsuk1/JiETNG/issues
+Keywords: maimai,maimai-dx,舞萌DX,舞萌查分器,查分器,rating-calculator,best-50,b50,score-tracker,line-bot,jietng
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# jietng — Python SDK
+
+[`pip install jietng`](https://pypi.org/project/jietng/) — Python 客户端，封装 [JiETNG](https://jietng.matsuk1.com) 舞萌DX 查分器的 HTTP API。
+
+支持同步 / 异步两套客户端、覆盖全部 v2 端点（用户 / 权限 / 同步 / 搜歌 / 成绩图 / 导出 …）、类型注解齐全。
+
+## 安装
+
+```bash
+pip install jietng
+```
+
+需要 Python ≥ 3.8、httpx ≥ 0.25。
+
+## 获取 Token
+
+JiETNG API 通过 Bearer Token 鉴权。申请方式见 <https://jietng.matsuk1.com/developer-api> —— 发邮件到 `matsuk1@proton.me` 索取。
+
+## 快速开始
+
+### 同步
+
+```python
+from jietng import jietngClient
+
+with jietngClient(token="your_token") as client:
+    users = client.users.list()
+    print(users["count"], "registered users")
+
+    # 取 B50 成绩图（返回 PNG bytes）
+    png = client.images.records("U1234567890", command="b50")
+    with open("b50.png", "wb") as f:
+        f.write(png)
+
+    # 触发后台同步
+    task = client.users.trigger_sync("U1234567890")
+    print("queued:", task["task_id"])
+
+    # 导出成绩为 JSON / XML，文件名由服务端推荐（含玩家名 + 时间戳）
+    path = client.exports.save("U1234567890", fmt="json")
+    print("exported to", path)
+```
+
+### 异步
+
+```python
+import asyncio
+from jietng import AsyncjietngClient
+
+async def main():
+    async with AsyncjietngClient(token="your_token") as client:
+        print(await client.songs.search("PANDORA", ver="jp", max_results=3))
+        png = await client.images.plate("U1234567890", title="真神")
+        with open("plate.png", "wb") as f:
+            f.write(png)
+
+asyncio.run(main())
+```
+
+## 资源总览
+
+| 命名空间 | 主要方法 |
+|---|---|
+| `client.users` | `list / get / create / delete / trigger_sync / bind / update_bind / get_rebind_url / get_settings_url` |
+| `client.permissions` | `request / list_requests / accept / reject / revoke / revoke_self` |
+| `client.songs` | `search / info` |
+| `client.tasks` | `get` |
+| `client.versions` | `list` |
+| `client.dxdata` | `get` |
+| `client.images` | `user_song / records / plate / achievement` |
+| `client.exports` | `download / save` |
+
+所有方法的形参 / 返回结构与 [JiETNG API 文档](https://jietng.matsuk1.com/developer-api) 一一对应。
+
+## 错误处理
+
+所有 HTTP 非 2xx 状态都会抛 `APIError` 子类。可以按需 catch 具体类型：
+
+```python
+from jietng import jietngClient, NotFoundError, PermissionDeniedError, RateLimitedError, QueueFullError
+
+try:
+    png = client.images.records("U_unknown", command="b50")
+except NotFoundError:
+    print("user has no records yet")
+except PermissionDeniedError:
+    print("your token doesn't have access to this user")
+except RateLimitedError:
+    print("slow down")
+except QueueFullError:
+    print("server task queue is full, retry later")
+```
+
+完整异常层级：
+
+```
+jietngError                  # 基类
+└─ APIError                  # 任意 HTTP 非 2xx
+   ├─ ValidationError        # 400
+   ├─ AuthenticationError    # 401
+   ├─ PermissionDeniedError  # 403
+   ├─ NotFoundError          # 404
+   ├─ RateLimitedError       # 429
+   ├─ ServerError            # 500
+   └─ QueueFullError         # 503
+```
+
+每个异常实例都带 `status_code` / `error` / `message` / `payload` 字段，方便排查。
+
+## 自定义
+
+```python
+client = jietngClient(
+    token="your_token",
+    base_url="https://your-self-hosted.example.com/api/v2",   # 自托管时
+    timeout=60.0,
+    extra_headers={"X-App-Name": "MyBot"},
+)
+```
+
+## 许可
+
+MIT。代码：<https://github.com/Matsuk1/JiETNG/tree/main/client>

jietng-0.1.0/src/jietng.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/jietng/__init__.py
+src/jietng/_http.py
+src/jietng/async_client.py
+src/jietng/client.py
+src/jietng/exceptions.py
+src/jietng/py.typed
+src/jietng.egg-info/PKG-INFO
+src/jietng.egg-info/SOURCES.txt
+src/jietng.egg-info/dependency_links.txt
+src/jietng.egg-info/requires.txt
+src/jietng.egg-info/top_level.txt

jietng-0.1.0/src/jietng.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jietng-0.1.0/src/jietng.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.25

jietng-0.1.0/src/jietng.egg-info/top_level.txt

@@ -0,0 +1 @@
+jietng