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
```
