redfox-python-sdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

redfox/__init__.py

@@ -1,7 +1,13 @@
 """RedFox Python SDK - 红狐数据平台 Python 客户端"""
 
-from .client import RedFoxClient
+from .client import RedFoxClient, AsyncRedFoxClient
 from .exceptions import RedFoxAPIError, RedFoxAuthError, RedFoxRateLimitError
 
-__version__ = "0.2.0"
-__all__ = ["RedFoxClient", "RedFoxAPIError", "RedFoxAuthError", "RedFoxRateLimitError"]
+__version__ = "0.2.2"
+__all__ = [
+    "RedFoxClient",
+    "AsyncRedFoxClient",
+    "RedFoxAPIError",
+    "RedFoxAuthError",
+    "RedFoxRateLimitError",
+]

redfox/client.py

@@ -1,9 +1,16 @@
-"""RedFox SDK 核心客户端"""
+"""RedFox SDK 核心客户端 — 同步 + 异步双客户端，自动重试，零配置"""
 
-import requests
+import os
+import time
+import random
+import logging
 from typing import Optional, Dict, Any
 
+import httpx
+
 from .exceptions import RedFoxAPIError, RedFoxAuthError, RedFoxRateLimitError
+
+# 导入端点（同步和异步共享同一套端点类）
 from .endpoints.douyin import DouyinAPI
 from .endpoints.xiaohongshu import XiaohongshuAPI
 from .endpoints.wechat import WechatAPI
@@ -15,16 +22,102 @@ from .endpoints.doubao_image import DoubaoImageAPI
 from .endpoints.doubao_video import DoubaoVideoAPI
 from .endpoints.ai_search import AISearchAPI
 
+logger = logging.getLogger("redfox")
+
+# 可重试的 HTTP 状态码
+RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+
+# 可重试的网络异常
+RETRYABLE_EXCEPTIONS = (
+    httpx.TimeoutException,
+    httpx.ConnectError,
+    httpx.RemoteProtocolError,
+    httpx.NetworkError,
+)
+
+
+def _compute_delay(attempt: int, backoff_factor: float = 0.5) -> float:
+    """计算指数退避延迟（含随机抖动）"""
+    base = backoff_factor * (2 ** attempt)
+    jitter = base * random.uniform(0.5, 1.5)
+    return min(jitter, 30.0)  # 上限 30 秒
+
+
+def _should_retry(status_code: int, exception: Optional[Exception] = None) -> bool:
+    """判断是否应该重试"""
+    if exception is not None:
+        return isinstance(exception, RETRYABLE_EXCEPTIONS)
+    return status_code in RETRYABLE_STATUSES
+
+
+class _RequestMixin:
+    """HTTP 请求 + 重试 + 响应处理的共享逻辑"""
+
+    def _prepare_request(
+        self, method: str, path: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> tuple:
+        """准备请求 URL 和清洗后的参数"""
+        url = f"{self.base_url}{path}"
+        if data:
+            data = {k: v for k, v in data.items() if v is not None}
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        return url, params, data
+
+    def _handle_response(self, response) -> dict:
+        """处理 API 响应，提取 data 或抛出结构化异常"""
+        if response.status_code == 401:
+            raise RedFoxAuthError(
+                "API Key 无效或缺失，请在 https://redfox.hk/settings/api-keys?source=github 获取",
+                code=401,
+            )
+        if response.status_code == 429:
+            raise RedFoxRateLimitError("请求频率超限，请稍后重试", code=429)
+        if response.status_code >= 500:
+            raise RedFoxAPIError("服务端错误", code=response.status_code)
+
+        try:
+            result = response.json()
+        except ValueError:
+            raise RedFoxAPIError(f"响应解析失败: {response.text[:200]}")
+
+        code = result.get("code")
+        if code and code != 2000:
+            msg = result.get("msg", "未知错误")
+            if code == 401 or code == 4001:
+                raise RedFoxAuthError(
+                    f"{msg}，请在 https://redfox.hk/settings/api-keys?source=github 获取有效的 API Key",
+                    code=code,
+                    response=result,
+                )
+            raise RedFoxAPIError(msg, code=code, response=result)
+
+        return result.get("data", result)
+
+    def _map_exception(self, exc: Exception) -> RedFoxAPIError:
+        """将网络异常映射为 RedFoxAPIError"""
+        if isinstance(exc, httpx.TimeoutException):
+            return RedFoxAPIError("请求超时，请稍后重试")
+        if isinstance(exc, (httpx.ConnectError, httpx.NetworkError)):
+            return RedFoxAPIError("网络连接失败，请检查网络")
+        return RedFoxAPIError(f"请求异常: {str(exc)}")
+
 
-class RedFoxClient:
+class RedFoxClient(_RequestMixin):
     """
-    RedFox 红狐数据平台客户端
+    RedFox 红狐数据平台客户端（同步）
 
     使用示例::
 
         from redfox import RedFoxClient
 
-        client = RedFoxClient(api_key="your_api_key")
+        # 零配置：自动从环境变量 REDFOX_API_KEY 读取
+        client = RedFoxClient()
+
+        # 或显式传入
+        client = RedFoxClient(api_key="ak_xxx")
 
         # 搜索抖音作品
         result = client.douyin.search_articles(keyword="AI")
@@ -32,42 +125,55 @@ class RedFoxClient:
         # 搜索小红书作品
         result = client.xiaohongshu.search_articles(keyword="AI")
 
-        # 搜索公众号文章
-        result = client.wechat.search_articles(keyword="AI")
-
         # AI 搜索
         task = client.ai_search.kimi_submit(inquiry_text="夏日茶饮推荐")
 
-    :param api_key: RedFox API Key，在 https://redfox.hk/settings/api-keys?source=github 获取
+    :param api_key: RedFox API Key。不传则从环境变量 ``REDFOX_API_KEY`` 读取
     :param base_url: API 基础地址，默认 https://redfox.hk
-    :param timeout: 请求超时时间（秒），默认 30
+    :param timeout: 请求超时（秒），默认 30
+    :param max_retries: 最大重试次数（指数退避），默认 3
+    :param backoff_factor: 退避基础因子，默认 0.5
     """
 
     DEFAULT_BASE_URL = "https://redfox.hk"
     DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BACKOFF_FACTOR = 0.5
 
     def __init__(
         self,
-        api_key: str,
+        api_key: Optional[str] = None,
         base_url: str = DEFAULT_BASE_URL,
         timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
     ):
+        # 零配置：未传 api_key 时从环境变量读取
+        if api_key is None:
+            api_key = os.getenv("REDFOX_API_KEY", "")
+
         if not api_key:
             raise ValueError(
-                "api_key 不能为空，请在 https://redfox.hk/settings/api-keys?source=github 获取"
+                "api_key 不能为空。请设置环境变量 REDFOX_API_KEY，"
+                "或传入 api_key 参数。"
+                "获取地址: https://redfox.hk/settings/api-keys?source=github"
             )
 
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
 
-        self._session = requests.Session()
-        self._session.headers.update({
-            "Content-Type": "application/json",
-            "REDFOX_API_KEY": self.api_key,
-        })
+        self._client = httpx.Client(
+            timeout=httpx.Timeout(timeout),
+            headers={
+                "Content-Type": "application/json",
+                "REDFOX_API_KEY": self.api_key,
+            },
+        )
 
-        # 初始化各平台 API 模块
+        # 初始化各平台 API 模块（端点类与异步客户端共享）
         self.douyin = DouyinAPI(self)
         self.xiaohongshu = XiaohongshuAPI(self)
         self.wechat = WechatAPI(self)
@@ -87,39 +193,57 @@ class RedFoxClient:
         data: Optional[Dict[str, Any]] = None,
     ) -> dict:
         """
-        发送 API 请求
+        发送 API 请求（含自动重试 + 指数退避）
 
         :param method: HTTP 方法（GET/POST）
         :param path: API 路径
         :param params: URL 查询参数
         :param data: 请求体 JSON 数据
         :return: API 响应 data 字段内容
-        :raises RedFoxAPIError: API 返回错误时抛出
+        :raises RedFoxAPIError: 重试耗尽后仍失败时抛出
         """
-        url = f"{self.base_url}{path}"
+        url, params, data = self._prepare_request(method, path, params, data)
+        last_exception = None
 
-        # 过滤掉值为 None 的参数
-        if data:
-            data = {k: v for k, v in data.items() if v is not None}
-        if params:
-            params = {k: v for k, v in params.items() if v is not None}
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=data,
+                )
 
-        try:
-            response = self._session.request(
-                method=method,
-                url=url,
-                params=params,
-                json=data,
-                timeout=self.timeout,
-            )
-        except requests.exceptions.Timeout:
-            raise RedFoxAPIError("请求超时，请稍后重试")
-        except requests.exceptions.ConnectionError:
-            raise RedFoxAPIError("网络连接失败，请检查网络")
-        except requests.exceptions.RequestException as e:
-            raise RedFoxAPIError(f"请求异常: {str(e)}")
+                # 需要重试的 HTTP 状态码
+                if response.status_code in RETRYABLE_STATUSES and attempt < self.max_retries:
+                    delay = _compute_delay(attempt, self.backoff_factor)
+                    logger.debug(
+                        "收到 %d，第 %d/%d 次重试，等待 %.1fs",
+                        response.status_code, attempt + 1, self.max_retries, delay,
+                    )
+                    time.sleep(delay)
+                    continue
+
+                return self._handle_response(response)
+
+            except RETRYABLE_EXCEPTIONS as exc:
+                last_exception = exc
+                if attempt < self.max_retries:
+                    delay = _compute_delay(attempt, self.backoff_factor)
+                    logger.debug(
+                        "网络异常 %s，第 %d/%d 次重试，等待 %.1fs",
+                        type(exc).__name__, attempt + 1, self.max_retries, delay,
+                    )
+                    time.sleep(delay)
+                else:
+                    raise self._map_exception(exc)
+
+            except (RedFoxAPIError, RedFoxAuthError, RedFoxRateLimitError):
+                # 业务异常不重试，直接抛出
+                raise
 
-        return self._handle_response(response)
+        # 重试耗尽
+        raise self._map_exception(last_exception) if last_exception else RedFoxAPIError("请求失败")
 
     def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> dict:
         """发送 POST 请求"""
@@ -129,34 +253,165 @@ class RedFoxClient:
         """发送 GET 请求"""
         return self.request("GET", path, params=params)
 
-    def _handle_response(self, response: requests.Response) -> dict:
-        """处理 API 响应"""
-        # HTTP 级别错误
-        if response.status_code == 401:
-            raise RedFoxAuthError(
-                "API Key 无效或缺失，请在 https://redfox.hk/settings/api-keys?source=github 获取",
-                code=401,
+    def close(self):
+        """关闭 HTTP 连接"""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class AsyncRedFoxClient(_RequestMixin):
+    """
+    RedFox 红狐数据平台客户端（异步）
+
+    使用示例::
+
+        import asyncio
+        from redfox import AsyncRedFoxClient
+
+        async def main():
+            async with AsyncRedFoxClient() as client:
+                # 所有 API 调用与同步客户端完全一致，只需 await
+                result = await client.douyin.search_articles(keyword="AI")
+                print(result)
+
+        asyncio.run(main())
+
+    :param api_key: RedFox API Key。不传则从环境变量 ``REDFOX_API_KEY`` 读取
+    :param base_url: API 基础地址，默认 https://redfox.hk
+    :param timeout: 请求超时（秒），默认 30
+    :param max_retries: 最大重试次数（指数退避），默认 3
+    :param backoff_factor: 退避基础因子，默认 0.5
+    """
+
+    DEFAULT_BASE_URL = "https://redfox.hk"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BACKOFF_FACTOR = 0.5
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
+    ):
+        if api_key is None:
+            api_key = os.getenv("REDFOX_API_KEY", "")
+
+        if not api_key:
+            raise ValueError(
+                "api_key 不能为空。请设置环境变量 REDFOX_API_KEY，"
+                "或传入 api_key 参数。"
+                "获取地址: https://redfox.hk/settings/api-keys?source=github"
             )
-        if response.status_code == 429:
-            raise RedFoxRateLimitError("请求频率超限，请稍后重试", code=429)
-        if response.status_code >= 500:
-            raise RedFoxAPIError(f"服务端错误", code=response.status_code)
 
-        try:
-            result = response.json()
-        except ValueError:
-            raise RedFoxAPIError(f"响应解析失败: {response.text[:200]}")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
 
-        # 业务级别错误
-        code = result.get("code")
-        if code and code != 2000:
-            msg = result.get("msg", "未知错误")
-            if code == 401 or code == 4001:
-                raise RedFoxAuthError(
-                    f"{msg}，请在 https://redfox.hk/settings/api-keys?source=github 获取有效的 API Key",
-                    code=code,
-                    response=result,
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout),
+            headers={
+                "Content-Type": "application/json",
+                "REDFOX_API_KEY": self.api_key,
+            },
+        )
+
+        # 初始化各平台 API 模块（与同步客户端共享同一套端点类）
+        self.douyin = DouyinAPI(self)
+        self.xiaohongshu = XiaohongshuAPI(self)
+        self.wechat = WechatAPI(self)
+        self.bilibili = BilibiliAPI(self)
+        self.toutiao = ToutiaoAPI(self)
+        self.tiktok = TikTokAPI(self)
+        self.gpt_image = GPTImageAPI(self)
+        self.doubao_image = DoubaoImageAPI(self)
+        self.doubao_video = DoubaoVideoAPI(self)
+        self.ai_search = AISearchAPI(self)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> dict:
+        """
+        异步发送 API 请求（含自动重试 + 指数退避）
+
+        :param method: HTTP 方法（GET/POST）
+        :param path: API 路径
+        :param params: URL 查询参数
+        :param data: 请求体 JSON 数据
+        :return: API 响应 data 字段内容
+        """
+        url, params, data = self._prepare_request(method, path, params, data)
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=data,
                 )
-            raise RedFoxAPIError(msg, code=code, response=result)
 
-        return result.get("data", result)
+                if response.status_code in RETRYABLE_STATUSES and attempt < self.max_retries:
+                    delay = _compute_delay(attempt, self.backoff_factor)
+                    logger.debug(
+                        "收到 %d，第 %d/%d 次重试，等待 %.1fs",
+                        response.status_code, attempt + 1, self.max_retries, delay,
+                    )
+                    await self._async_sleep(delay)
+                    continue
+
+                return self._handle_response(response)
+
+            except RETRYABLE_EXCEPTIONS as exc:
+                last_exception = exc
+                if attempt < self.max_retries:
+                    delay = _compute_delay(attempt, self.backoff_factor)
+                    logger.debug(
+                        "网络异常 %s，第 %d/%d 次重试，等待 %.1fs",
+                        type(exc).__name__, attempt + 1, self.max_retries, delay,
+                    )
+                    await self._async_sleep(delay)
+                else:
+                    raise self._map_exception(exc)
+
+            except (RedFoxAPIError, RedFoxAuthError, RedFoxRateLimitError):
+                raise
+
+        raise self._map_exception(last_exception) if last_exception else RedFoxAPIError("请求失败")
+
+    async def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> dict:
+        """异步发送 POST 请求"""
+        return await self.request("POST", path, data=data)
+
+    async def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> dict:
+        """异步发送 GET 请求"""
+        return await self.request("GET", path, params=params)
+
+    async def _async_sleep(self, seconds: float):
+        """异步延时"""
+        import asyncio
+        await asyncio.sleep(seconds)
+
+    async def close(self):
+        """关闭 HTTP 连接"""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

redfox/endpoints/bilibili.py

@@ -24,32 +24,46 @@ class BilibiliAPI:
             "/story/api/bili/data/accountDetail", data={"mid": mid}
         )
 
-    def get_work(self, bvid: str) -> dict:
+    def get_work(
+        self,
+        bvid: str = None,
+        work_url: str = None,
+    ) -> dict:
         """
         获取哔哩哔哩作品内容详情（优质库）
 
-        :param bvid: 作品 BV ID
+        bvid 和 work_url 至少传一个。
+
+        :param bvid: 作品 BV 号
+        :param work_url: 作品链接，支持 bilibili.com/video/BV1xxx 或 b23.tv 格式
         :return: 作品详情字典
         """
-        return self._client.post(
-            "/story/api/bili/data/workDetail", data={"bvid": bvid}
-        )
+        data: Dict[str, Any] = {}
+        if bvid:
+            data["bvId"] = bvid
+        if work_url:
+            data["workUrl"] = work_url
+        return self._client.post("/story/api/bili/data/workDetail", data=data)
 
     def search_users(
         self,
         keyword: str,
-        page_num: int = 1,
+        page: int = 1,
+        page_size: int = None,
         order: str = None,
     ) -> dict:
         """
         搜索关键词获取哔哩哔哩账号（优质库）
 
         :param keyword: 搜索关键词（必填）
-        :param page_num: 页码，默认 1
-        :param order: 排序方式
+        :param page: 页码，从 1 开始（必填）
+        :param page_size: 每页条数，默认 10，最大 50
+        :param order: 排序：follower=粉丝数 / like=获赞数，默认相关性
         :return: 搜索结果字典
         """
-        data: Dict[str, Any] = {"keyword": keyword, "page": str(page_num)}
+        data: Dict[str, Any] = {"keyword": keyword, "page": str(page)}
+        if page_size is not None:
+            data["pageSize"] = page_size
         if order is not None:
             data["order"] = order
         return self._client.post("/story/api/bili/data/accountSearch", data=data)
@@ -57,39 +71,53 @@ class BilibiliAPI:
     def search_articles(
         self,
         keyword: str,
-        page_num: int = 1,
+        page: int = 1,
+        page_size: int = None,
         order: str = None,
     ) -> dict:
         """
         搜索关键词获取哔哩哔哩作品（优质库）
 
         :param keyword: 搜索关键词（必填）
-        :param page_num: 页码，默认 1
-        :param order: 排序方式
+        :param page: 页码，从 1 开始（必填）
+        :param page_size: 每页条数，默认 10，最大 50
+        :param order: 排序：time=发布时间 / play=播放数 / like=点赞数 / comment=评论数 / favorite=收藏数，默认 time
         :return: 搜索结果字典
         """
-        data: Dict[str, Any] = {"keyword": keyword, "page": str(page_num)}
+        data: Dict[str, Any] = {"keyword": keyword, "page": str(page)}
+        if page_size is not None:
+            data["pageSize"] = page_size
         if order is not None:
             data["order"] = order
         return self._client.post("/story/api/bili/data/workSearch", data=data)
 
     def get_user_works(
         self,
-        mid: str,
-        page_num: int = 1,
-        page_size: int = 30,
+        mid: str = None,
+        account_url: str = None,
+        page: int = 1,
+        page_size: int = None,
+        order: str = None,
     ) -> dict:
         """
         获取哔哩哔哩账号作品列表（优质库）
 
-        :param mid: 账号 MID（必填）
-        :param page_num: 页码，默认 1
-        :param page_size: 每页条数，默认 30
+        mid 和 account_url 至少传一个。
+
+        :param mid: 账号 MID
+        :param account_url: 主页链接，如 https://space.bilibili.com/946974
+        :param page: 页码，默认 1
+        :param page_size: 每页条数，默认 10，最大 50
+        :param order: 排序：time=发布时间 / play=播放数 / like=点赞数，默认 time
         :return: 作品列表字典
         """
-        data: Dict[str, Any] = {
-            "mid": mid,
-            "page": str(page_num),
-            "pageSize": str(page_size),
-        }
+        data: Dict[str, Any] = {"page": str(page)}
+        if mid:
+            data["mid"] = mid
+        if account_url:
+            data["accountUrl"] = account_url
+        if page_size is not None:
+            data["pageSize"] = page_size
+        if order is not None:
+            data["order"] = order
         return self._client.post("/story/api/bili/data/accountWorkList", data=data)