dxpos-openapi 0.0.1__tar.gz

dxpos_openapi-0.0.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,142 @@
+# 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/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools==75.3.0", "wheel==0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dxpos-openapi"
+version = "0.0.1"
+description = "DXPOS OpenAPI Python SDK"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8.16"
+authors = [{name = "DXPOS", email = "support@dxpos.co"}]
+keywords = ["dxpos", "openapi", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests==2.31.0",
+    "urllib3==1.26.20",
+    "certifi==2024.8.30",
+    "charset-normalizer==3.3.2",
+    "idna==3.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.3.5",
+    "build==1.2.2",
+    "twine==5.1.1",
+    "setuptools==75.3.0",
+    "wheel==0.45.1",
+]
+
+[project.urls]
+Homepage = "https://openapi.dxpos.co"
+Documentation = "https://openapi.dxpos.co"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

dxpos_openapi-0.0.1/setup.cfg

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

dxpos_openapi-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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/src/dxpos_openapi.egg-info/PKG-INFO

@@ -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/src/dxpos_openapi.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/dxpos_openapi/__init__.py
+src/dxpos_openapi/auth.py
+src/dxpos_openapi/client.py
+src/dxpos_openapi/constants.py
+src/dxpos_openapi.egg-info/PKG-INFO
+src/dxpos_openapi.egg-info/SOURCES.txt
+src/dxpos_openapi.egg-info/dependency_links.txt
+src/dxpos_openapi.egg-info/requires.txt
+src/dxpos_openapi.egg-info/top_level.txt
+tests/test_auth.py
+tests/test_client.py

dxpos_openapi-0.0.1/src/dxpos_openapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dxpos_openapi-0.0.1/src/dxpos_openapi.egg-info/requires.txt

@@ -0,0 +1,12 @@
+requests==2.31.0
+urllib3==1.26.20
+certifi==2024.8.30
+charset-normalizer==3.3.2
+idna==3.7
+
+[dev]
+pytest==8.3.5
+build==1.2.2
+twine==5.1.1
+setuptools==75.3.0
+wheel==0.45.1

dxpos_openapi-0.0.1/src/dxpos_openapi.egg-info/top_level.txt

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

dxpos_openapi-0.0.1/tests/test_auth.py

@@ -0,0 +1,51 @@
+import hashlib
+import hmac
+
+from dxpos_openapi.auth import body_sha256_hex, build_sign_str, sign_headers
+from dxpos_openapi.constants import (
+    HEADER_ACCESS_KEY,
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+)
+
+
+def test_empty_body_sha256():
+    assert body_sha256_hex(b"") == hashlib.sha256(b"").hexdigest()
+    assert body_sha256_hex(None) == hashlib.sha256(b"").hexdigest()
+
+
+def test_sign_str_five_lines():
+    body = b'{"size":1}'
+    raw = build_sign_str("POST", "/api/v1/file", "1700000000", "abc", body)
+    lines = raw.split("\n")
+    assert lines == [
+        "POST",
+        "/api/v1/file",
+        "1700000000",
+        "abc",
+        hashlib.sha256(body).hexdigest(),
+    ]
+
+
+def test_sign_headers_hex_and_fields():
+    headers = sign_headers("ak", "sk", "GET", "/api/v1/theme", b"")
+    assert set(headers) == {
+        HEADER_ACCESS_KEY,
+        HEADER_TIMESTAMP,
+        HEADER_NONCE,
+        HEADER_SIGNATURE,
+    }
+    assert headers[HEADER_ACCESS_KEY] == "ak"
+    assert headers[HEADER_TIMESTAMP].isdigit()
+    assert headers[HEADER_NONCE]
+    assert headers[HEADER_SIGNATURE] == headers[HEADER_SIGNATURE].lower()
+    raw = build_sign_str(
+        "GET",
+        "/api/v1/theme",
+        headers[HEADER_TIMESTAMP],
+        headers[HEADER_NONCE],
+        b"",
+    )
+    expected = hmac.new(b"sk", raw.encode("utf-8"), hashlib.sha256).hexdigest()
+    assert headers[HEADER_SIGNATURE] == expected

dxpos_openapi-0.0.1/tests/test_client.py

@@ -0,0 +1,297 @@
+import hashlib
+import hmac
+import json
+
+import pytest
+import requests
+
+from dxpos_openapi.auth import build_sign_str
+from dxpos_openapi.client import DxposClient
+from dxpos_openapi.constants import (
+    DEFAULT_BASE_URL,
+    HEADER_ACCESS_KEY,
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+    PATH_FILE,
+    PATH_SCENE_ENHANCEMENT,
+    PATH_THEME,
+)
+
+
+class FakeResponse(object):
+    def __init__(self, payload=None, status_code=200, text=""):
+        self.status_code = status_code
+        self._payload = payload
+        self.text = text
+
+    def json(self):
+        if self._payload is None:
+            raise ValueError("not json")
+        return self._payload
+
+
+def _ok(data):
+    return {"code": 0, "msg": "", "data": data, "request_id": "req_test"}
+
+
+def _client():
+    return DxposClient("ak", "sk", base_url="https://openapi.example")
+
+
+def _assert_signed(method, path, body, headers):
+    raw = build_sign_str(
+        method,
+        path,
+        headers[HEADER_TIMESTAMP],
+        headers[HEADER_NONCE],
+        body,
+    )
+    expected = hmac.new(b"sk", raw.encode("utf-8"), hashlib.sha256).hexdigest()
+    assert headers[HEADER_ACCESS_KEY] == "ak"
+    assert headers[HEADER_SIGNATURE] == expected
+
+
+def test_constructor_requires_keys():
+    with pytest.raises(ValueError):
+        DxposClient("", "sk")
+    with pytest.raises(ValueError):
+        DxposClient("ak", "")
+
+
+def test_default_base_url():
+    client = DxposClient("ak", "sk")
+    assert client.base_url == DEFAULT_BASE_URL
+
+
+def test_list_themes(monkeypatch):
+    client = _client()
+    captured = {}
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        captured.update(
+            {"method": method, "url": url, "data": data, "headers": headers}
+        )
+        return FakeResponse(_ok({"items": [{"theme_id": "t1"}]}))
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    resp = client.list_themes()
+    assert resp["code"] == 0
+    assert resp["data"]["items"][0]["theme_id"] == "t1"
+    assert captured["method"] == "GET"
+    assert captured["url"] == "https://openapi.example" + PATH_THEME
+    assert captured["data"] == b""
+    _assert_signed("GET", PATH_THEME, b"", captured["headers"])
+
+
+def test_get_and_cancel_task(monkeypatch):
+    client = _client()
+    calls = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        calls.append({"method": method, "url": url, "data": data, "headers": headers})
+        return FakeResponse(_ok({"task_id": "tid", "status": "waiting"}))
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    get_resp = client.get_task("tid")
+    cancel_resp = client.cancel_task("tid")
+    assert get_resp["code"] == 0
+    assert cancel_resp["code"] == 0
+    assert calls[0]["method"] == "GET"
+    assert calls[0]["url"].endswith("/api/v1/task/tid")
+    assert calls[0]["data"] == b""
+    _assert_signed("GET", "/api/v1/task/tid", b"", calls[0]["headers"])
+    assert calls[1]["method"] == "POST"
+    assert calls[1]["url"].endswith("/api/v1/task/tid/cancel")
+    assert calls[1]["data"] == b""
+    _assert_signed("POST", "/api/v1/task/tid/cancel", b"", calls[1]["headers"])
+
+
+def test_create_with_url_does_not_hit_file(monkeypatch):
+    client = _client()
+    calls = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        calls.append({"method": method, "url": url, "data": data, "headers": headers})
+        return FakeResponse(_ok({"task_id": "tid"}))
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    resp = client.create_scene_enhancement(
+        theme_id="theme1",
+        image_url="https://example.com/a.jpg",
+    )
+    assert resp["code"] == 0
+    assert len(calls) == 1
+    assert calls[0]["url"].endswith(PATH_SCENE_ENHANCEMENT)
+    payload = json.loads(calls[0]["data"].decode("utf-8"))
+    assert payload == {
+        "theme_id": "theme1",
+        "image": {"type": "url", "url": "https://example.com/a.jpg"},
+    }
+    _assert_signed("POST", PATH_SCENE_ENHANCEMENT, calls[0]["data"], calls[0]["headers"])
+
+
+def test_create_with_file_id_does_not_hit_file(monkeypatch):
+    client = _client()
+    calls = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        calls.append({"url": url, "data": data})
+        return FakeResponse(_ok({"task_id": "tid"}))
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    resp = client.create_scene_enhancement(theme_id="theme1", file_id="fid")
+    assert resp["code"] == 0
+    assert len(calls) == 1
+    payload = json.loads(calls[0]["data"].decode("utf-8"))
+    assert payload["image"] == {"type": "file_id", "file_id": "fid"}
+
+
+def test_upload_file_success(tmp_path, monkeypatch):
+    image = tmp_path / "product.jpg"
+    raw = b"jpeg-bytes"
+    image.write_bytes(raw)
+    client = _client()
+    calls = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        calls.append({"method": method, "url": url, "data": data, "headers": headers})
+        return FakeResponse(
+            _ok(
+                {
+                    "file_id": "fid1",
+                    "put_url": "https://cos.example/put",
+                    "expires_at": "2026-09-22 18:00:00",
+                }
+            )
+        )
+
+    def fake_put(url, data=None, headers=None, timeout=None):
+        calls.append({"put_url": url, "put_data": data, "put_headers": headers})
+        return FakeResponse(status_code=200)
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    monkeypatch.setattr(client._session, "put", fake_put)
+    resp = client.upload_file(str(image))
+    assert resp["code"] == 0
+    assert resp["data"]["file_id"] == "fid1"
+    assert calls[0]["url"].endswith(PATH_FILE)
+    payload = json.loads(calls[0]["data"].decode("utf-8"))
+    assert payload == {
+        "size": len(raw),
+        "content_type": "image/jpeg",
+        "filename": "product.jpg",
+    }
+    _assert_signed("POST", PATH_FILE, calls[0]["data"], calls[0]["headers"])
+    assert calls[1]["put_url"] == "https://cos.example/put"
+    assert calls[1]["put_data"] == raw
+    assert calls[1]["put_headers"]["Content-Type"] == "image/jpeg"
+    assert calls[1]["put_headers"]["Content-Length"] == str(len(raw))
+
+
+def test_create_with_image_path_chains_upload(tmp_path, monkeypatch):
+    image = tmp_path / "a.png"
+    image.write_bytes(b"png-bytes")
+    client = _client()
+    calls = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        calls.append({"url": url, "data": data})
+        if url.endswith(PATH_FILE):
+            return FakeResponse(_ok({"file_id": "fid2", "put_url": "https://cos.example/put"}))
+        return FakeResponse(_ok({"task_id": "tid2"}))
+
+    def fake_put(url, data=None, headers=None, timeout=None):
+        calls.append({"put": True})
+        return FakeResponse(status_code=204)
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    monkeypatch.setattr(client._session, "put", fake_put)
+    resp = client.create_scene_enhancement(theme_id="theme1", image_path=str(image))
+    assert resp["code"] == 0
+    assert resp["data"]["task_id"] == "tid2"
+    assert [item.get("url", "PUT") for item in calls] == [
+        "https://openapi.example" + PATH_FILE,
+        "PUT",
+        "https://openapi.example" + PATH_SCENE_ENHANCEMENT,
+    ]
+    create_payload = json.loads(calls[2]["data"].decode("utf-8"))
+    assert create_payload == {
+        "theme_id": "theme1",
+        "image": {"type": "file_id", "file_id": "fid2"},
+    }
+
+
+def test_precreate_failure_skips_put(tmp_path, monkeypatch):
+    image = tmp_path / "a.webp"
+    image.write_bytes(b"w")
+    client = _client()
+    put_called = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        return FakeResponse({"code": 10015, "msg": "图片过大，不能超过 5MB", "data": {}, "request_id": "r"})
+
+    def fake_put(*args, **kwargs):
+        put_called.append(True)
+        return FakeResponse(status_code=200)
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    monkeypatch.setattr(client._session, "put", fake_put)
+    resp = client.upload_file(str(image))
+    assert resp["code"] == 10015
+    assert resp["msg"] == "图片过大，不能超过 5MB"
+    assert put_called == []
+
+
+def test_put_failure_skips_create(tmp_path, monkeypatch):
+    image = tmp_path / "a.jpg"
+    image.write_bytes(b"x")
+    client = _client()
+    urls = []
+
+    def fake_request(method, url, data=None, headers=None, timeout=None):
+        urls.append(url)
+        return FakeResponse(_ok({"file_id": "fid", "put_url": "https://cos.example/put"}))
+
+    def fake_put(url, data=None, headers=None, timeout=None):
+        return FakeResponse(status_code=403)
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    monkeypatch.setattr(client._session, "put", fake_put)
+    resp = client.create_scene_enhancement(theme_id="theme1", image_path=str(image))
+    assert resp["code"] == -1
+    assert "403" in resp["msg"]
+    assert urls == ["https://openapi.example" + PATH_FILE]
+
+
+def test_choose_none_or_many():
+    client = _client()
+    none = client.create_scene_enhancement(theme_id="t")
+    both = client.create_scene_enhancement(theme_id="t", file_id="a", image_url="https://x")
+    assert none["code"] == -1
+    assert both["code"] == -1
+    assert "三选一" in none["msg"]
+
+
+def test_missing_file_and_bad_ext(tmp_path):
+    client = _client()
+    missing = client.upload_file(str(tmp_path / "no.jpg"))
+    bad = tmp_path / "a.gif"
+    bad.write_bytes(b"gif")
+    unsupported = client.upload_file(str(bad))
+    assert missing["code"] == -1
+    assert "不存在" in missing["msg"]
+    assert unsupported["code"] == -1
+    assert "格式不支持" in unsupported["msg"]
+
+
+def test_network_error(monkeypatch):
+    client = _client()
+
+    def fake_request(*args, **kwargs):
+        raise requests.ConnectionError("down")
+
+    monkeypatch.setattr(client._session, "request", fake_request)
+    resp = client.list_themes()
+    assert resp["code"] == -1
+    assert "请求失败" in resp["msg"]