Metadata-Version: 2.4
Name: py-easy-wisharetec
Version: 1.1.5
Summary: 一个用于 慧享 开放平台集成的 Python 包，提供简洁易用的 API 接口，支持同步和异步操作，帮助开发者快速实现 wisharetec 相关功能。
Home-page: https://gitee.com/guolei19850528/py_easy_wisharetec
Author: guolei
Author-email: 174000902@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: diskcache
Requires-Dist: redis
Requires-Dist: jsonschema
Requires-Dist: jsonpath-ng
Requires-Dist: py-easy-httpx
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# py_easy_wisharetec

一个与 Wisharetec SaaS 系统交互的 Python 工具包，提供了便捷的认证、数据查询和缓存管理功能。

## 功能特性

- **认证管理**：支持 SaaS 系统登录和 token 缓存
- **数据查询**：提供多种业务数据的查询方法
- **缓存支持**：支持 diskcache 和 redis 缓存
- **同步请求**：基于 httpx 实现的同步 HTTP 请求
- **响应处理**：提供 JSON 数据验证和提取功能
- **类型提示**：完整的类型注解，提供良好的 IDE 支持

## 安装

### 使用 pip 安装

```bash
pip install py_easy_wisharetec
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_easy_wisharetec.git
cd py_easy_wisharetec
pip install -e .
```

## 依赖

- httpx
- diskcache
- redis
- py_easy_httpx

## 快速开始

### 基本用法

#### 初始化 Saas 实例

```python
from py_easy_wisharetec.saas import Saas
import diskcache

# 初始化缓存实例
diskcache_default = diskcache.Cache("./runtime/diskcache/default")

# 初始化 Saas 实例
saas = Saas(
    account="your_account",
    password="your_password",
    cache_config={
        "instance": diskcache_default
    }
)
```

#### 登录并刷新 token

```python
# 刷新登录状态（如果缓存中有 token 则使用缓存，否则重新登录）
saas.refresh_login()

# 现在可以使用 saas 实例进行各种查询操作
```

#### 使用 QueryConditionFormatter 构建查询条件

```python
from py_easy_wisharetec.saas import QueryConditionFormatter

# 构建查询条件
query_condition = QueryConditionFormatter(
    conditions={
        "fields": [
            {
                "method": 1,
                "name": "sysStatus",
                "map": {},
                "value": "1"
            }
        ]
    },
    pageSize=100
)

# 转换为字典格式
query_dict = query_condition.to_dict()
```

#### 查询数据

```python
# 查询停车审批列表
response = saas.query_parking_approvals(json=query_dict)
print(response)

# 查询业主列表
response = saas.query_property_owners(json=query_dict)
print(response)

# 查询车辆列表
response = saas.query_cars(json=query_dict)
print(response)
```

## API 文档

### Saas 类

#### 初始化参数
- `base_url`：SaaS 系统基础 URL，默认为 "https://saas.wisharetec.com/"
- `account`：登录账号
- `password`：登录密码
- `cache_config`：缓存配置字典
- `client_kwargs`：客户端配置字典

#### 主要方法

##### 认证相关
- `login(client=None, **kwargs)`：登录 SaaS 系统
- `refresh_login(client=None, login_kwargs=None, query_manage_tree_kwargs=None)`：刷新登录状态

##### 数据查询
- `query_manage_tree(client=None, **kwargs)`：查询管理树
- `query_property_owners(client=None, **kwargs)`：查询业主列表
- `query_property_owner(client=None, user_id=None, company_id=None, **kwargs)`：查询业主详情
- `query_cars(client=None, **kwargs)`：查询车辆列表
- `query_car(client=None, id=None, **kwargs)`：查询车辆详情
- `query_parking_spaces(client=None, **kwargs)`：查询停车位列表
- `query_parking_space(client=None, id=None, **kwargs)`：查询停车位详情
- `query_parking_lots(client=None, **kwargs)`：查询停车场列表
- `query_parking_lot(client=None, id=None, **kwargs)`：查询停车场详情
- `query_parking_approvals(client=None, **kwargs)`：查询停车审批列表
- `query_parking_approval(client=None, id=None, **kwargs)`：查询停车审批详情
- `update_parking_approval(client=None, **kwargs)`：更新停车审批状态
- `query_shop_orders(client=None, **kwargs)`：查询商城订单列表
- `query_shop_order(client=None, id=None, **kwargs)`：查询商城订单详情
- `query_service_orders(client=None, **kwargs)`：查询服务订单列表
- `query_service_order(client=None, id=None, **kwargs)`：查询服务订单详情

### QueryConditionFormatter 类

#### 初始化参数
- `conditions`：查询条件字典，默认为空字典
- `count`：是否返回总记录数，默认为 True
- `last`：是否返回最后一页，默认为 True
- `orderBy`：排序字段列表，默认为空列表
- `pageNum`：页码，默认为 1
- `pageSize`：每页记录数，默认为 50

#### 方法
- `to_dict()`：将查询条件转换为字典格式

## 高级用法

### 缓存配置

```python
import diskcache
import redis
from py_easy_wisharetec.saas import Saas

# 使用 diskcache 缓存
diskcache_instance = diskcache.Cache("./runtime/diskcache/default")
saas_with_diskcache = Saas(
    account="your_account",
    password="your_password",
    cache_config={
        "instance": diskcache_instance,
        "key": "py_easy_wisharetec_saas_your_account",
        "expire": 86400 * 180  # 180天
    }
)

# 使用 redis 缓存
redis_instance = redis.Redis(host="localhost", port=6379, db=0)
saas_with_redis = Saas(
    account="your_account",
    password="your_password",
    cache_config={
        "instance": redis_instance,
        "key": "py_easy_wisharetec_saas_your_account",
        "expire": 86400 * 180  # 180天
    }
)
```

### 自定义客户端配置

```python
from py_easy_wisharetec.saas import Saas

# 初始化 Saas 实例，配置默认客户端参数
saas = Saas(
    account="your_account",
    password="your_password",
    client_kwargs={
        "timeout": 600,  # 10分钟超时
        "headers": {
            "client": "co-pc",
            "User-Agent": "py_easy_wisharetec"
        }
    }
)
```

## 项目结构

```
py_easy_wisharetec/
├── py_easy_wisharetec/              # 主包目录
│   ├── __init__.py                  # 包初始化文件
│   └── saas.py                      # SaaS 系统交互模块
├── runtime/                         # 运行时目录
│   └── diskcache/                   # 缓存目录
├── README.md                        # 项目文档
├── setup.py                         # 安装配置
├── requirements.txt                 # 依赖列表
├── LICENSE                          # 许可证文件
├── deploy.sh                        # 部署脚本
├── test_saas.py                     # 测试文件
└── .gitignore                       # Git 忽略文件
```

## 测试

运行测试：

```bash
# 运行测试
python -m pytest
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

- 作者：guolei
- 邮箱：174000902@qq.com
- 项目地址：https://gitee.com/guolei19850528/py_easy_wisharetec

## 致谢

- [httpx](https://www.python-httpx.org/) - 高性能的异步 HTTP 客户端库
- [diskcache](https://github.com/grantjenkins/diskcache) - 磁盘缓存库
- [redis](https://redis.io/) - 内存数据库，用于缓存
- [py_easy_httpx](https://gitee.com/guolei19850528/py_easy_httpx) - 简化 httpx 使用的工具包
