py_wisharetec_toolkit

浙江慧享科技有限公司 - 善数・慧享云运营平台 Python 扩展包。

本包封装了善数・慧享云运营平台 (https://saas.wisharetec.com/) 的各类 API 接口，提供同步客户端 ShanshuClient 和异步客户端 AsyncShanshuClient，供他人调用。

作者：guolei 174000902@qq.com
项目主页：https://gitee.com/guolei19850528/py_wisharetec_toolkit

安装

pip install py_wisharetec_toolkit

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

pip install -e .

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

pip install py_wisharetec_toolkit[cache]

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

pip install -e ".[cache]"

快速开始

同步客户端

from py_wisharetec_toolkit.shanshu.client import ShanshuClient
from py_wisharetec_toolkit.shanshu.auth import DiskCacheTokenCache

# 从环境变量读取账号和密码（不建议在代码中硬编码）
import os

account = os.environ.get("SHANSHU_TEST_ACCOUNT", "")
password = os.environ.get("SHANSHU_TEST_PASSWORD", "")

# 创建客户端（token 自动缓存到 diskcache）
token_cache = DiskCacheTokenCache(cache_dir=".runtime/cache/diskcache", table="token")
client = ShanshuClient(
    account=account,
    password=password,
    token_cache=token_cache,
)

# 登录
client.login(account, password)

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

client.close()

异步客户端

import asyncio
import os
from py_wisharetec_toolkit.shanshu.auth import DiskCacheTokenCache
from py_wisharetec_toolkit.shanshu.client import AsyncShanshuClient
from py_wisharetec_toolkit.shanshu.models import PageQueryParams

async def main():
    token_cache = DiskCacheTokenCache(cache_dir=".runtime/cache/diskcache", table="token")
    account = os.environ.get("SHANSHU_TEST_ACCOUNT", "")
    password = os.environ.get("SHANSHU_TEST_PASSWORD", "")
    
    async with AsyncShanshuClient(
        account=account,
        password=password,
        token_cache=token_cache,
    ) as client:
        await client.async_login(account, password)
        
        params = PageQueryParams(
            conditions={
                "fields": [
                    {"map": {}, "method": 1, "name": "spaceTreeId", "value": "73"},
                    {"map": {}, "method": 1, "name": "flag", "value": 0},
                ]
            },
            page_num=1,
            page_size=20,
        )
        resp = await client.async_query_community_with_paginator(params=params)
        print(resp.ok, resp.total, len(resp.records))

asyncio.run(main())

已实现的接口

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

Token 缓存

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

• MemoryTokenCache：进程内内存缓存（默认，无需额外依赖）
• DiskCacheTokenCache：基于 diskcache 的持久化缓存（默认依赖）
• RedisTokenCache：基于 redis 的缓存（默认依赖）

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

目录结构

src/py_wisharetec_toolkit/
├── __init__.py          # 顶层包
├── py.typed             # PEP 561 类型标记
└── shanshu/             # 子包，供他人调用
    ├── __init__.py
    ├── client.py        # 同步客户端 ShanshuClient
    ├── async_client.py  # 异步客户端 AsyncShanshuClient（已合并到 client.py）
    ├── auth.py          # Token 缓存与认证
    ├── models.py        # pydantic 响应模型
    └── hello.py         # 示例模块

参数说明

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

许可证

MIT License