py_easy_wisharetec

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

功能特性

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

安装

使用 pip 安装

pip install py_easy_wisharetec

从源码安装

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

依赖

• httpx
• diskcache
• redis
• py_easy_httpx

快速开始

基本用法

初始化 Saas 实例

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

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

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

使用 QueryConditionFormatter 构建查询条件

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()

查询数据

# 查询停车审批列表
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()：将查询条件转换为字典格式

高级用法

缓存配置

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天
    }
)

自定义客户端配置

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 忽略文件

测试

运行测试：

# 运行测试
python -m pytest

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

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

致谢

• httpx - 高性能的异步 HTTP 客户端库
• diskcache - 磁盘缓存库
• redis - 内存数据库，用于缓存
• py_easy_httpx - 简化 httpx 使用的工具包