dxpos-openapi 0.0.1__py3-none-any.whl

dxpos_openapi/__init__.py

@@ -0,0 +1,6 @@
+from dxpos_openapi.client import DxposClient
+from dxpos_openapi.constants import DEFAULT_BASE_URL
+
+__version__ = "0.0.1"
+
+__all__ = ["DxposClient", "DEFAULT_BASE_URL", "__version__"]

dxpos_openapi/auth.py

@@ -0,0 +1,42 @@
+import hashlib
+import hmac
+import time
+import uuid
+
+from dxpos_openapi.constants import (
+    HEADER_ACCESS_KEY,
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+)
+
+
+def body_sha256_hex(body):
+    return hashlib.sha256(body or b"").hexdigest()
+
+
+def build_sign_str(method, path, timestamp, nonce, body):
+    return "{}\n{}\n{}\n{}\n{}".format(
+        method,
+        path,
+        timestamp,
+        nonce,
+        body_sha256_hex(body),
+    )
+
+
+def sign_headers(access_key, secret_key, method, path, body=b""):
+    timestamp = str(int(time.time()))
+    nonce = uuid.uuid4().hex
+    raw = build_sign_str(method, path, timestamp, nonce, body)
+    signature = hmac.new(
+        secret_key.encode("utf-8"),
+        raw.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return {
+        HEADER_ACCESS_KEY: access_key,
+        HEADER_TIMESTAMP: timestamp,
+        HEADER_NONCE: nonce,
+        HEADER_SIGNATURE: signature,
+    }

dxpos_openapi/client.py

@@ -0,0 +1,174 @@
+import json
+import os
+
+import requests
+
+from dxpos_openapi.auth import sign_headers
+from dxpos_openapi.constants import (
+    DEFAULT_BASE_URL,
+    IMAGE_TYPE_FILE_ID,
+    IMAGE_TYPE_URL,
+    MIME_BY_SUFFIX,
+    PATH_FILE,
+    PATH_SCENE_ENHANCEMENT,
+    PATH_THEME,
+    path_cancel,
+    path_task,
+)
+
+
+def _fail(msg, request_id=""):
+    return {"code": -1, "msg": msg, "data": {}, "request_id": request_id}
+
+
+def _encode_json(payload):
+    return json.dumps(payload, ensure_ascii=False).encode("utf-8")
+
+
+class DxposClient(object):
+    def __init__(self, access_key, secret_key, base_url=DEFAULT_BASE_URL, timeout=30):
+        if not access_key or not secret_key:
+            raise ValueError("access_key 和 secret_key 不能为空")
+        self.access_key = access_key
+        self.secret_key = secret_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    def list_themes(self):
+        return self._request("GET", PATH_THEME)
+
+    def upload_file(self, image_path):
+        loaded = self._read_local_image(image_path)
+        if loaded["error"] is not None:
+            return loaded["error"]
+        created = self._request(
+            "POST",
+            PATH_FILE,
+            {
+                "size": loaded["size"],
+                "content_type": loaded["content_type"],
+                "filename": loaded["filename"],
+            },
+        )
+        if created.get("code") != 0:
+            return created
+        put_url = (created.get("data") or {}).get("put_url")
+        if not put_url:
+            return _fail("预创建成功但缺少 put_url")
+        put_error = self._put_cos(
+            put_url,
+            loaded["raw"],
+            loaded["content_type"],
+            loaded["size"],
+        )
+        if put_error is not None:
+            return put_error
+        return created
+
+    def create_scene_enhancement(self, theme_id, file_id=None, image_path=None, image_url=None):
+        picked = [item for item in (file_id, image_path, image_url) if item]
+        if len(picked) != 1:
+            return _fail("file_id、image_path、image_url 必须三选一")
+        if image_url:
+            return self._request(
+                "POST",
+                PATH_SCENE_ENHANCEMENT,
+                {
+                    "theme_id": theme_id,
+                    "image": {"type": IMAGE_TYPE_URL, "url": image_url},
+                },
+            )
+        if file_id:
+            return self._request(
+                "POST",
+                PATH_SCENE_ENHANCEMENT,
+                {
+                    "theme_id": theme_id,
+                    "image": {"type": IMAGE_TYPE_FILE_ID, "file_id": file_id},
+                },
+            )
+        uploaded = self.upload_file(image_path)
+        if uploaded.get("code") != 0:
+            return uploaded
+        new_file_id = (uploaded.get("data") or {}).get("file_id")
+        if not new_file_id:
+            return _fail("上传成功但缺少 file_id")
+        return self._request(
+            "POST",
+            PATH_SCENE_ENHANCEMENT,
+            {
+                "theme_id": theme_id,
+                "image": {"type": IMAGE_TYPE_FILE_ID, "file_id": new_file_id},
+            },
+        )
+
+    def get_task(self, task_id):
+        return self._request("GET", path_task(task_id))
+
+    def cancel_task(self, task_id):
+        return self._request("POST", path_cancel(task_id))
+
+    def _request(self, method, path, payload=None):
+        body = b"" if payload is None else _encode_json(payload)
+        headers = sign_headers(self.access_key, self.secret_key, method, path, body)
+        if payload is not None:
+            headers["Content-Type"] = "application/json"
+        try:
+            resp = self._session.request(
+                method,
+                self.base_url + path,
+                data=body,
+                headers=headers,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            return _fail("请求失败: {}".format(exc))
+        try:
+            parsed = resp.json()
+        except ValueError:
+            return _fail("响应不是 JSON: HTTP {}".format(resp.status_code))
+        if not isinstance(parsed, dict):
+            return _fail("响应格式不正确")
+        return parsed
+
+    def _put_cos(self, put_url, raw, content_type, size):
+        try:
+            resp = self._session.put(
+                put_url,
+                data=raw,
+                headers={
+                    "Content-Type": content_type,
+                    "Content-Length": str(size),
+                },
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            return _fail("上传失败: {}".format(exc))
+        if resp.status_code not in (200, 204):
+            return _fail("上传失败: HTTP {}".format(resp.status_code))
+        return None
+
+    @staticmethod
+    def _read_local_image(image_path):
+        if not image_path or not os.path.isfile(image_path):
+            return {"error": _fail("本地文件不存在")}
+        content_type = MIME_BY_SUFFIX.get(os.path.splitext(image_path)[1].lower())
+        if content_type is None:
+            return {
+                "error": _fail("图片格式不支持，仅支持 image/jpeg、image/png、image/webp")
+            }
+        try:
+            with open(image_path, "rb") as handle:
+                raw = handle.read()
+        except OSError as exc:
+            return {"error": _fail("读取本地文件失败: {}".format(exc))}
+        if not raw:
+            return {"error": _fail("本地文件为空")}
+        return {
+            "error": None,
+            "raw": raw,
+            "content_type": content_type,
+            "filename": os.path.basename(image_path),
+            "size": len(raw),
+        }

dxpos_openapi/constants.py

@@ -0,0 +1,28 @@
+DEFAULT_BASE_URL = "https://openapi.dxpos.co"
+
+PATH_THEME = "/api/v1/theme"
+PATH_FILE = "/api/v1/file"
+PATH_SCENE_ENHANCEMENT = "/api/v1/task/scene_enhancement"
+
+HEADER_ACCESS_KEY = "X-Access-Key"
+HEADER_TIMESTAMP = "X-Timestamp"
+HEADER_NONCE = "X-Nonce"
+HEADER_SIGNATURE = "X-Signature"
+
+IMAGE_TYPE_FILE_ID = "file_id"
+IMAGE_TYPE_URL = "url"
+
+MIME_BY_SUFFIX = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+}
+
+
+def path_task(task_id):
+    return "/api/v1/task/{}".format(task_id)
+
+
+def path_cancel(task_id):
+    return "/api/v1/task/{}/cancel".format(task_id)

dxpos_openapi-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DXPOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dxpos_openapi-0.0.1.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.1
+Name: dxpos-openapi
+Version: 0.0.1
+Summary: DXPOS OpenAPI Python SDK
+Author-email: DXPOS <support@dxpos.co>
+License: MIT License
+        
+        Copyright (c) 2026 DXPOS
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://openapi.dxpos.co
+Project-URL: Documentation, https://openapi.dxpos.co
+Keywords: dxpos,openapi,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8.16
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.31.0
+Requires-Dist: urllib3==1.26.20
+Requires-Dist: certifi==2024.8.30
+Requires-Dist: charset-normalizer==3.3.2
+Requires-Dist: idna==3.7
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.5; extra == "dev"
+Requires-Dist: build==1.2.2; extra == "dev"
+Requires-Dist: twine==5.1.1; extra == "dev"
+Requires-Dist: setuptools==75.3.0; extra == "dev"
+Requires-Dist: wheel==0.45.1; extra == "dev"
+
+# dxpos-openapi
+
+DXPOS OpenAPI 的 Python SDK。安装后：
+
+```python
+from dxpos_openapi import DxposClient
+```
+
+需要 Python 3.8.16 及以上。
+
+## 安装
+
+```bash
+pip install dxpos-openapi
+```
+
+升级：
+
+```bash
+pip install -U dxpos-openapi
+```
+
+## 初始化
+
+密钥和域名在构造 `DxposClient` 时传入，SDK 不读环境变量。`base_url` 默认生产域名。
+
+```python
+from dxpos_openapi import DxposClient
+
+client = DxposClient(
+    access_key="你的 Access Key",
+    secret_key="你的 Secret Key",
+    # base_url="https://openapi-test.dxpos.co",  # 测试环境
+)
+```
+
+| 环境 | base_url |
+|------|----------|
+| 生产（默认） | `https://openapi.dxpos.co` |
+| 测试 | `https://openapi-test.dxpos.co` |
+
+五个方法会自动做 HMAC 签名，不用自己算。
+
+## 返回值
+
+每个方法都返回接口原样字典，业务失败也不抛异常：
+
+```python
+{
+    "code": 0,
+    "msg": "",
+    "data": {},
+    "request_id": "req_..."
+}
+```
+
+`code == 0` 为成功，读 `data`。本地文件不存在、格式不支持、COS 上传失败、网络错误等会合成 `code == -1`。
+
+## 方法
+
+### 主题列表
+
+```python
+resp = client.list_themes()
+theme_id = resp["data"]["items"][0]["theme_id"]
+```
+
+### 上传本地图片
+
+内部会预创建文件并 PUT 到 COS。成功时返回预创建接口的原样 JSON，`data` 里有 `file_id`。
+
+```python
+resp = client.upload_file("/path/to/product.jpg")
+file_id = resp["data"]["file_id"]
+```
+
+仅支持 `.jpg` / `.jpeg` / `.png` / `.webp`。
+
+### 创建场景增强任务
+
+`file_id`、`image_path`、`image_url` 必须三选一。
+
+```python
+# 已有公网 URL
+resp = client.create_scene_enhancement(
+    theme_id=theme_id,
+    image_url="https://example.com/product.jpg",
+)
+
+# 已经 upload_file 拿到 file_id
+resp = client.create_scene_enhancement(theme_id=theme_id, file_id=file_id)
+
+# 本地路径：自动上传再建任务
+resp = client.create_scene_enhancement(
+    theme_id=theme_id,
+    image_path="/path/to/product.jpg",
+)
+
+task_id = resp["data"]["task_id"]
+```
+
+### 查询任务
+
+```python
+resp = client.get_task(task_id)
+# data.status: waiting / processing / done / failed / canceled
+```
+
+### 取消任务
+
+仅排队中（`waiting`）可取消。
+
+```python
+resp = client.cancel_task(task_id)
+```
+
+## 维护者：发布到 PyPI
+
+不需要把 token 写进仓库。本机配置 `~/.pypirc`，用 `__token__` 和 API token。
+
+开发依赖：
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+首次 `0.0.1`：
+
+```bash
+rm -rf dist build src/*.egg-info
+python -m build
+twine check dist/*
+twine upload -r testpypi dist/*
+# 干净环境验证：
+# pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple dxpos-openapi==0.0.1
+twine upload dist/*
+git tag v0.0.1
+git push origin main --tags
+```
+
+以后更新：同步改 `pyproject.toml` 的 `version` 和 `src/dxpos_openapi/__init__.py` 的 `__version__`，再走一遍 build / twine / tag。同一版本号不能覆盖重传。小改用 `0.0.x`，加方法或改入参用 `0.1.0`。

dxpos_openapi-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+dxpos_openapi/__init__.py,sha256=3ChDNCNYzU6kw6IXq5m2b4jb_eZyMnt6WQCLPaYK7X4,183
+dxpos_openapi/auth.py,sha256=nmARbBgQq6k6iNIzhdNR1Yndo3NfQORGVJtzrJRbxBc,950
+dxpos_openapi/client.py,sha256=yaOh3fjIC2ETOrIsmAUhS9P_3erY9a-loh03cLejhOM,5861
+dxpos_openapi/constants.py,sha256=asy51Q8UtrBX0FZS0FVUS4ZGpymIrIargjQqAjKyx5o,621
+dxpos_openapi-0.0.1.dist-info/LICENSE,sha256=0EazA4qvynt-70-mNL0Q5vzQFwGuLMLRjgzrAmKsmMY,1062
+dxpos_openapi-0.0.1.dist-info/METADATA,sha256=YqcDD44DmFaEQRIV4ZVRx2fPy2dOsSMgL60y0nemVQA,5655
+dxpos_openapi-0.0.1.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+dxpos_openapi-0.0.1.dist-info/top_level.txt,sha256=w-2h_7jVu5SIf_rSTubE3wy50gW1QAvBngNVBjktuJ4,14
+dxpos_openapi-0.0.1.dist-info/RECORD,,

dxpos_openapi-0.0.1.dist-info/WHEEL

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

dxpos_openapi-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+dxpos_openapi