omnidoc 0.1.0__tar.gz

omnidoc-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: omnidoc
+Version: 0.1.0
+Summary: OmniDoc 开放 API 的 Python 客户端：上传、翻译、下载、积分查询与 Webhook 验签
+Project-URL: Homepage, https://omnidoc.top/
+Project-URL: Documentation, https://docs.omnidoc.top/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# omnidoc（Python）
+
+OmniDoc 开放 API 的 Python 客户端：上传文件、创建翻译任务、等待结果、下载产物，并提供积分查询和 Webhook 验签。接口说明见 <https://docs.omnidoc.top/>。
+
+## 安装
+
+发布到 PyPI 之前，可以从源码安装：
+
+```bash
+pip install ./libs/omnidoc-python
+```
+
+发布后使用 `pip install omnidoc`。
+
+依赖只有 `requests`，需要 Python 3.9 或更新版本。
+
+## 快速开始
+
+在环境变量里设置 API Key（以 `sk_` 开头，在 API 中心创建）：
+
+```bash
+export OMNIDOC_API_KEY="sk_your_key"
+```
+
+```python
+from omnidoc import OmniDocClient
+
+client = OmniDocClient()  # 读取 OMNIDOC_API_KEY
+files = client.translate_file("report.docx", "en", output_dir="out")
+print(files)
+```
+
+`translate_file` 会依次完成：上传（presign → 直传 → finalize）、创建翻译任务、轮询直到结束、下载全部产物。任务失败时抛出 `JobFailedError`，`quota_exceeded` 为 True 表示余额不足，未扣费。
+
+## 分步调用
+
+```python
+doc_id = client.upload("report.docx")
+job = client.create_job(doc_id, "en", output_mode="bilingual", engine="xr-397b")
+job = client.wait_job(job["id"], poll_interval=3, timeout=1800)
+for artifact in client.list_artifacts(job["id"]):
+    client.download_artifact(artifact["id"], "out", fallback_name=f"{artifact['id']}.{artifact.get('format', 'bin')}")
+```
+
+`create_job` 每次调用会生成新的 `Idempotency-Key`；内部重试沿用同一个键，不会重复创建或扣费。需要自己重试同一次提交时，传入相同的 `idempotency_key`。
+
+## 查询与其他接口
+
+```python
+client.get_job(job_id)           # 任务状态（不扣积分）
+client.cancel_job(job_id)        # 取消任务
+client.credit_balance()          # 积分余额（不扣积分）
+client.credit_operations()       # 积分流水
+client.usage_summary()           # 用量汇总
+
+# 尚未封装的接口，按 docs.omnidoc.top 上的路径直接调用：
+client.get_json("<路径>", params={...})
+client.post_json("<路径>", json={...})
+```
+
+## 错误与重试
+
+- API 错误统一抛出 `OmniDocError`，带有 `status_code`、`code`、`message` 与 `request_id`（对应响应头 `X-Request-Id`）。
+- 429 与 5xx 会按 `Retry-After` 或指数退避重试，最多 `max_retries` 次（默认 4）。
+- `AUTH_API_KEY_QUOTA_EXCEEDED` 不重试：该 Key 的预算已用尽，需要先调高预算。
+
+## Webhook 验签
+
+```python
+from omnidoc import parse_webhook
+
+event = parse_webhook(raw_body, request.headers["X-Webhook-Signature"], secret)
+```
+
+必须使用收到的原始请求体字节验签。签名或时间戳不符时抛出 `ValueError`。接收端还应按 `data.job_id` 与 `data.status` 去重。
+
+## 安全
+
+- Key 只在服务端或受控环境保存，不要写进源码、日志或公开仓库。
+- Key 只发送给 API 地址，不会发送给直传的 `upload_url`。
+
+## 开发
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+测试使用假的 HTTP 会话，不需要 API Key，也不会访问网络。

omnidoc-0.1.0/README.md

@@ -0,0 +1,89 @@
+# omnidoc（Python）
+
+OmniDoc 开放 API 的 Python 客户端：上传文件、创建翻译任务、等待结果、下载产物，并提供积分查询和 Webhook 验签。接口说明见 <https://docs.omnidoc.top/>。
+
+## 安装
+
+发布到 PyPI 之前，可以从源码安装：
+
+```bash
+pip install ./libs/omnidoc-python
+```
+
+发布后使用 `pip install omnidoc`。
+
+依赖只有 `requests`，需要 Python 3.9 或更新版本。
+
+## 快速开始
+
+在环境变量里设置 API Key（以 `sk_` 开头，在 API 中心创建）：
+
+```bash
+export OMNIDOC_API_KEY="sk_your_key"
+```
+
+```python
+from omnidoc import OmniDocClient
+
+client = OmniDocClient()  # 读取 OMNIDOC_API_KEY
+files = client.translate_file("report.docx", "en", output_dir="out")
+print(files)
+```
+
+`translate_file` 会依次完成：上传（presign → 直传 → finalize）、创建翻译任务、轮询直到结束、下载全部产物。任务失败时抛出 `JobFailedError`，`quota_exceeded` 为 True 表示余额不足，未扣费。
+
+## 分步调用
+
+```python
+doc_id = client.upload("report.docx")
+job = client.create_job(doc_id, "en", output_mode="bilingual", engine="xr-397b")
+job = client.wait_job(job["id"], poll_interval=3, timeout=1800)
+for artifact in client.list_artifacts(job["id"]):
+    client.download_artifact(artifact["id"], "out", fallback_name=f"{artifact['id']}.{artifact.get('format', 'bin')}")
+```
+
+`create_job` 每次调用会生成新的 `Idempotency-Key`；内部重试沿用同一个键，不会重复创建或扣费。需要自己重试同一次提交时，传入相同的 `idempotency_key`。
+
+## 查询与其他接口
+
+```python
+client.get_job(job_id)           # 任务状态（不扣积分）
+client.cancel_job(job_id)        # 取消任务
+client.credit_balance()          # 积分余额（不扣积分）
+client.credit_operations()       # 积分流水
+client.usage_summary()           # 用量汇总
+
+# 尚未封装的接口，按 docs.omnidoc.top 上的路径直接调用：
+client.get_json("<路径>", params={...})
+client.post_json("<路径>", json={...})
+```
+
+## 错误与重试
+
+- API 错误统一抛出 `OmniDocError`，带有 `status_code`、`code`、`message` 与 `request_id`（对应响应头 `X-Request-Id`）。
+- 429 与 5xx 会按 `Retry-After` 或指数退避重试，最多 `max_retries` 次（默认 4）。
+- `AUTH_API_KEY_QUOTA_EXCEEDED` 不重试：该 Key 的预算已用尽，需要先调高预算。
+
+## Webhook 验签
+
+```python
+from omnidoc import parse_webhook
+
+event = parse_webhook(raw_body, request.headers["X-Webhook-Signature"], secret)
+```
+
+必须使用收到的原始请求体字节验签。签名或时间戳不符时抛出 `ValueError`。接收端还应按 `data.job_id` 与 `data.status` 去重。
+
+## 安全
+
+- Key 只在服务端或受控环境保存，不要写进源码、日志或公开仓库。
+- Key 只发送给 API 地址，不会发送给直传的 `upload_url`。
+
+## 开发
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+测试使用假的 HTTP 会话，不需要 API Key，也不会访问网络。

omnidoc-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "omnidoc"
+version = "0.1.0"
+description = "OmniDoc 开放 API 的 Python 客户端：上传、翻译、下载、积分查询与 Webhook 验签"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.31",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://omnidoc.top/"
+Documentation = "https://docs.omnidoc.top/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

omnidoc-0.1.0/setup.cfg

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

omnidoc-0.1.0/src/omnidoc/__init__.py

@@ -0,0 +1,16 @@
+"""OmniDoc 开放 API 的 Python 客户端。"""
+
+from .client import DEFAULT_BASE_URL, OmniDocClient
+from .errors import JobFailedError, OmniDocError
+from .webhooks import parse_webhook, verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "JobFailedError",
+    "OmniDocClient",
+    "OmniDocError",
+    "parse_webhook",
+    "verify_webhook",
+]
+
+__version__ = "0.1.0"

omnidoc-0.1.0/src/omnidoc/client.py

@@ -0,0 +1,302 @@
+"""OmniDoc 开放 API 的同步客户端。
+
+接口说明见 https://docs.omnidoc.top/ 。典型流程：
+
+    client = OmniDocClient()                      # 读取环境变量 OMNIDOC_API_KEY
+    paths = client.translate_file("report.docx", "en", output_dir="out")
+
+Key 只发送给 API 地址；直传的 upload_url 不带 Key。
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import re
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+from urllib.parse import unquote
+
+import requests
+
+from .errors import JobFailedError, OmniDocError, error_from_response
+
+DEFAULT_BASE_URL = "https://omnidoc.top/api/v1"
+TERMINAL_JOB_STATUSES = frozenset({"completed", "failed"})
+RETRYABLE_STATUSES = frozenset({429, 500, 502, 503, 504})
+QUOTA_EXCEEDED_CODE = "AUTH_API_KEY_QUOTA_EXCEEDED"
+
+PathLike = Union[str, os.PathLike]
+
+_UTF8_FILENAME = re.compile(r"filename\*=UTF-8''([^;]+)", re.IGNORECASE)
+_PLAIN_FILENAME = re.compile(r'filename="([^"]+)"', re.IGNORECASE)
+
+
+def _filename_from_disposition(disposition: str, fallback: str) -> str:
+    """从 Content-Disposition 取文件名，只保留最后一段，防止路径穿越。"""
+    match = _UTF8_FILENAME.search(disposition)
+    if match:
+        name = unquote(match.group(1))
+    else:
+        match = _PLAIN_FILENAME.search(disposition)
+        name = match.group(1) if match else fallback
+    return Path(name).name or fallback
+
+
+class OmniDocClient:
+    """OmniDoc API 客户端。
+
+    Args:
+        api_key: 以 ``sk_`` 开头的 API Key；缺省时读取环境变量 OMNIDOC_API_KEY。
+        base_url: API 根地址，默认 https://omnidoc.top/api/v1。
+        timeout: (连接超时, 读取超时) 秒数。
+        max_retries: 遇到 429 与 5xx 时的最大重试次数（不含首次请求）。
+        session: 可选的 requests.Session，便于测试或复用连接。
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: Tuple[float, float] = (10.0, 60.0),
+        max_retries: int = 4,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        key = api_key or os.environ.get("OMNIDOC_API_KEY")
+        if not key:
+            raise ValueError("需要 API Key：传入 api_key，或设置环境变量 OMNIDOC_API_KEY")
+        self._api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = session or requests.Session()
+
+    # ------------------------------------------------------------------ 底层请求
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        """发送请求，成功返回 Response，失败抛出 OmniDocError。
+
+        429 与 5xx 按 Retry-After 或指数退避重试；AUTH_API_KEY_QUOTA_EXCEEDED 不重试。
+        创建类请求重试时会沿用调用方传入的 Idempotency-Key，因此不会重复扣费。
+        """
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        attempt = 0
+        while True:
+            request_headers = {"X-API-Key": self._api_key, **(headers or {})}
+            response = self._session.request(
+                method,
+                url,
+                json=json,
+                params=params,
+                headers=request_headers,
+                timeout=self.timeout,
+                stream=stream,
+            )
+            if response.status_code < 400:
+                return response
+
+            error = error_from_response(response)
+            retryable = response.status_code in RETRYABLE_STATUSES and error.code != QUOTA_EXCEEDED_CODE
+            if not retryable or attempt >= self.max_retries:
+                raise error
+
+            time.sleep(_retry_delay(response, attempt))
+            attempt += 1
+
+    def get_json(self, path: str, **kwargs: Any) -> Any:
+        """GET 并返回解析后的 JSON；可调用文档中任何尚未封装的接口。"""
+        return self.request("GET", path, **kwargs).json()
+
+    def post_json(self, path: str, json: Any = None, **kwargs: Any) -> Any:
+        """POST 并返回解析后的 JSON。"""
+        return self.request("POST", path, json=json, **kwargs).json()
+
+    # ------------------------------------------------------------------ 上传
+
+    def upload(self, path: PathLike, *, filename: Optional[str] = None) -> str:
+        """上传本地文件并确认，返回文档 ID。
+
+        流程：申请上传地址（presign）→ 直传到 upload_url → 确认（finalize）。
+        """
+        file_path = Path(path)
+        size = file_path.stat().st_size
+        ticket = self.post_json(
+            "upload/presign",
+            json={"filename": filename or file_path.name, "file_size": size},
+        )
+
+        put_headers = {**ticket["upload_headers"], "Content-Length": str(size)}
+        with file_path.open("rb") as stream:
+            # 直传地址不带 API Key，使用模块级 requests.put。
+            uploaded = requests.put(
+                ticket["upload_url"], headers=put_headers, data=stream, timeout=300
+            )
+        uploaded.raise_for_status()
+
+        finalized = self.post_json(
+            "upload/finalize", json={"finalize_token": ticket["finalize_token"]}
+        )
+        return finalized["document"]["id"]
+
+    # ------------------------------------------------------------------ 翻译任务
+
+    def create_job(
+        self,
+        document_id: str,
+        target_lang: str,
+        *,
+        source_lang: Optional[str] = None,
+        engine: Optional[str] = None,
+        output_mode: Optional[str] = None,
+        glossary_id: Optional[str] = None,
+        include_images: Optional[bool] = None,
+        context_translation: Optional[bool] = None,
+        style_preset: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """创建文件翻译任务。
+
+        output_mode 可选 ``single`` 或 ``bilingual``。重试同一次提交时请传入相同的
+        idempotency_key；每次新的提交使用新的 UUID（缺省时自动生成）。
+        """
+        optional = {
+            "source_lang": source_lang,
+            "engine": engine,
+            "output_mode": output_mode,
+            "glossary_id": glossary_id,
+            "include_images": include_images,
+            "context_translation": context_translation,
+            "style_preset": style_preset,
+        }
+        body: Dict[str, Any] = {"document_id": document_id, "target_lang": target_lang}
+        body.update({k: v for k, v in optional.items() if v is not None})
+        key = idempotency_key or str(uuid.uuid4())
+        return self.request(
+            "POST", "jobs", json=body, headers={"Idempotency-Key": key}
+        ).json()
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """查询任务状态（不扣积分）。"""
+        return self.request("GET", f"jobs/{job_id}").json()
+
+    def cancel_job(self, job_id: str) -> Dict[str, Any]:
+        """取消任务。取消的任务不会发送 Webhook。"""
+        return self.request("POST", f"jobs/{job_id}/cancel").json()
+
+    def wait_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 3.0,
+        timeout: float = 1800.0,
+    ) -> Dict[str, Any]:
+        """轮询直到任务 completed 或 failed，返回最终任务信息。
+
+        生产环境建议改用 Webhook 或 SSE，不要长时间轮询。
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job.get("status") in TERMINAL_JOB_STATUSES:
+                return job
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"任务 {job_id} 在 {timeout:.0f} 秒内没有结束")
+            time.sleep(poll_interval)
+
+    # ------------------------------------------------------------------ 产物
+
+    def list_artifacts(self, job_id: str) -> List[Dict[str, Any]]:
+        """列出任务的产物（不扣积分）。"""
+        return self.request("GET", "artifacts", params={"job_id": job_id}).json()
+
+    def download_artifact(
+        self,
+        artifact_id: str,
+        output_dir: PathLike = ".",
+        *,
+        fallback_name: Optional[str] = None,
+    ) -> Path:
+        """下载产物到 output_dir，文件名取自响应头，取不到时用 fallback_name。"""
+        response = self.request(
+            "GET", f"artifacts/{artifact_id}/download", stream=True
+        )
+        fallback = fallback_name or artifact_id
+        name = _filename_from_disposition(
+            response.headers.get("Content-Disposition", ""), fallback
+        )
+        target = Path(output_dir) / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("wb") as handle:
+            for chunk in response.iter_content(chunk_size=64 * 1024):
+                handle.write(chunk)
+        return target
+
+    # ------------------------------------------------------------------ 组合流程
+
+    def translate_file(
+        self,
+        path: PathLike,
+        target_lang: str,
+        *,
+        output_dir: PathLike = ".",
+        poll_interval: float = 3.0,
+        timeout: float = 1800.0,
+        **options: Any,
+    ) -> List[Path]:
+        """上传、翻译、等待并下载全部产物，返回下载后的文件路径列表。
+
+        options 会原样传给 create_job（如 output_mode、engine、glossary_id）。
+        任务失败时抛出 JobFailedError。
+        """
+        document_id = self.upload(path)
+        job = self.create_job(document_id, target_lang, **options)
+        job = self.wait_job(job["id"], poll_interval=poll_interval, timeout=timeout)
+        if job.get("status") == "failed":
+            raise JobFailedError(job)
+
+        files: List[Path] = []
+        for artifact in self.list_artifacts(job["id"]):
+            fallback = f"{artifact['id']}.{artifact.get('format') or 'bin'}"
+            files.append(
+                self.download_artifact(
+                    artifact["id"], output_dir, fallback_name=fallback
+                )
+            )
+        return files
+
+    # ------------------------------------------------------------------ 账户与用量
+
+    def credit_balance(self) -> Dict[str, Any]:
+        """积分余额（不扣积分）。"""
+        return self.get_json("billing/credits/balance")
+
+    def credit_operations(self, **params: Any) -> Any:
+        """积分流水，可按文档支持的查询参数过滤（不扣积分）。"""
+        return self.get_json("billing/credits/operations", params=params or None)
+
+    def usage_summary(self, **params: Any) -> Any:
+        """用量汇总（不扣积分）。"""
+        return self.get_json("usage/summary", params=params or None)
+
+
+def _retry_delay(response: requests.Response, attempt: int) -> float:
+    """优先使用 Retry-After；没有时指数退避并加入随机抖动。"""
+    retry_after = response.headers.get("Retry-After")
+    if retry_after:
+        try:
+            return max(float(retry_after), 0.0)
+        except ValueError:
+            pass
+    return min(2 ** attempt, 16) + random.random()

omnidoc-0.1.0/src/omnidoc/errors.py

@@ -0,0 +1,72 @@
+"""OmniDoc 客户端的异常类型。"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+
+class OmniDocError(Exception):
+    """API 返回的错误（HTTP 状态码 >= 400）。
+
+    code 来自响应体的 code 字段；只有部分错误带 code，缺失时为 UNKNOWN_ERROR。
+    request_id 对应响应头 X-Request-Id，排查问题时请一并提供。
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        *,
+        detail: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(f"HTTP {status_code} {code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.detail = detail
+        self.request_id = request_id
+
+
+class JobFailedError(RuntimeError):
+    """翻译任务以 failed 结束。
+
+    quota_exceeded 为 True 时表示余额不足以开始该文件，任务未扣费。
+    """
+
+    def __init__(self, job: dict) -> None:
+        self.job = job
+        self.quota_exceeded = bool(job.get("quota_exceeded"))
+        super().__init__(job.get("error_msg") or "translation failed")
+
+
+def error_from_response(response: requests.Response) -> OmniDocError:
+    """把错误响应转换成 OmniDocError，兼容无 JSON 或 422 字段列表的情况。"""
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+    if not isinstance(body, dict):
+        body = {}
+
+    code = body.get("code") or "UNKNOWN_ERROR"
+    detail = body.get("detail")
+    message = body.get("message")
+    if not message:
+        if isinstance(detail, str):
+            message = detail
+        elif isinstance(detail, list):
+            message = "参数校验失败"
+        else:
+            message = response.reason or "request failed"
+
+    return OmniDocError(
+        response.status_code,
+        code,
+        message,
+        detail=detail,
+        request_id=response.headers.get("X-Request-Id"),
+    )

omnidoc-0.1.0/src/omnidoc/webhooks.py

@@ -0,0 +1,44 @@
+"""Webhook 回调验签。
+
+签名是对原始请求体做 HMAC-SHA256，头部格式为 ``X-Webhook-Signature: sha256=<hex>``。
+必须用收到的原始字节验签，不要先解析再重新序列化。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Optional
+
+DEFAULT_TOLERANCE_SECONDS = 12 * 3600
+
+
+def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
+    """检查签名是否与原始请求体匹配。"""
+    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(f"sha256={expected}", signature)
+
+
+def parse_webhook(
+    payload: bytes,
+    signature: str,
+    secret: str,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> dict[str, Any]:
+    """验签并解析回调；签名不符或 timestamp 超出容差时抛出 ValueError。
+
+    失败重试会原样重发，因此时效窗口不要短于最后一次重试（约 8.6 小时）。
+    接收端还应按 data.job_id 与 data.status 去重。
+    """
+    if not verify_webhook(payload, signature, secret):
+        raise ValueError("invalid signature")
+
+    event = json.loads(payload)
+    current = time.time() if now is None else now
+    if abs(current - event["timestamp"]) > tolerance:
+        raise ValueError("stale event")
+    return event

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

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: omnidoc
+Version: 0.1.0
+Summary: OmniDoc 开放 API 的 Python 客户端：上传、翻译、下载、积分查询与 Webhook 验签
+Project-URL: Homepage, https://omnidoc.top/
+Project-URL: Documentation, https://docs.omnidoc.top/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# omnidoc（Python）
+
+OmniDoc 开放 API 的 Python 客户端：上传文件、创建翻译任务、等待结果、下载产物，并提供积分查询和 Webhook 验签。接口说明见 <https://docs.omnidoc.top/>。
+
+## 安装
+
+发布到 PyPI 之前，可以从源码安装：
+
+```bash
+pip install ./libs/omnidoc-python
+```
+
+发布后使用 `pip install omnidoc`。
+
+依赖只有 `requests`，需要 Python 3.9 或更新版本。
+
+## 快速开始
+
+在环境变量里设置 API Key（以 `sk_` 开头，在 API 中心创建）：
+
+```bash
+export OMNIDOC_API_KEY="sk_your_key"
+```
+
+```python
+from omnidoc import OmniDocClient
+
+client = OmniDocClient()  # 读取 OMNIDOC_API_KEY
+files = client.translate_file("report.docx", "en", output_dir="out")
+print(files)
+```
+
+`translate_file` 会依次完成：上传（presign → 直传 → finalize）、创建翻译任务、轮询直到结束、下载全部产物。任务失败时抛出 `JobFailedError`，`quota_exceeded` 为 True 表示余额不足，未扣费。
+
+## 分步调用
+
+```python
+doc_id = client.upload("report.docx")
+job = client.create_job(doc_id, "en", output_mode="bilingual", engine="xr-397b")
+job = client.wait_job(job["id"], poll_interval=3, timeout=1800)
+for artifact in client.list_artifacts(job["id"]):
+    client.download_artifact(artifact["id"], "out", fallback_name=f"{artifact['id']}.{artifact.get('format', 'bin')}")
+```
+
+`create_job` 每次调用会生成新的 `Idempotency-Key`；内部重试沿用同一个键，不会重复创建或扣费。需要自己重试同一次提交时，传入相同的 `idempotency_key`。
+
+## 查询与其他接口
+
+```python
+client.get_job(job_id)           # 任务状态（不扣积分）
+client.cancel_job(job_id)        # 取消任务
+client.credit_balance()          # 积分余额（不扣积分）
+client.credit_operations()       # 积分流水
+client.usage_summary()           # 用量汇总
+
+# 尚未封装的接口，按 docs.omnidoc.top 上的路径直接调用：
+client.get_json("<路径>", params={...})
+client.post_json("<路径>", json={...})
+```
+
+## 错误与重试
+
+- API 错误统一抛出 `OmniDocError`，带有 `status_code`、`code`、`message` 与 `request_id`（对应响应头 `X-Request-Id`）。
+- 429 与 5xx 会按 `Retry-After` 或指数退避重试，最多 `max_retries` 次（默认 4）。
+- `AUTH_API_KEY_QUOTA_EXCEEDED` 不重试：该 Key 的预算已用尽，需要先调高预算。
+
+## Webhook 验签
+
+```python
+from omnidoc import parse_webhook
+
+event = parse_webhook(raw_body, request.headers["X-Webhook-Signature"], secret)
+```
+
+必须使用收到的原始请求体字节验签。签名或时间戳不符时抛出 `ValueError`。接收端还应按 `data.job_id` 与 `data.status` 去重。
+
+## 安全
+
+- Key 只在服务端或受控环境保存，不要写进源码、日志或公开仓库。
+- Key 只发送给 API 地址，不会发送给直传的 `upload_url`。
+
+## 开发
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+测试使用假的 HTTP 会话，不需要 API Key，也不会访问网络。

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/omnidoc/__init__.py
+src/omnidoc/client.py
+src/omnidoc/errors.py
+src/omnidoc/webhooks.py
+src/omnidoc.egg-info/PKG-INFO
+src/omnidoc.egg-info/SOURCES.txt
+src/omnidoc.egg-info/dependency_links.txt
+src/omnidoc.egg-info/requires.txt
+src/omnidoc.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+requests>=2.31
+
+[test]
+pytest>=8

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

@@ -0,0 +1 @@
+omnidoc

omnidoc-0.1.0/tests/test_client.py

@@ -0,0 +1,274 @@
+import hashlib
+import hmac
+import json
+
+import pytest
+import requests
+
+import omnidoc.client as client_module
+from omnidoc import JobFailedError, OmniDocClient, OmniDocError, parse_webhook, verify_webhook
+
+
+class FakeResponse:
+    def __init__(self, status_code=200, body=None, headers=None, content=b""):
+        self.status_code = status_code
+        self._body = body
+        self.headers = headers or {}
+        self.content = content
+        self.reason = "OK" if status_code < 400 else "Error"
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("no json body")
+        return self._body
+
+    def iter_content(self, chunk_size=1):
+        yield self.content
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise requests.HTTPError(f"HTTP {self.status_code}")
+
+
+class FakeSession:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    def request(self, method, url, **kwargs):
+        self.calls.append((method, url, kwargs))
+        return self.responses.pop(0)
+
+
+class PutOk:
+    status_code = 200
+
+    def raise_for_status(self):
+        return None
+
+
+@pytest.fixture
+def sleeps(monkeypatch):
+    recorded = []
+    monkeypatch.setattr(client_module.time, "sleep", lambda seconds: recorded.append(seconds))
+    return recorded
+
+
+def make_client(responses, **kwargs):
+    session = FakeSession(responses)
+    return OmniDocClient("sk_test", session=session, **kwargs), session
+
+
+def test_api_key_is_read_from_environment(monkeypatch):
+    monkeypatch.setenv("OMNIDOC_API_KEY", "sk_env")
+    client = OmniDocClient(session=FakeSession([]))
+    assert client._api_key == "sk_env"
+
+
+def test_missing_api_key_raises(monkeypatch):
+    monkeypatch.delenv("OMNIDOC_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        OmniDocClient(session=FakeSession([]))
+
+
+def test_request_sends_key_header_to_api_base():
+    client, session = make_client([FakeResponse(200, {"balance": 10})])
+    assert client.credit_balance() == {"balance": 10}
+    method, url, kwargs = session.calls[0]
+    assert method == "GET"
+    assert url == "https://omnidoc.top/api/v1/billing/credits/balance"
+    assert kwargs["headers"]["X-API-Key"] == "sk_test"
+
+
+def test_retries_429_using_retry_after(sleeps):
+    client, session = make_client(
+        [
+            FakeResponse(429, {"code": "RATE_LIMITED", "message": "slow down"}, {"Retry-After": "7"}),
+            FakeResponse(200, {"ok": 1}),
+        ]
+    )
+    assert client.usage_summary() == {"ok": 1}
+    assert sleeps == [7.0]
+    assert len(session.calls) == 2
+
+
+def test_quota_exceeded_is_not_retried(sleeps):
+    client, session = make_client(
+        [FakeResponse(429, {"code": "AUTH_API_KEY_QUOTA_EXCEEDED", "message": "quota used up"})]
+    )
+    with pytest.raises(OmniDocError) as info:
+        client.usage_summary()
+    assert info.value.code == "AUTH_API_KEY_QUOTA_EXCEEDED"
+    assert sleeps == []
+    assert len(session.calls) == 1
+
+
+def test_gives_up_after_max_retries(sleeps):
+    client, session = make_client(
+        [FakeResponse(503, {"message": "busy"}) for _ in range(3)], max_retries=2
+    )
+    with pytest.raises(OmniDocError) as info:
+        client.usage_summary()
+    assert info.value.status_code == 503
+    assert len(session.calls) == 3
+
+
+def test_error_carries_request_id():
+    client, _ = make_client(
+        [FakeResponse(401, {"code": "UNAUTHORIZED", "message": "bad key"}, {"X-Request-Id": "req-1"})]
+    )
+    with pytest.raises(OmniDocError) as info:
+        client.usage_summary()
+    assert info.value.status_code == 401
+    assert info.value.request_id == "req-1"
+
+
+def test_422_field_list_becomes_readable_message():
+    client, _ = make_client(
+        [FakeResponse(422, {"detail": [{"loc": ["body", "target_lang"], "msg": "Field required"}]})]
+    )
+    with pytest.raises(OmniDocError) as info:
+        client.post_json("jobs", json={})
+    assert info.value.message == "参数校验失败"
+
+
+def test_create_job_sends_idempotency_key_and_only_set_options():
+    client, session = make_client([FakeResponse(201, {"id": "job1", "status": "pending"})])
+    job = client.create_job(
+        "doc1", "en", output_mode="bilingual", engine="xr-397b", idempotency_key="key-1"
+    )
+    assert job["id"] == "job1"
+    method, url, kwargs = session.calls[0]
+    assert method == "POST" and url.endswith("/jobs")
+    assert kwargs["headers"]["Idempotency-Key"] == "key-1"
+    assert kwargs["json"] == {
+        "document_id": "doc1",
+        "target_lang": "en",
+        "output_mode": "bilingual",
+        "engine": "xr-397b",
+    }
+
+
+def test_create_job_retry_reuses_idempotency_key(sleeps):
+    client, session = make_client(
+        [FakeResponse(503, {"message": "busy"}), FakeResponse(201, {"id": "job2"})]
+    )
+    client.create_job("doc1", "en", idempotency_key="same-key")
+    keys = [call[2]["headers"]["Idempotency-Key"] for call in session.calls]
+    assert keys == ["same-key", "same-key"]
+
+
+def test_upload_runs_presign_put_finalize(monkeypatch, tmp_path):
+    source = tmp_path / "report.docx"
+    source.write_bytes(b"hello")
+    put_calls = []
+
+    def fake_put(url, headers=None, data=None, timeout=None):
+        put_calls.append((url, headers, data.read()))
+        return PutOk()
+
+    monkeypatch.setattr(client_module.requests, "put", fake_put)
+    client, session = make_client(
+        [
+            FakeResponse(
+                200,
+                {
+                    "upload_url": "https://upload.example/x",
+                    "upload_headers": {"Content-Type": "application/octet-stream"},
+                    "finalize_token": "tok",
+                },
+            ),
+            FakeResponse(200, {"document": {"id": "doc9"}}),
+        ]
+    )
+    assert client.upload(source) == "doc9"
+
+    url, headers, body = put_calls[0]
+    assert url == "https://upload.example/x"
+    assert headers["Content-Length"] == "5"
+    assert body == b"hello"
+    # 直传地址不能带 API Key
+    assert "X-API-Key" not in headers
+    assert session.calls[0][1].endswith("/upload/presign")
+    assert session.calls[1][1].endswith("/upload/finalize")
+    assert session.calls[1][2]["json"] == {"finalize_token": "tok"}
+
+
+def test_translate_file_downloads_with_server_filename(monkeypatch, tmp_path):
+    source = tmp_path / "in.docx"
+    source.write_bytes(b"x")
+    monkeypatch.setattr(client_module.requests, "put", lambda *a, **k: PutOk())
+    client, _ = make_client(
+        [
+            FakeResponse(200, {"upload_url": "https://u", "upload_headers": {}, "finalize_token": "t"}),
+            FakeResponse(200, {"document": {"id": "d1"}}),
+            FakeResponse(201, {"id": "j1", "status": "pending"}),
+            FakeResponse(200, {"id": "j1", "status": "completed"}),
+            FakeResponse(200, [{"id": "a1", "format": "docx"}]),
+            FakeResponse(
+                200,
+                content=b"DATA",
+                headers={"Content-Disposition": "attachment; filename*=UTF-8''%E6%96%87%E6%A1%A3.docx"},
+            ),
+        ]
+    )
+    files = client.translate_file(source, "en", output_dir=tmp_path / "out", poll_interval=0)
+    assert [f.name for f in files] == ["文档.docx"]
+    assert files[0].read_bytes() == b"DATA"
+
+
+def test_download_strips_directory_parts_from_server_filename(tmp_path):
+    client, _ = make_client(
+        [FakeResponse(200, content=b"Z", headers={"Content-Disposition": 'attachment; filename="../../evil.txt"'})]
+    )
+    saved = client.download_artifact("a1", tmp_path, fallback_name="a1.txt")
+    assert saved.parent == tmp_path
+    assert saved.name == "evil.txt"
+
+
+def test_translate_file_raises_when_job_failed(monkeypatch, tmp_path):
+    source = tmp_path / "in.pdf"
+    source.write_bytes(b"x")
+    monkeypatch.setattr(client_module.requests, "put", lambda *a, **k: PutOk())
+    client, _ = make_client(
+        [
+            FakeResponse(200, {"upload_url": "https://u", "upload_headers": {}, "finalize_token": "t"}),
+            FakeResponse(200, {"document": {"id": "d2"}}),
+            FakeResponse(201, {"id": "j2", "status": "pending"}),
+            FakeResponse(
+                200,
+                {"id": "j2", "status": "failed", "quota_exceeded": True, "error_msg": "余额不足"},
+            ),
+        ]
+    )
+    with pytest.raises(JobFailedError) as info:
+        client.translate_file(source, "en", output_dir=tmp_path, poll_interval=0)
+    assert info.value.quota_exceeded is True
+
+
+def _sign(payload: bytes, secret: str) -> str:
+    return "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+
+
+def test_verify_webhook_accepts_matching_signature():
+    body = b'{"event":"job.completed","timestamp":1000,"data":{}}'
+    assert verify_webhook(body, _sign(body, "s3cret"), "s3cret")
+
+
+def test_verify_webhook_rejects_tampered_body():
+    body = b'{"x":1}'
+    assert not verify_webhook(b'{"x":2}', _sign(body, "s3cret"), "s3cret")
+
+
+def test_parse_webhook_returns_event_within_tolerance():
+    body = json.dumps(
+        {"event": "job.completed", "timestamp": 1000, "data": {"job_id": "j", "status": "completed"}}
+    ).encode()
+    event = parse_webhook(body, _sign(body, "k"), "k", now=1500)
+    assert event["data"]["job_id"] == "j"
+
+
+def test_parse_webhook_rejects_stale_event():
+    body = json.dumps({"event": "job.completed", "timestamp": 1000, "data": {}}).encode()
+    with pytest.raises(ValueError, match="stale"):
+        parse_webhook(body, _sign(body, "k"), "k", now=1000 + 13 * 3600)