"""Asynchronous MoviePilot REST client.""" from __future__ import annotations from collections.abc import Mapping from dataclasses import dataclass from typing import Any import httpx class MoviePilotError(Exception): """Base exception for MoviePilot integration failures.""" class MoviePilotConfigError(MoviePilotError): """Raised when the client configuration is incomplete or invalid.""" class MoviePilotConnectionError(MoviePilotError): """Raised when MoviePilot cannot be reached.""" class MoviePilotAuthenticationError(MoviePilotError): """Raised when MoviePilot rejects the API token.""" class MoviePilotAPIError(MoviePilotError): """Raised when MoviePilot returns an unsuccessful API response.""" def __init__(self, status_code: int, message: str, data: Any = None) -> None: super().__init__(message) self.status_code = status_code self.message = message self.data = data class MoviePilotResponseError(MoviePilotError): """Raised when a response cannot be decoded as JSON.""" class MoviePilotRateLimitError(MoviePilotAPIError): """Raised when MoviePilot asks the caller to slow down.""" @dataclass(frozen=True, slots=True) class MoviePilotResponse: """Normalized response returned by MoviePilot.""" status_code: int data: Any success: bool | None = None message: str | None = None def _response_message(payload: Any) -> str | None: if not isinstance(payload, Mapping): return None message = payload.get("message") return message if isinstance(message, str) else None def _response_success(payload: Any) -> bool | None: if not isinstance(payload, Mapping): return None success = payload.get("success") return success if isinstance(success, bool) else None class MoviePilotClient: """Small async client for MoviePilot's external API.""" def __init__( self, base_url: str, api_token: str, *, timeout: float = 20.0, retries: int = 2, retry_backoff: float = 0.5, transport: httpx.AsyncBaseTransport | None = None, ) -> None: normalized_url = (base_url or "").strip().rstrip("/") normalized_token = (api_token or "").strip() if not normalized_url: raise MoviePilotConfigError("MoviePilot 地址未配置") if not normalized_token: raise MoviePilotConfigError("MoviePilot API Token 未配置") if not normalized_url.startswith(("http://", "https://")): raise MoviePilotConfigError("MoviePilot 地址必须以 http:// 或 https:// 开头") self.base_url = normalized_url self._api_token = normalized_token self._timeout = httpx.Timeout(timeout) self._retries = max(int(retries), 0) self._retry_backoff = max(float(retry_backoff), 0.0) self._transport = transport self._client: httpx.AsyncClient | None = None async def __aenter__(self) -> "MoviePilotClient": await self.start() return self async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None: await self.close() async def start(self) -> None: if self._client is None: self._client = httpx.AsyncClient( base_url=self.base_url, headers={"X-API-KEY": self._api_token}, timeout=self._timeout, transport=self._transport, ) async def close(self) -> None: if self._client is not None: await self._client.aclose() self._client = None async def request( self, method: str, path: str, *, params: Mapping[str, Any] | None = None, json: Any = None, ) -> MoviePilotResponse: await self.start() assert self._client is not None request_path = path if path.startswith("/") else f"/{path}" request_params = dict(params or {}) request_params.setdefault("token", self._api_token) response: httpx.Response | None = None for attempt in range(self._retries + 1): try: response = await self._client.request( method, request_path, params=request_params, json=json, ) except httpx.TimeoutException as exc: if attempt >= self._retries: raise MoviePilotConnectionError("\u8fde\u63a5 MoviePilot \u5931\u8d25") from exc await self._sleep_before_retry(attempt) continue except httpx.HTTPError as exc: if attempt >= self._retries: raise MoviePilotConnectionError("\u8fde\u63a5 MoviePilot \u5931\u8d25") from exc await self._sleep_before_retry(attempt) continue if response.status_code == 429 or response.status_code >= 500: if attempt < self._retries: await self._sleep_before_retry(attempt, response) continue break assert response is not None if response.status_code in (401, 403): raise MoviePilotAuthenticationError( f"MoviePilot \u9274\u6743\u5931\u8d25\uFF08HTTP {response.status_code}\uFF09\uff0c\u8bf7\u68c0\u67e5 API Token" ) try: payload = response.json() except ValueError as exc: raise MoviePilotResponseError( f"MoviePilot 返回了无法解析的 JSON(HTTP {response.status_code})" ) from exc message = _response_message(payload) success = _response_success(payload) if response.status_code >= 400: if response.status_code == 429: raise MoviePilotRateLimitError( response.status_code, message or "MoviePilot \u8bf7\u6c42\u8fc7\u4e8e\u9891\u7e41\uff0c\u8bf7\u7a0d\u540e\u91cd\u8bd5", payload, ) raise MoviePilotAPIError( response.status_code, message or f"MoviePilot 请求失败(HTTP {response.status_code})", payload, ) if success is False: raise MoviePilotAPIError( response.status_code, message or "MoviePilot 操作失败", payload, ) data = payload.get("data") if isinstance(payload, Mapping) else payload return MoviePilotResponse( status_code=response.status_code, data=data, success=success, message=message, ) async def _sleep_before_retry( self, attempt: int, response: httpx.Response | None = None ) -> None: retry_after = response.headers.get("Retry-After") if response else None try: delay = float(retry_after) if retry_after else self._retry_backoff * (2**attempt) except ValueError: delay = self._retry_backoff * (2**attempt) import asyncio await asyncio.sleep(min(max(delay, 0.0), 10.0)) def diagnostics(self) -> dict[str, str]: """Return safe connection diagnostics without exposing the token.""" return { "base_url": self.base_url, "token": "\u5df2\u914d\u7f6e" if self._api_token else "\u672a\u914d\u7f6e", "timeout_seconds": str(self._timeout.read), "retries": str(self._retries), } async def get( self, path: str, *, params: Mapping[str, Any] | None = None, ) -> MoviePilotResponse: return await self.request("GET", path, params=params) async def post( self, path: str, *, params: Mapping[str, Any] | None = None, json: Any = None, ) -> MoviePilotResponse: return await self.request("POST", path, params=params, json=json) async def put( self, path: str, *, params: Mapping[str, Any] | None = None, json: Any = None, ) -> MoviePilotResponse: return await self.request("PUT", path, params=params, json=json) async def delete( self, path: str, *, params: Mapping[str, Any] | None = None, ) -> MoviePilotResponse: return await self.request("DELETE", path, params=params) async def test_connection(self) -> MoviePilotResponse: """Call a low-cost endpoint to validate URL and token.""" return await self.get("/api/v1/subscribe/list")