wz-opensdk 0.1.0__tar.gz

wz_opensdk-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: wz-opensdk
+Version: 0.1.0
+Summary: 万桩开放平台 Python OpenSDK
+License: MIT
+Project-URL: Homepage, https://gitee.com/wz-open-platform/wz-opensdk-python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# wz-opensdk
+
+万桩开放平台 Python SDK。覆盖 Apifox 项目 `wz-open` 中文目录下的公开 API（设备、充电、续费、开票、回调日志）。`inner/*` 内部接口不在本 SDK 中。SDK 只做 client，不解析平台推送到合作方的入站回调。
+
+发行名：`wz-opensdk`。导入名：`wzopensdk`。Python **3.9+**。
+
+## 安装
+
+```bash
+pip install wz-opensdk
+```
+
+尚未发布到 PyPI 时，可从 Gitee 安装：
+
+```bash
+pip install git+https://gitee.com/wz-open-platform/wz-opensdk-python.git@v0.1.0
+```
+
+本地开发：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+```python
+import os
+from wzopensdk import WzOpenClient, Endpoints
+from wzopensdk.device import DeviceNumRequest
+
+client = WzOpenClient(
+    endpoint=Endpoints.PROD,  # 测试环境用 Endpoints.TEST
+    app_id=os.environ["WZ_OPEN_APP_ID"],
+    app_secret=os.environ["WZ_OPEN_APP_SECRET"],
+)
+
+device = client.device.find_one(DeviceNumRequest("18000001"))
+```
+
+也可 `WzOpenClient.from_env()`（读 `WZ_OPEN_APP_ID` / `WZ_OPEN_APP_SECRET`，可选 `WZ_OPEN_ENDPOINT`，缺省测试环境）。
+
+按域调用，方法不堆在 `WzOpenClient` 上：
+
+- `client.device` 设备绑定、计费模式、状态、在线日志
+- `client.charge.start` / `stop`
+- `client.renew`
+- `client.invoice`
+- `client.callback.log` / `retry_finish_order`
+
+默认请求超时 10s。
+
+## 签名
+
+SDK 按接入指引自动加 `app_id`、`timestamp`、`sign`（HMAC-SHA256 大写 hex）。调用方不要自己拼签，也不要传 `company_id`。金额单位为分。
+
+契约快照：[../api/openapi.json](../api/openapi.json)（汽车桩 `saveMode`/`getMode` 在 SDK 中拆成独立方法；`/open/device/setting/sync` 属于 inner，本 SDK 不实现）。公开能力合计 40 条出站 API。
+
+## 日志
+
+使用标准库 `logging`，logger 名 `wzopensdk`。可传入自定义 logger。
+
+成功请求的 info 日志会带 `method`、`path`；响应头有 `X-B3-TraceId` 时再带 `traceId`。失败时同一字段出现在 error 日志里，并可从 `WzOpenAPIError.trace_id` 读取。
+
+## HTTP
+
+可配 timeout（默认 10s）、retry_count（失败重试且每次重签）、retry_wait、user_agent、proxy_url，或直接传入 `httpx.Client`。
+
+## 环境
+
+| 环境 | Base URL |
+| --- | --- |
+| 测试 | `https://dev-api-open.wanzhuangkj.com` |
+| 正式 | `https://api-open.wanzhuangkj.com` |
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest -q
+# 或 make test
+```
+
+现网验证（需要凭证）：
+
+```bash
+export WZ_OPEN_APP_ID=...
+export WZ_OPEN_APP_SECRET=...
+make verify
+```

wz_opensdk-0.1.0/README.md

@@ -0,0 +1,92 @@
+# wz-opensdk
+
+万桩开放平台 Python SDK。覆盖 Apifox 项目 `wz-open` 中文目录下的公开 API（设备、充电、续费、开票、回调日志）。`inner/*` 内部接口不在本 SDK 中。SDK 只做 client，不解析平台推送到合作方的入站回调。
+
+发行名：`wz-opensdk`。导入名：`wzopensdk`。Python **3.9+**。
+
+## 安装
+
+```bash
+pip install wz-opensdk
+```
+
+尚未发布到 PyPI 时，可从 Gitee 安装：
+
+```bash
+pip install git+https://gitee.com/wz-open-platform/wz-opensdk-python.git@v0.1.0
+```
+
+本地开发：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+```python
+import os
+from wzopensdk import WzOpenClient, Endpoints
+from wzopensdk.device import DeviceNumRequest
+
+client = WzOpenClient(
+    endpoint=Endpoints.PROD,  # 测试环境用 Endpoints.TEST
+    app_id=os.environ["WZ_OPEN_APP_ID"],
+    app_secret=os.environ["WZ_OPEN_APP_SECRET"],
+)
+
+device = client.device.find_one(DeviceNumRequest("18000001"))
+```
+
+也可 `WzOpenClient.from_env()`（读 `WZ_OPEN_APP_ID` / `WZ_OPEN_APP_SECRET`，可选 `WZ_OPEN_ENDPOINT`，缺省测试环境）。
+
+按域调用，方法不堆在 `WzOpenClient` 上：
+
+- `client.device` 设备绑定、计费模式、状态、在线日志
+- `client.charge.start` / `stop`
+- `client.renew`
+- `client.invoice`
+- `client.callback.log` / `retry_finish_order`
+
+默认请求超时 10s。
+
+## 签名
+
+SDK 按接入指引自动加 `app_id`、`timestamp`、`sign`（HMAC-SHA256 大写 hex）。调用方不要自己拼签，也不要传 `company_id`。金额单位为分。
+
+契约快照：[../api/openapi.json](../api/openapi.json)（汽车桩 `saveMode`/`getMode` 在 SDK 中拆成独立方法；`/open/device/setting/sync` 属于 inner，本 SDK 不实现）。公开能力合计 40 条出站 API。
+
+## 日志
+
+使用标准库 `logging`，logger 名 `wzopensdk`。可传入自定义 logger。
+
+成功请求的 info 日志会带 `method`、`path`；响应头有 `X-B3-TraceId` 时再带 `traceId`。失败时同一字段出现在 error 日志里，并可从 `WzOpenAPIError.trace_id` 读取。
+
+## HTTP
+
+可配 timeout（默认 10s）、retry_count（失败重试且每次重签）、retry_wait、user_agent、proxy_url，或直接传入 `httpx.Client`。
+
+## 环境
+
+| 环境 | Base URL |
+| --- | --- |
+| 测试 | `https://dev-api-open.wanzhuangkj.com` |
+| 正式 | `https://api-open.wanzhuangkj.com` |
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest -q
+# 或 make test
+```
+
+现网验证（需要凭证）：
+
+```bash
+export WZ_OPEN_APP_ID=...
+export WZ_OPEN_APP_SECRET=...
+make verify
+```

wz_opensdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wz-opensdk"
+version = "0.1.0"
+description = "万桩开放平台 Python OpenSDK"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+urls = { Homepage = "https://gitee.com/wz-open-platform/wz-opensdk-python" }
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

wz_opensdk-0.1.0/setup.cfg

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

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

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: wz-opensdk
+Version: 0.1.0
+Summary: 万桩开放平台 Python OpenSDK
+License: MIT
+Project-URL: Homepage, https://gitee.com/wz-open-platform/wz-opensdk-python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# wz-opensdk
+
+万桩开放平台 Python SDK。覆盖 Apifox 项目 `wz-open` 中文目录下的公开 API（设备、充电、续费、开票、回调日志）。`inner/*` 内部接口不在本 SDK 中。SDK 只做 client，不解析平台推送到合作方的入站回调。
+
+发行名：`wz-opensdk`。导入名：`wzopensdk`。Python **3.9+**。
+
+## 安装
+
+```bash
+pip install wz-opensdk
+```
+
+尚未发布到 PyPI 时，可从 Gitee 安装：
+
+```bash
+pip install git+https://gitee.com/wz-open-platform/wz-opensdk-python.git@v0.1.0
+```
+
+本地开发：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+```python
+import os
+from wzopensdk import WzOpenClient, Endpoints
+from wzopensdk.device import DeviceNumRequest
+
+client = WzOpenClient(
+    endpoint=Endpoints.PROD,  # 测试环境用 Endpoints.TEST
+    app_id=os.environ["WZ_OPEN_APP_ID"],
+    app_secret=os.environ["WZ_OPEN_APP_SECRET"],
+)
+
+device = client.device.find_one(DeviceNumRequest("18000001"))
+```
+
+也可 `WzOpenClient.from_env()`（读 `WZ_OPEN_APP_ID` / `WZ_OPEN_APP_SECRET`，可选 `WZ_OPEN_ENDPOINT`，缺省测试环境）。
+
+按域调用，方法不堆在 `WzOpenClient` 上：
+
+- `client.device` 设备绑定、计费模式、状态、在线日志
+- `client.charge.start` / `stop`
+- `client.renew`
+- `client.invoice`
+- `client.callback.log` / `retry_finish_order`
+
+默认请求超时 10s。
+
+## 签名
+
+SDK 按接入指引自动加 `app_id`、`timestamp`、`sign`（HMAC-SHA256 大写 hex）。调用方不要自己拼签，也不要传 `company_id`。金额单位为分。
+
+契约快照：[../api/openapi.json](../api/openapi.json)（汽车桩 `saveMode`/`getMode` 在 SDK 中拆成独立方法；`/open/device/setting/sync` 属于 inner，本 SDK 不实现）。公开能力合计 40 条出站 API。
+
+## 日志
+
+使用标准库 `logging`，logger 名 `wzopensdk`。可传入自定义 logger。
+
+成功请求的 info 日志会带 `method`、`path`；响应头有 `X-B3-TraceId` 时再带 `traceId`。失败时同一字段出现在 error 日志里，并可从 `WzOpenAPIError.trace_id` 读取。
+
+## HTTP
+
+可配 timeout（默认 10s）、retry_count（失败重试且每次重签）、retry_wait、user_agent、proxy_url，或直接传入 `httpx.Client`。
+
+## 环境
+
+| 环境 | Base URL |
+| --- | --- |
+| 测试 | `https://dev-api-open.wanzhuangkj.com` |
+| 正式 | `https://api-open.wanzhuangkj.com` |
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest -q
+# 或 make test
+```
+
+现网验证（需要凭证）：
+
+```bash
+export WZ_OPEN_APP_ID=...
+export WZ_OPEN_APP_SECRET=...
+make verify
+```

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

@@ -0,0 +1,26 @@
+README.md
+pyproject.toml
+src/wz_opensdk.egg-info/PKG-INFO
+src/wz_opensdk.egg-info/SOURCES.txt
+src/wz_opensdk.egg-info/dependency_links.txt
+src/wz_opensdk.egg-info/requires.txt
+src/wz_opensdk.egg-info/top_level.txt
+src/wzopensdk/__init__.py
+src/wzopensdk/callback.py
+src/wzopensdk/charge.py
+src/wzopensdk/client.py
+src/wzopensdk/device.py
+src/wzopensdk/endpoints.py
+src/wzopensdk/errors.py
+src/wzopensdk/invoice.py
+src/wzopensdk/renew.py
+src/wzopensdk/_internal/__init__.py
+src/wzopensdk/_internal/http.py
+src/wzopensdk/_internal/params.py
+src/wzopensdk/_internal/signer.py
+tests/test_client.py
+tests/test_contract_error.py
+tests/test_device.py
+tests/test_live_smoke.py
+tests/test_service.py
+tests/test_signer.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+httpx>=0.27
+
+[dev]
+pytest>=8.0

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

@@ -0,0 +1 @@
+wzopensdk

wz_opensdk-0.1.0/src/wzopensdk/__init__.py

@@ -0,0 +1,13 @@
+"""万桩开放平台 Python OpenSDK。"""
+
+from wzopensdk.client import WzOpenClient
+from wzopensdk.endpoints import Endpoints
+from wzopensdk.errors import WzOpenAPIError, WzOpenConfigError, WzOpenError
+
+__all__ = [
+    "Endpoints",
+    "WzOpenAPIError",
+    "WzOpenClient",
+    "WzOpenConfigError",
+    "WzOpenError",
+]

wz_opensdk-0.1.0/src/wzopensdk/_internal/__init__.py

@@ -0,0 +1 @@
+

wz_opensdk-0.1.0/src/wzopensdk/_internal/http.py

@@ -0,0 +1,207 @@
+"""Sign, send, retry, and decode open-platform envelopes."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Callable, TypeVar
+
+import httpx
+
+from wzopensdk._internal import params as paramx
+from wzopensdk._internal import signer
+from wzopensdk.errors import WzOpenAPIError, WzOpenError
+
+CODE_SUCCESS = 1
+HEADER_B3_TRACE_ID = "X-B3-TraceId"
+T = TypeVar("T")
+
+
+class HttpInvoker:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        app_id: str,
+        app_secret: str,
+        timeout: float = 10.0,
+        retry_count: int = 0,
+        retry_wait: float = 0.2,
+        user_agent: str = "wz-opensdk/python",
+        proxy_url: str | None = None,
+        insecure_skip_verify: bool = False,
+        logger: logging.Logger | None = None,
+        http_client: httpx.Client | None = None,
+        clock: Callable[[], int] | None = None,
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.app_id = app_id
+        self.app_secret = app_secret
+        self.timeout = timeout if timeout > 0 else 10.0
+        self.retry_count = max(0, retry_count)
+        self.retry_wait = retry_wait if retry_wait > 0 else 0.2
+        self.user_agent = user_agent or "wz-opensdk/python"
+        self.log = logger or logging.getLogger("wzopensdk")
+        self.clock = clock or (lambda: int(time.time()))
+        if http_client is not None:
+            self.http = http_client
+            self._owns_client = False
+        else:
+            self.http = httpx.Client(
+                timeout=self.timeout,
+                proxy=proxy_url,
+                verify=not insecure_skip_verify,
+            )
+            self._owns_client = True
+
+    def invoke(
+        self,
+        method: str,
+        path: str,
+        operation: str,
+        incoming: Any,
+        decode: Callable[[Any], T],
+    ) -> T:
+        business = paramx.to_params(incoming)
+        wait = self.retry_wait
+        attempts = self.retry_count + 1
+        last: WzOpenError | None = None
+        for attempt in range(attempts):
+            if attempt > 0:
+                time.sleep(wait)
+                wait *= 2
+            try:
+                return self._attempt_once(method, path, operation, business, decode)
+            except WzOpenError as exc:
+                last = exc
+                if not self._should_retry(exc) or attempt == attempts - 1:
+                    raise
+        raise last or WzOpenError("request failed")
+
+    def invoke_map(self, method: str, path: str, operation: str, incoming: Any) -> dict[str, Any] | None:
+        return self.invoke(method, path, operation, incoming, lambda data: data)
+
+    def invoke_void(self, method: str, path: str, operation: str, incoming: Any) -> None:
+        self.invoke(method, path, operation, incoming, lambda data: data)
+
+    def _attempt_once(
+        self,
+        method: str,
+        path: str,
+        operation: str,
+        business: dict[str, Any],
+        decode: Callable[[Any], T],
+    ) -> T:
+        payload = dict(business)
+        payload["app_id"] = self.app_id
+        payload["timestamp"] = self.clock()
+        payload["sign"] = signer.sign(payload, self.app_secret)
+
+        method = method.upper()
+        url = self.endpoint + path
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        request_kwargs: dict[str, Any] = {
+            "headers": headers,
+            "timeout": self.timeout,
+        }
+        if method in {"GET", "HEAD"}:
+            qs = paramx.encode_query(payload)
+            if qs:
+                url = f"{url}?{qs}"
+        else:
+            request_kwargs["json"] = payload
+            headers["Content-Type"] = "application/json"
+
+        try:
+            resp = self.http.request(method, url, **request_kwargs)
+        except httpx.TimeoutException as exc:
+            self.log.error(
+                "open api request failed method=%s path=%s operation=%s err=%s",
+                method,
+                path,
+                operation,
+                exc,
+            )
+            raise WzOpenError(f"request timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            self.log.error(
+                "open api request failed method=%s path=%s operation=%s err=%s",
+                method,
+                path,
+                operation,
+                exc,
+            )
+            raise WzOpenError(f"network error: {exc}") from exc
+
+        status = resp.status_code
+        trace_id = _response_trace_id(resp)
+        if status < 200 or status >= 300:
+            self._log_failure(method, path, operation, status, trace_id)
+            raise WzOpenAPIError.http_status(status, operation, trace_id)
+
+        try:
+            env = resp.json()
+        except json.JSONDecodeError as exc:
+            raise WzOpenError(f"decode envelope: {exc}") from exc
+        if not isinstance(env, dict):
+            raise WzOpenError("decode envelope: not an object")
+
+        code = int(env.get("code") or 0)
+        if code != CODE_SUCCESS:
+            raise WzOpenAPIError(status, code, str(env.get("message") or ""), operation, trace_id)
+
+        self._log_success(method, path, operation, status, trace_id)
+        data = env.get("data")
+        return decode(data)
+
+    def _log_success(self, method: str, path: str, operation: str, status: int, trace_id: str) -> None:
+        if trace_id:
+            self.log.info(
+                "open api request method=%s path=%s operation=%s status=%s traceId=%s",
+                method,
+                path,
+                operation,
+                status,
+                trace_id,
+            )
+            return
+        self.log.info(
+            "open api request method=%s path=%s operation=%s status=%s",
+            method,
+            path,
+            operation,
+            status,
+        )
+
+    def _log_failure(self, method: str, path: str, operation: str, status: int, trace_id: str) -> None:
+        if trace_id:
+            self.log.error(
+                "open api request failed method=%s path=%s operation=%s status=%s traceId=%s",
+                method,
+                path,
+                operation,
+                status,
+                trace_id,
+            )
+            return
+        self.log.error(
+            "open api request failed method=%s path=%s operation=%s status=%s",
+            method,
+            path,
+            operation,
+            status,
+        )
+
+    def _should_retry(self, err: WzOpenError) -> bool:
+        if isinstance(err, WzOpenAPIError):
+            return err.status >= 500
+        cause = err.__cause__
+        return isinstance(cause, httpx.HTTPError)
+
+
+def _response_trace_id(resp: httpx.Response) -> str:
+    return (resp.headers.get(HEADER_B3_TRACE_ID) or "").strip()

wz_opensdk-0.1.0/src/wzopensdk/_internal/params.py

@@ -0,0 +1,52 @@
+"""Convert request models to signed parameter maps and GET query strings."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any
+from urllib.parse import quote
+
+from wzopensdk._internal import signer
+
+
+def to_params(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        raw = value
+    elif is_dataclass(value) and not isinstance(value, type):
+        raw = asdict(value)
+    elif hasattr(value, "__dict__"):
+        raw = {k: v for k, v in vars(value).items() if not k.startswith("_")}
+    else:
+        raw = {}
+    out: dict[str, Any] = {}
+    for key, item in raw.items():
+        if signer.is_blank(item):
+            continue
+        out[str(key)] = item
+    return out
+
+
+def encode_query(params: dict[str, Any]) -> str:
+    if not params:
+        return ""
+    parts: list[str] = []
+    for key in sorted(params.keys()):
+        value = params[key]
+        if signer.is_blank(value):
+            continue
+        items = _as_slice(value)
+        if items is not None:
+            q_key = key if key.endswith("[]") else key + "[]"
+            for item in items:
+                parts.append(f"{quote(q_key, safe='')}={quote(item, safe='')}")
+            continue
+        parts.append(f"{quote(str(key), safe='')}={quote(signer.stringify(value), safe='')}")
+    return "&".join(parts)
+
+
+def _as_slice(value: Any) -> list[str] | None:
+    if isinstance(value, (list, tuple)):
+        return [signer.stringify(item) for item in value if not signer.is_blank(item)]
+    return None