redfox-python-sdk 0.1.0__py3-none-any.whl

redfox/__init__.py

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

redfox/client.py

@@ -0,0 +1,138 @@
+"""RedFox SDK 核心客户端"""
+
+import requests
+from typing import Optional, Dict, Any
+
+from .exceptions import RedFoxAPIError, RedFoxAuthError, RedFoxRateLimitError
+from .endpoints.douyin import DouyinAPI
+
+
+class RedFoxClient:
+    """
+    RedFox 红狐数据平台客户端
+
+    使用示例::
+
+        from redfox import RedFoxClient
+
+        client = RedFoxClient(api_key="your_api_key")
+
+        # 搜索抖音作品
+        result = client.douyin.search_articles(keyword="AI")
+
+        # 获取账号信息
+        user = client.douyin.get_user(account_id="dy_user123")
+
+    :param api_key: RedFox API Key，在 https://redfox.hk/settings/api-keys?source=github 获取
+    :param base_url: API 基础地址，默认 https://redfox.hk
+    :param timeout: 请求超时时间（秒），默认 30
+    """
+
+    DEFAULT_BASE_URL = "https://redfox.hk"
+    DEFAULT_TIMEOUT = 30
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError(
+                "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._session = requests.Session()
+        self._session.headers.update({
+            "Content-Type": "application/json",
+            "REDFOX_API_KEY": self.api_key,
+        })
+
+        # 初始化各平台 API 模块
+        self.douyin = DouyinAPI(self)
+
+    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 字段内容
+        :raises RedFoxAPIError: API 返回错误时抛出
+        """
+        url = f"{self.base_url}{path}"
+
+        # 过滤掉值为 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}
+
+        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)}")
+
+        return self._handle_response(response)
+
+    def post(self, path: str, data: Optional[Dict[str, Any]] = None) -> dict:
+        """发送 POST 请求"""
+        return self.request("POST", path, data=data)
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> dict:
+        """发送 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,
+            )
+        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]}")
+
+        # 业务级别错误
+        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)

redfox/endpoints/__init__.py

@@ -0,0 +1 @@
+"""端点模块"""

redfox/endpoints/douyin.py

@@ -0,0 +1,164 @@
+"""抖音平台 API 端点"""
+
+from typing import Optional, Dict, Any
+
+
+class DouyinAPI:
+    """
+    抖音平台 API 集合
+
+    包含抖音作品搜索、账号查询、作品详情等接口。
+    所有接口均为 POST 请求，参数通过 JSON body 传递。
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    # ─── 作品相关 ───────────────────────────────────────────
+
+    def get_work(
+        self,
+        work_id: str = None,
+        work_url: str = None,
+    ) -> dict:
+        """
+        获取抖音作品内容详情（优质库）
+
+        通过作品 ID 或作品链接查询作品详细信息，包括互动数据、作者信息等。
+        work_id 和 work_url 至少传一个。
+
+        :param work_id: 作品 ID，如 "10000123456789"
+        :param work_url: 作品链接，如 "https://www.douyin.com/video/xxx"
+        :return: 作品详情字典
+        """
+        data = {}
+        if work_id:
+            data["workId"] = work_id
+        if work_url:
+            data["workUrl"] = work_url
+
+        return self._client.post("/story/api/dyData/queryWork", data=data)
+
+    def search_articles(
+        self,
+        keyword: str,
+        offset: int = 0,
+        sort_type: str = None,
+    ) -> dict:
+        """
+        搜索关键词获取抖音作品（优质库）
+
+        :param keyword: 搜索关键词（必填）
+        :param offset: 分页偏移量，从 0 开始，每次 +20
+        :param sort_type: 排序方式，如 "default"
+        :return: 搜索结果字典，包含 total/hasMore/list
+        """
+        data: Dict[str, Any] = {"keyword": keyword}
+        if offset is not None:
+            data["offset"] = offset
+        if sort_type is not None:
+            data["sortType"] = sort_type
+
+        return self._client.post("/story/api/dyData/searchArticle", data=data)
+
+    def get_user_works(
+        self,
+        account_id: str = None,
+        author_url: str = None,
+        sec_user_id: str = None,
+        offset: int = 0,
+        sort_type: str = None,
+    ) -> dict:
+        """
+        获取抖音账号作品列表（优质库）
+
+        account_id / author_url / sec_user_id 至少传一个。
+
+        :param account_id: 抖音号
+        :param author_url: 作者主页链接
+        :param sec_user_id: 作者 sec_user_id
+        :param offset: 偏移量，从 0 开始，每页 +20
+        :param sort_type: 排序方式：0=默认，2=最新，4=最热
+        :return: 作品列表字典，包含 total/hasMore/list
+        """
+        data: Dict[str, Any] = {}
+        if account_id:
+            data["accountId"] = account_id
+        if author_url:
+            data["authorUrl"] = author_url
+        if sec_user_id:
+            data["secUserId"] = sec_user_id
+        if offset is not None:
+            data["offset"] = offset
+        if sort_type is not None:
+            data["sortType"] = sort_type
+
+        return self._client.post("/story/api/dyData/queryWorkList", data=data)
+
+    # ─── 账号相关 ───────────────────────────────────────────
+
+    def get_user(self, account_id: str) -> dict:
+        """
+        获取抖音账号信息（优质库）
+
+        :param account_id: 抖音账号 ID（支持 unique_id、short_id、uid 任一匹配）
+        :return: 账号信息字典
+        """
+        return self._client.post(
+            "/story/api/dyData/queryUser",
+            data={"accountId": account_id},
+        )
+
+    def search_users(
+        self,
+        keyword: str,
+        offset: int = 0,
+        sort_type: str = None,
+    ) -> dict:
+        """
+        搜索关键词获取抖音账号（优质库）
+
+        :param keyword: 搜索关键词（必填）
+        :param offset: 分页偏移量，从 0 开始
+        :param sort_type: 排序方式
+        :return: 搜索结果字典，包含 total/hasMore/list
+        """
+        data: Dict[str, Any] = {"keyword": keyword}
+        if offset is not None:
+            data["offset"] = offset
+        if sort_type is not None:
+            data["sortType"] = sort_type
+
+        return self._client.post("/story/api/dyData/searchUser", data=data)
+
+    # ─── AI 作品 ────────────────────────────────────────────
+
+    def search_ai_articles(
+        self,
+        keyword: str,
+        page_num: int = 1,
+        page_size: int = 20,
+        start_time: str = None,
+        end_time: str = None,
+    ) -> dict:
+        """
+        搜索关键词获取抖音 AI 作品（优质库）
+
+        :param keyword: 搜索关键词（必填）
+        :param page_num: 页码，默认 1
+        :param page_size: 每页条数，默认 20
+        :param start_time: 开始时间，格式 "2026-06-01 00:00:00"
+        :param end_time: 结束时间，格式 "2026-06-02 00:00:00"
+        :return: 搜索结果字典，包含 total/pageNum/pageSize/pages/list
+        """
+        data: Dict[str, Any] = {
+            "keyword": keyword,
+            "pageNum": page_num,
+            "pageSize": page_size,
+        }
+        if start_time is not None:
+            data["startTime"] = start_time
+        if end_time is not None:
+            data["endTime"] = end_time
+
+        return self._client.post("/story/api/parseWork/queryDyAiMsgs", data=data)

redfox/exceptions.py

@@ -0,0 +1,26 @@
+"""RedFox SDK 自定义异常"""
+
+
+class RedFoxAPIError(Exception):
+    """RedFox API 调用异常基类"""
+
+    def __init__(self, message: str, code: int = None, response: dict = None):
+        self.message = message
+        self.code = code
+        self.response = response
+        super().__init__(self.message)
+
+    def __str__(self):
+        if self.code:
+            return f"RedFoxAPIError(code={self.code}): {self.message}"
+        return f"RedFoxAPIError: {self.message}"
+
+
+class RedFoxAuthError(RedFoxAPIError):
+    """鉴权失败（API Key 无效或缺失）"""
+    pass
+
+
+class RedFoxRateLimitError(RedFoxAPIError):
+    """请求频率超限"""
+    pass

redfox_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.1
+Name: redfox-python-sdk
+Version: 0.1.0
+Summary: RedFox 红狐数据平台 Python SDK
+Home-page: https://redfox.hk
+Author: RedFox
+Author-email: dev@redfox.hk
+License: UNKNOWN
+Platform: UNKNOWN
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests (>=2.25.0)
+
+# RedFox Python SDK
+
+红狐数据平台 Python SDK，支持通过简洁的 Python 接口调用红狐平台所有数据 API。
+
+## 安装
+
+```bash
+pip install redfox-sdk
+```
+
+## 快速开始
+
+```python
+from redfox import RedFoxClient
+
+client = RedFoxClient(api_key="your_api_key")
+
+# 搜索抖音作品
+result = client.douyin.search_articles(keyword="人工智能")
+for item in result["list"]:
+    print(f"{item['title']} - 点赞: {item['likeCount']}")
+```
+
+## 获取 API Key
+
+前往 [API Keys 页面](https://redfox.hk/settings/api-keys?source=github) 获取。
+
+## License
+
+MIT
+
+

redfox_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+redfox/__init__.py,sha256=IDMBABFLRl6UV3BuvLLVH7mmJOSCwJZuk2uOAocrXwI,285
+redfox/client.py,sha256=HAatJMY-hc_kKF3NNhKWMX9Q2J0SDQBmO_QUiStY6N8,4589
+redfox/exceptions.py,sha256=QWosa7FXJbxNPenMx1CRIPj7z8SFmmtg2_8Qjzika1E,668
+redfox/endpoints/__init__.py,sha256=sjtHfb6bkX_wdd_ryRajkPrBRnno2HMiwys0DcNIqSA,19
+redfox/endpoints/douyin.py,sha256=ND2iECy5EFNlx8HbB4Fom_H6djFQOMpzaPoao3RZb-Y,5506
+redfox_python_sdk-0.1.0.dist-info/METADATA,sha256=qXRQwCN8VFXCkKDOhl7J4HGwyj_Xu9cabYNQEN3aBHg,1081
+redfox_python_sdk-0.1.0.dist-info/WHEEL,sha256=ewwEueio1C2XeHTvT17n8dZUJgOvyCWCt0WVNLClP9o,92
+redfox_python_sdk-0.1.0.dist-info/top_level.txt,sha256=cOIfFv-M-TaEjpiRQy-OygdvvuHeZrlQSoRWMj0DaEM,7
+redfox_python_sdk-0.1.0.dist-info/RECORD,,

redfox_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.37.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

redfox_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+redfox