Metadata-Version: 2.4
Name: py_wisharetec_toolkit
Version: 3.0.8
Summary: 浙江慧享科技有限公司 - 善数・慧享云运营平台 Python 扩展包，提供接口调用封装
Author-email: 郭磊 <174000902@qq.com>
License: MIT License
        
        Copyright (c) 2026 guolei
        
        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://gitee.com/guolei19850528/py_wisharetec_toolkit
Project-URL: Repository, https://gitee.com/guolei19850528/py_wisharetec_toolkit
Project-URL: Package, https://pypi.org/project/py-wisharetec-toolkit/
Keywords: wisharetec,wisharetec_toolkit,shanshu,saas.wisharetec.com,saas toolkit
Classifier: Development Status :: 4 - Beta
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
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: cache
Requires-Dist: diskcache>=5.0.0; extra == "cache"
Requires-Dist: redis>=5.0.0; extra == "cache"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Dynamic: license-file

# py_wisharetec_toolkit

[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-py--wisharetec--toolkit-blue.svg)](https://pypi.org/project/py-wisharetec-toolkit/)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)

## 文档语言

- [中文 (README.md)](README.md)
- [English (README.en.md)](README.en.md)

## 介绍

**py_wisharetec_toolkit** 是浙江慧享科技有限公司 - 善数・慧享云运营平台的 Python 扩展包，封装了善数・慧享云运营平台 (https://saas.wisharetec.com/) 的各类 API 接口。

本包提供同步客户端 `ShanshuClient` 和异步客户端 `AsyncShanshuClient`，方法名完全一致，支持 `with` / `async with` 上下文管理器，让你极其简单地与慧享云平台 API 交互。无需手动拼接 URL，无需手动构建 JSON 负载，自动缓存 access_token，支持同步和异步客户端。

### 核心特性

- **双模客户端**：同时提供同步（`ShanshuClient`）与异步（`AsyncShanshuClient`）客户端，方法名完全一致（异步方法已去掉 `async_` 前缀），支持 `with` / `async with` 上下文管理器。
- **全平台接口封装**：涵盖登录、园区/房产/车场/楼幢/住户/业主/车辆/车位/工单/商城订单/服务订单/审批等档案与业务接口，全部基于 Pydantic 模型封装返回。
- **分页查询统一模型**：所有分页接口均使用 `ShanshuPageQueryParams` 模型封装查询参数，包含 `conditions`、`count`、`last`、`order_by`、`page_num`、`page_size` 字段。
- **自动缓存 access_token**：支持内存（默认）、diskcache、Redis 三种缓存后端，自动处理 token 过期与刷新。
- **基于 httpx**：底层 HTTP 客户端使用 httpx，支持同步与异步请求。

### 参考文档

- [善数・慧享云运营平台](https://saas.wisharetec.com/)

## 软件架构

```
py_wisharetec_toolkit/
├── README.md                   # 项目说明文档（中文）
├── README.en.md                # 项目说明文档（英文）
├── pyproject.toml              # 项目构建配置（PEP 621 / setuptools）
├── LICENSE                     # MIT 许可证
├── uv.lock                     # 依赖锁定文件
├── src/
│   └── py_wisharetec_toolkit/  # 源代码包
│       ├── __init__.py         # 包入口
│       ├── py.typed            # PEP 561 类型标记
│       └── shanshu/            # 子包，供他人调用
│           ├── __init__.py
│           ├── client.py       # 同步客户端 ShanshuClient 与异步客户端 AsyncShanshuClient
│           ├── auth.py         # Token 缓存与认证
│           └── models.py       # pydantic 响应模型
├── tests/                      # 测试用例
│   └── shanshu/
│       ├── conftest.py         # 公共夹具（客户端、登录、查询条件）
│       ├── .env.example        # 测试配置模板
│       └── test_*.py           # 各接口的同步 / 异步测试用例
└── examples/                   # 演示代码
    └── shanshu/
        ├── .env.example        # 示例配置模板
        ├── example_common.py   # 示例公共辅助
        ├── example_*.py        # 各接口同步示例
        └── example_async_*.py  # 各接口异步示例
```

## 安装教程

推荐使用 [uv](https://github.com/astral-sh/uv) 进行安装：

### 1. 基础安装（推荐 uv）

```bash
uv pip install py_wisharetec_toolkit
```

或从本地源码安装（开发模式）：

```bash
uv pip install -e .
```

带缓存依赖安装（diskcache / redis）：

```bash
uv pip install py_wisharetec_toolkit[cache]
```

或从本地源码安装（开发模式，带缓存依赖）：

```bash
uv pip install -e ".[cache]"
```

### 2. 或者使用 pip 安装

```bash
pip install py_wisharetec_toolkit
```

或从本地源码安装（开发模式）：

```bash
pip install -e .
```

带缓存依赖安装（diskcache / redis）：

```bash
pip install py_wisharetec_toolkit[cache]
```

或从本地源码安装（开发模式，带缓存依赖）：

```bash
pip install -e ".[cache]"
```

## 使用说明

### 快速开始

```python
from py_wisharetec_toolkit.shanshu.client import ShanshuClient
from py_wisharetec_toolkit.shanshu.models import ShanshuPageQueryParams

# 创建同步客户端
client = ShanshuClient(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password",
)

# 登录
resp = client.login("your_account", "your_password")
print(resp.ok)

# 查询园区档案
params = ShanshuPageQueryParams(
    conditions={
        "fields": [
            {"map": {}, "method": 1, "name": "spaceTreeId", "value": "73"},
            {"map": {}, "method": 1, "name": "flag", "value": 0},
        ]
    },
    page_num=1,
    page_size=20,
)
result = client.query_community_with_paginator(params=params)
print(result.ok, result.total, len(result.records or []))

client.close()
```

> 注意：账号、密码等敏感信息请通过环境变量（`.env` 文件）配置，勿硬编码在代码中。测试用例请参考 `tests/shanshu/.env.example`，示例代码请参考 `examples/shanshu/.env.example`。

### 创建客户端

```python
from py_wisharetec_toolkit.shanshu.client import ShanshuClient, AsyncShanshuClient

# 同步客户端
client = ShanshuClient(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password",
)

# 异步客户端
async_client = AsyncShanshuClient(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password",
)
```

推荐使用上下文管理器，自动管理 HTTP 连接池：

```python
with ShanshuClient(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password",
) as client:
    # 使用 client 调用接口
    pass

async with AsyncShanshuClient(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password",
) as client:
    # 使用 client 调用接口
    pass
```

## 已实现的接口

| 接口 | 方法 | 路径 | 返回模型 |
|------|------|------|----------|
| 登录 | `login` | `/api/user/loginInteractive` | `ShanshuLoginResponse` |
| 园区档案 | `query_community_with_paginator` | `/api/space/community/v2/frontPage` | `ShanshuCommunityPageResponse` |
| 房产档案 | `query_property_with_paginator` | `/api/space/property/propertyPage` | `ShanshuPropertyPageResponse` |
| 车场档案 | `query_yard_archive_with_paginator` | `/api/space/space/yardArchivePage` | `ShanshuYardArchivePageResponse` |
| 楼幢档案 | `query_building_with_paginator` | `/api/space/property/getSpaceBuildingPage` | `ShanshuBuildingPageResponse` |
| 住户档案 | `query_resident_with_paginator` | `/api/user/residentInfo/getResidentPage` | `ShanshuResidentPageResponse` |
| 业主档案 | `query_archive_with_paginator` | `/api/space/archive/examine/page` | `ShanshuArchivePageResponse` |
| 车辆档案 | `query_car_manage_with_paginator` | `/api/space/carManage/pageCarManage` | `ShanshuCarManagePageResponse` |
| 车位档案 | `query_parking_with_paginator` | `/api/space/parking/parkingPage` | `ShanshuParkingPageResponse` |
| 工单档案 | `query_work_order_with_paginator` | `/api/woreport/task/query/page` | `ShanshuWorkOrderPageResponse` |
| 商城订单 | `query_mall_order_with_paginator` | `/api/retailmall/order/pageFront` | `ShanshuMallOrderPageResponse` |
| 服务订单 | `query_service_order_with_paginator` | `/api/houseserve/order/pageFront` | `ShanshuServiceOrderPageResponse` |
| 审批数据 | `query_approval_with_paginator` | `/api/bpm/process/approval` | `ShanshuApprovalPageResponse` |
| 审批详情 | `query_approval_detail` | `/api/bpm/process/progress/{instance_id}/node_433279443693` | `ShanshuApprovalDetailRecord` |
| 业主详情 | `query_owner_detail` | `/api/space/archive/archive/detailSensitive` | `ShanshuOwnerDetailRecord` |

同步客户端 `ShanshuClient` 与异步客户端 `AsyncShanshuClient` 方法名完全一致（异步方法已去掉 `async_` 前缀），异步客户端支持 `async with` 上下文管理器。

所有分页接口均使用 `ShanshuPageQueryParams` 模型封装查询参数，包含 `conditions`、`count`、`last`、`order_by`、`page_num`、`page_size` 字段。

### 接口注意事项

- 园区、房产、楼幢、车场、业主、车辆、车位、审批等接口的 `conditions` 需携带 `spaceTreeId` 与 `flag`。
- 住户档案接口需传入空条件：`conditions={}`；商城订单、服务订单接口需传入 `conditions={"fields": []}`（不能携带 `spaceTreeId`、`flag`，否则后端返回“系统内部报错”）。
- 工单档案接口要求 `conditions` 中额外携带 `appCode=WORK_ORDER`。
- 审批详情需先通过审批列表接口获取 `procInstId`，节点 ID 固定为 `node_433279443693`；业主详情需先获取 `userId` / `communityId` / `spaceId`，再调用详情接口。

## 参数说明

所有分页查询接口均使用 `ShanshuPageQueryParams` 模型：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| conditions | dict\|None | None | 查询条件 |
| count | bool | True | 是否返回总记录数 |
| last | bool | True | 是否返回 last 标志 |
| order_by | list\|None | None | 排序字段列表 |
| page_num | int | 1 | 页码 |
| page_size | int | 20 | 每页大小 |

## 示例代码 (`examples/`)

完整可运行示例位于 `examples/shanshu/`，覆盖全部接口的同步与异步调用，文件命名规则为 `example_*.py`（同步）与 `example_async_*.py`（异步）。

运行示例前，请复制模板并填写真实账号：

```bash
cp examples/shanshu/.env.example examples/shanshu/.env
```

运行示例（以园区档案为例）：

```bash
python examples/shanshu/example_community_page.py
python examples/shanshu/example_async_community_page.py
```

公共配置与查询条件集中在 `examples/shanshu/example_common.py`，统一从 `examples/shanshu/.env` 读取 `SHANSHU_*` 变量。

### 示例文件列表

| 同步示例 | 异步示例 | 说明 |
|----------|----------|------|
| `example_login.py` | `example_async_login.py` | 登录接口 |
| `example_community_page.py` | `example_async_community_page.py` | 园区档案列表 |
| `example_property_page.py` | `example_async_property_page.py` | 房产档案列表 |
| `example_yard_archive_page.py` | `example_async_yard_archive_page.py` | 车场档案列表 |
| `example_building_page.py` | `example_async_building_page.py` | 楼幢档案列表 |
| `example_resident_page.py` | `example_async_resident_page.py` | 住户档案列表 |
| `example_archive_page.py` | `example_async_archive_page.py` | 业主档案列表 |
| `example_car_manage_page.py` | `example_async_car_manage_page.py` | 车辆档案列表 |
| `example_parking_page.py` | `example_async_parking_page.py` | 车位档案列表 |
| `example_work_order_page.py` | `example_async_work_order_page.py` | 工单档案列表 |
| `example_mall_order_page.py` | `example_async_mall_order_page.py` | 商城订单列表 |
| `example_service_order_page.py` | `example_async_service_order_page.py` | 服务订单列表 |
| `example_approval_page.py` | `example_async_approval_page.py` | 审批数据列表 |
| `example_approval_detail.py` | `example_async_approval_detail.py` | 审批详情 |
| `example_owner_detail.py` | `example_async_owner_detail.py` | 业主详情 |

## 测试 (`tests/`)

测试用例位于 `tests/shanshu/`，基于 pytest + pytest-asyncio，统一从 `tests/shanshu/.env` 读取配置，公共夹具定义在 `tests/shanshu/conftest.py`。

运行测试前，请复制模板并填写真实账号：

```bash
cp tests/shanshu/.env.example tests/shanshu/.env
```

安装测试依赖并运行：

```bash
uv pip install -e ".[dev,cache]"
pytest tests/shanshu -q
```

未配置 `SHANSHU_ACCOUNT` / `SHANSHU_PASSWORD` 时，测试会自动跳过。

### 测试文件列表

- `test_login.py` / `test_async_login.py`：登录接口
- `test_community_page.py` / `test_async_community_page.py`：园区档案列表
- `test_property_page.py` / `test_async_property_page.py`：房产档案列表
- `test_yard_archive_page.py` / `test_async_yard_archive_page.py`：车场档案列表
- `test_building_page.py` / `test_async_building_page.py`：楼幢档案列表
- `test_resident_page.py` / `test_async_resident_page.py`：住户档案列表
- `test_archive_page.py` / `test_async_archive_page.py`：业主档案列表
- `test_car_manage_page.py` / `test_async_car_manage_page.py`：车辆档案列表
- `test_parking_page.py` / `test_async_parking_page.py`：车位档案列表
- `test_work_order_page.py` / `test_async_work_order_page.py`：工单档案列表
- `test_mall_order_page.py` / `test_async_mall_order_page.py`：商城订单列表
- `test_service_order_page.py` / `test_async_service_order_page.py`：服务订单列表
- `test_approval_page.py` / `test_async_approval_page.py`：审批数据列表
- `test_approval_detail.py` / `test_async_approval_detail.py`：审批详情
- `test_owner_detail.py` / `test_async_owner_detail.py`：业主详情

## Token 缓存

客户端支持三种 Token 缓存后端：

- `ShanshuMemoryTokenCache`：进程内内存缓存（默认，无需额外依赖）
- `ShanshuDiskCacheTokenCache`：基于 diskcache 的持久化缓存（需安装 `[cache]` 依赖）
- `ShanshuRedisTokenCache`：基于 redis 的缓存（需安装 `[cache]` 依赖）

缓存 key 格式：`py_wisharetec_toolkit:shanshu:authorization:{account}`，便于缓存不同用户的登录 token。

## 贡献指南

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

本项目采用 [MIT 许可证](LICENSE)。
