# vjmap Python SDK（单文件）

`vjmap.py` 是一个单文件 Python SDK，封装 vjmap 后端（web服务 + 图形服务）的常用 REST 接口。

## 要求

- Python ≥ 3.8
- 唯一第三方依赖：`requests`

## 安装

拷贝 `vjmap.py` 到你的项目，或：

```bash
pip install -r requirements.txt
# 把 vjmap.py 放进你的 PYTHONPATH
```

## 快速用法

```python
from vjmap import Vjmap, VjmapError, MapOpenWay

svc = Vjmap("http://127.0.0.1:27660/api/v1", "<jwt-token>")

print(svc.heart())          # {'status':'ok','timestamp':...}
print(svc.version())        # {'arch','os','status','time','version'}
print(svc.run_status())     # 详细运行状态
```

## 核心对象

| 类 / 函数 | 用途 |
|-----------|------|
| `Vjmap(base_url, token)` | 客户端主入口 |
| `VjmapError` | 统一异常，含 `.status` / `.url` / `.body` |
| `MapOpenWay.Memory` / `.GeomRender` | 打开图时的模式枚举 |
| `compute_secret_key(pwd)` | 明文密码 → 16 位 secretKey |
| `file_md5(path_or_bytes)` | 文件 MD5（32 字符 hex） |



## 错误处理

```python
try:
    svc.metadata("not_exist_map", "v1")
except VjmapError as e:
    print(e.status, e.url, e.body)
```

- web服务标准响应 `{code, msg, data}` 会自动 unwrap：成功时返回 `data`，失败（code≠0）抛 `VjmapError`。
- 图形服务 JSON 直接原样返回（部分字段结构依 cmd 不同）。
- 二进制接口（瓦片 / 缩略图 / 导出 PDF）用 `stream=True` 走底层 `_request` 或后续追加的 `*_bytes` 方法。