feat: add async MoviePilot REST client
这个提交存在于:
父节点
fcc72ba3d0
当前提交
d3d0327eaa
共有 2 个文件被更改,包括 304 次插入 和 0 次删除
205
moviepilot_client.py
普通文件
205
moviepilot_client.py
普通文件
|
|
@ -0,0 +1,205 @@
|
|||
"""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."""
|
||||
|
||||
|
||||
@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,
|
||||
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._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}"
|
||||
try:
|
||||
response = await self._client.request(
|
||||
method,
|
||||
request_path,
|
||||
params=params,
|
||||
json=json,
|
||||
)
|
||||
except httpx.TimeoutException as exc:
|
||||
raise MoviePilotConnectionError("连接 MoviePilot 超时") from exc
|
||||
except httpx.HTTPError as exc:
|
||||
raise MoviePilotConnectionError("连接 MoviePilot 失败") from exc
|
||||
|
||||
if response.status_code in (401, 403):
|
||||
raise MoviePilotAuthenticationError("MoviePilot 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:
|
||||
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 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")
|
||||
99
tests/test_moviepilot_client.py
普通文件
99
tests/test_moviepilot_client.py
普通文件
|
|
@ -0,0 +1,99 @@
|
|||
import httpx
|
||||
import pytest
|
||||
|
||||
from moviepilot_client import (
|
||||
MoviePilotAPIError,
|
||||
MoviePilotAuthenticationError,
|
||||
MoviePilotClient,
|
||||
MoviePilotConfigError,
|
||||
MoviePilotConnectionError,
|
||||
MoviePilotResponseError,
|
||||
)
|
||||
|
||||
|
||||
def make_transport(handler):
|
||||
return httpx.MockTransport(handler)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_request_adds_api_header_and_unwraps_data() -> None:
|
||||
async def handler(request: httpx.Request) -> httpx.Response:
|
||||
assert request.headers["X-API-KEY"] == "secret"
|
||||
assert request.url.path == "/api/v1/media/search"
|
||||
assert request.url.params["title"] == "沙丘"
|
||||
return httpx.Response(200, json={"success": True, "data": [{"id": 1}]})
|
||||
|
||||
async with MoviePilotClient(
|
||||
"http://moviepilot:3000/", "secret", transport=make_transport(handler)
|
||||
) as client:
|
||||
response = await client.get(
|
||||
"/api/v1/media/search", params={"title": "沙丘"}
|
||||
)
|
||||
|
||||
assert response.data == [{"id": 1}]
|
||||
assert response.success is True
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_list_response_is_preserved() -> None:
|
||||
async def handler(request: httpx.Request) -> httpx.Response:
|
||||
return httpx.Response(200, json=[{"id": 1}])
|
||||
|
||||
async with MoviePilotClient(
|
||||
"http://moviepilot:3000", "secret", transport=make_transport(handler)
|
||||
) as client:
|
||||
response = await client.get("/api/v1/subscribe/list")
|
||||
|
||||
assert response.data == [{"id": 1}]
|
||||
assert response.success is None
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_api_failure_and_auth_failure_are_normalized() -> None:
|
||||
async def api_error(request: httpx.Request) -> httpx.Response:
|
||||
return httpx.Response(400, json={"success": False, "message": "参数错误"})
|
||||
|
||||
async with MoviePilotClient(
|
||||
"http://moviepilot:3000", "secret", transport=make_transport(api_error)
|
||||
) as client:
|
||||
with pytest.raises(MoviePilotAPIError, match="参数错误"):
|
||||
await client.get("/api/v1/media/search")
|
||||
|
||||
async def auth_error(request: httpx.Request) -> httpx.Response:
|
||||
return httpx.Response(401, json={"detail": "Unauthorized"})
|
||||
|
||||
async with MoviePilotClient(
|
||||
"http://moviepilot:3000", "secret", transport=make_transport(auth_error)
|
||||
) as client:
|
||||
with pytest.raises(MoviePilotAuthenticationError):
|
||||
await client.get("/api/v1/media/search")
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_connection_and_json_errors_are_normalized() -> None:
|
||||
async def invalid_json(request: httpx.Request) -> httpx.Response:
|
||||
return httpx.Response(200, content=b"not-json")
|
||||
|
||||
async with MoviePilotClient(
|
||||
"http://moviepilot:3000", "secret", transport=make_transport(invalid_json)
|
||||
) as client:
|
||||
with pytest.raises(MoviePilotResponseError):
|
||||
await client.get("/api/v1/media/search")
|
||||
|
||||
async def network_error(request: httpx.Request) -> httpx.Response:
|
||||
raise httpx.ConnectError("offline", request=request)
|
||||
|
||||
async with MoviePilotClient(
|
||||
"http://moviepilot:3000", "secret", transport=make_transport(network_error)
|
||||
) as client:
|
||||
with pytest.raises(MoviePilotConnectionError):
|
||||
await client.get("/api/v1/media/search")
|
||||
|
||||
|
||||
def test_invalid_configuration_is_rejected() -> None:
|
||||
with pytest.raises(MoviePilotConfigError):
|
||||
MoviePilotClient("", "secret")
|
||||
with pytest.raises(MoviePilotConfigError):
|
||||
MoviePilotClient("http://moviepilot:3000", "")
|
||||
with pytest.raises(MoviePilotConfigError):
|
||||
MoviePilotClient("moviepilot:3000", "secret")
|
||||
正在加载…
添加表格
在新工单中引用