py-wisharetec-toolkit 1.0.0__tar.gz

py_wisharetec_toolkit-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 郭磊
+
+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.

py_wisharetec_toolkit-1.0.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: py-wisharetec-toolkit
+Version: 1.0.0
+Summary: Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。
+Author-email: Guolei <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 郭磊
+        
+        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.git
+Keywords: wisharetec,python,client,api,wisharetec saas,saas
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: redis>=4.6.0
+Requires-Dist: py-httpx-toolkit>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# py-wisharetec-toolkit
+
+Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。
+
+## 功能特性
+
+- 封装 SaaS 系统的认证机制，包括登录、令牌刷新和令牌缓存
+- 提供同步和异步两种 HTTP 请求模式
+- 集成 JSON Schema 校验和 JSONPath 查询工具
+- 支持 diskcache 和 Redis 两种缓存后端
+
+## 安装
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-wisharetec-toolkit
+```
+
+### 使用 pip
+
+```bash
+pip install py-wisharetec-toolkit
+```
+
+## 依赖包
+
+| 依赖包 | 版本要求 | 说明 |
+|--------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端库，支持同步和异步请求 |
+| pydantic | >=2.0 | 数据验证和序列化 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询工具 |
+| jsonschema | >=4.21.0 | JSON Schema 校验 |
+| diskcache | >=5.6.3 | 本地磁盘缓存 |
+| redis | >=4.6.0 | Redis 缓存支持 |
+| py-httpx-toolkit | >=1.0.0 | HTTP 请求工具封装 |
+
+## API 说明
+
+### Saas 类
+
+#### 初始化
+
+```python
+from py_wisharetec_toolkit.saas import Saas
+
+saas = Saas(
+    base_url="https://saas.wisharetec.com/",
+    account="your_account",
+    password="your_password",
+    cache_config={
+        "instance": None,  # diskcache.Cache 或 redis.Redis 实例
+        "key": "py_wisharetec_saas_account",
+        "expire": 7100,
+    },
+    client_kwargs={
+        "timeout": 60,
+        "verify": False,
+    }
+)
+```
+
+#### 同步方法
+
+| 方法 | 说明 |
+|------|------|
+| `login()` | 用户登录，获取认证 Token |
+| `refresh_token()` | 智能刷新 Token（支持缓存） |
+| `query_space_manage_tree()` | 查询空间管理树结构 |
+| `request_with_token()` | 发送带授权头的请求 |
+
+#### 异步方法
+
+| 方法 | 说明 |
+|------|------|
+| `async_login()` | 异步用户登录 |
+| `async_refresh_token()` | 异步智能刷新 Token |
+| `async_query_space_manage_tree()` | 异步查询空间管理树 |
+| `async_request_with_token()` | 异步发送带授权头的请求 |
+
+## utils 工具函数
+
+### json_find_first
+
+使用 JSONPath 表达式从 JSON 数据中查找第一个匹配项。
+
+```python
+from py_wisharetec_toolkit.saas.utils import json_find_first
+
+data = {"userInfoV": {"id": "123"}}
+result = json_find_first("$.userInfoV.id", data)
+# 返回: "123"
+```
+
+### json_is_valid
+
+校验 JSON 数据是否符合指定的 JSON Schema。
+
+```python
+from py_wisharetec_toolkit.saas.utils import json_is_valid
+
+schema = {
+    "type": "object",
+    "properties": {"id": {"type": "string"}},
+    "required": ["id"]
+}
+data = {"id": "123"}
+result = json_is_valid(schema, data)
+# 返回: True
+```
+
+## 使用示例
+
+### 同步方式
+
+```python
+from py_wisharetec_toolkit.saas import Saas
+
+saas = Saas(
+    account="test",
+    password="password"
+)
+
+# 登录获取 Token
+saas.login()
+
+# 发送请求
+response = saas.request_with_token(
+    method="GET",
+    url="/api/data/list"
+)
+print(response.json())
+```
+
+### 异步方式
+
+```python
+import asyncio
+from py_wisharetec_toolkit.saas import Saas
+
+async def main():
+    saas = Saas(
+        account="test",
+        password="password"
+    )
+    
+    # 异步登录
+    await saas.async_login()
+    
+    # 异步发送请求
+    response = await saas.async_request_with_token(
+        method="GET",
+        url="/api/data/list"
+    )
+    print(response.json())
+
+asyncio.run(main())
+```
+
+### 使用缓存
+
+```python
+import diskcache
+from py_wisharetec_toolkit.saas import Saas
+
+cache = diskcache.Cache("./cache")
+
+saas = Saas(
+    account="test",
+    password="password",
+    cache_config={
+        "instance": cache,
+        "key": "saas_token",
+        "expire": 7100
+    }
+)
+
+# 自动从缓存获取或刷新 Token
+saas.refresh_token()
+```
+
+## 作者
+
+**Guolei**
+
+- 邮箱: 174000902@qq.com
+
+## 项目主页
+
+- **Gitee**: [https://gitee.com/guolei19850528/py_wisharetec_toolkit](https://gitee.com/guolei19850528/py_wisharetec_toolkit)
+
+## 许可证
+
+MIT License

py_wisharetec_toolkit-1.0.0/README.md

@@ -0,0 +1,194 @@
+# py-wisharetec-toolkit
+
+Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。
+
+## 功能特性
+
+- 封装 SaaS 系统的认证机制，包括登录、令牌刷新和令牌缓存
+- 提供同步和异步两种 HTTP 请求模式
+- 集成 JSON Schema 校验和 JSONPath 查询工具
+- 支持 diskcache 和 Redis 两种缓存后端
+
+## 安装
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-wisharetec-toolkit
+```
+
+### 使用 pip
+
+```bash
+pip install py-wisharetec-toolkit
+```
+
+## 依赖包
+
+| 依赖包 | 版本要求 | 说明 |
+|--------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端库，支持同步和异步请求 |
+| pydantic | >=2.0 | 数据验证和序列化 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询工具 |
+| jsonschema | >=4.21.0 | JSON Schema 校验 |
+| diskcache | >=5.6.3 | 本地磁盘缓存 |
+| redis | >=4.6.0 | Redis 缓存支持 |
+| py-httpx-toolkit | >=1.0.0 | HTTP 请求工具封装 |
+
+## API 说明
+
+### Saas 类
+
+#### 初始化
+
+```python
+from py_wisharetec_toolkit.saas import Saas
+
+saas = Saas(
+    base_url="https://saas.wisharetec.com/",
+    account="your_account",
+    password="your_password",
+    cache_config={
+        "instance": None,  # diskcache.Cache 或 redis.Redis 实例
+        "key": "py_wisharetec_saas_account",
+        "expire": 7100,
+    },
+    client_kwargs={
+        "timeout": 60,
+        "verify": False,
+    }
+)
+```
+
+#### 同步方法
+
+| 方法 | 说明 |
+|------|------|
+| `login()` | 用户登录，获取认证 Token |
+| `refresh_token()` | 智能刷新 Token（支持缓存） |
+| `query_space_manage_tree()` | 查询空间管理树结构 |
+| `request_with_token()` | 发送带授权头的请求 |
+
+#### 异步方法
+
+| 方法 | 说明 |
+|------|------|
+| `async_login()` | 异步用户登录 |
+| `async_refresh_token()` | 异步智能刷新 Token |
+| `async_query_space_manage_tree()` | 异步查询空间管理树 |
+| `async_request_with_token()` | 异步发送带授权头的请求 |
+
+## utils 工具函数
+
+### json_find_first
+
+使用 JSONPath 表达式从 JSON 数据中查找第一个匹配项。
+
+```python
+from py_wisharetec_toolkit.saas.utils import json_find_first
+
+data = {"userInfoV": {"id": "123"}}
+result = json_find_first("$.userInfoV.id", data)
+# 返回: "123"
+```
+
+### json_is_valid
+
+校验 JSON 数据是否符合指定的 JSON Schema。
+
+```python
+from py_wisharetec_toolkit.saas.utils import json_is_valid
+
+schema = {
+    "type": "object",
+    "properties": {"id": {"type": "string"}},
+    "required": ["id"]
+}
+data = {"id": "123"}
+result = json_is_valid(schema, data)
+# 返回: True
+```
+
+## 使用示例
+
+### 同步方式
+
+```python
+from py_wisharetec_toolkit.saas import Saas
+
+saas = Saas(
+    account="test",
+    password="password"
+)
+
+# 登录获取 Token
+saas.login()
+
+# 发送请求
+response = saas.request_with_token(
+    method="GET",
+    url="/api/data/list"
+)
+print(response.json())
+```
+
+### 异步方式
+
+```python
+import asyncio
+from py_wisharetec_toolkit.saas import Saas
+
+async def main():
+    saas = Saas(
+        account="test",
+        password="password"
+    )
+    
+    # 异步登录
+    await saas.async_login()
+    
+    # 异步发送请求
+    response = await saas.async_request_with_token(
+        method="GET",
+        url="/api/data/list"
+    )
+    print(response.json())
+
+asyncio.run(main())
+```
+
+### 使用缓存
+
+```python
+import diskcache
+from py_wisharetec_toolkit.saas import Saas
+
+cache = diskcache.Cache("./cache")
+
+saas = Saas(
+    account="test",
+    password="password",
+    cache_config={
+        "instance": cache,
+        "key": "saas_token",
+        "expire": 7100
+    }
+)
+
+# 自动从缓存获取或刷新 Token
+saas.refresh_token()
+```
+
+## 作者
+
+**Guolei**
+
+- 邮箱: 174000902@qq.com
+
+## 项目主页
+
+- **Gitee**: [https://gitee.com/guolei19850528/py_wisharetec_toolkit](https://gitee.com/guolei19850528/py_wisharetec_toolkit)
+
+## 许可证
+
+MIT License

py_wisharetec_toolkit-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "py-wisharetec-toolkit"
+version = "1.0.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Guolei", email = "174000902@qq.com" }
+]
+description = "Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。"
+keywords = ["wisharetec", "python", "client", "api", "wisharetec saas", "saas"]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0",
+    "jsonpath-ng>=1.5.3",
+    "jsonschema>=4.21.0",
+    "diskcache>=5.6.3",
+    "redis>=4.6.0",
+    "py-httpx-toolkit>=1.0.0",
+]
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "setuptools>=61.0",
+    "twine>=4.0",
+]
+
+[project.urls]
+"Homepage" = "https://gitee.com/guolei19850528/py_wisharetec_toolkit"
+"Repository" = "https://gitee.com/guolei19850528/py_wisharetec_toolkit.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]

py_wisharetec_toolkit-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit/__init__.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+py_wisharetec 包入口模块
+
+Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。
+
+主要功能：
+- 封装 SaaS 系统的认证机制，包括登录、令牌刷新和令牌缓存
+- 提供同步和异步两种 HTTP 请求模式
+- 集成 JSON Schema 校验和 JSONPath 查询工具
+- 支持 diskcache 和 Redis 两种缓存后端
+
+子模块说明：
+- saas: 核心 SaaS 客户端实现，包含 Saas 类和工具函数
+- saas.utils: 工具函数模块，提供 JSON 数据处理相关功能
+"""

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit/saas/__init__.py

@@ -0,0 +1,523 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+import hashlib
+from typing import Optional, Union
+
+import diskcache
+import httpx
+import redis
+from py_httpx_toolkit import Httpx
+
+from .utils import json_is_valid
+
+
+class Saas(Httpx):
+    """
+    SaaS系统客户端类，继承自Httpx，提供与Wisharetec SaaS平台的交互能力
+
+    主要功能包括：
+    - 用户登录认证
+    - Token管理与自动刷新
+    - 请求授权头自动添加
+    - 支持同步和异步请求
+    - 支持缓存Token（Redis/diskcache）
+    """
+
+    def __init__(
+            self,
+            base_url: Optional[str] = "https://saas.wisharetec.com/",
+            account: Optional[str] = None,
+            password: Optional[str] = None,
+            cache_config: Optional[dict] = None,
+            client_kwargs: Optional[dict] = None
+    ):
+        """
+        初始化SaaS客户端
+
+        :param base_url: SaaS平台基础URL，默认为"https://saas.wisharetec.com/"
+        :param account: 用户账号
+        :param password: 用户密码（明文，内部会进行MD5加密）
+        :param cache_config: 缓存配置字典，支持以下键：
+            - instance: 缓存实例（diskcache.Cache或redis.Redis），为None时不使用缓存
+            - key: 缓存键名，默认为"py_wisharetec_saas_{account}"
+            - expire: 缓存过期时间（秒），默认为7100秒
+        :param client_kwargs: httpx客户端配置参数，会覆盖默认配置
+        """
+        # 处理基础URL，移除末尾斜杠保证URL格式统一
+        self.base_url = base_url or "https://saas.wisharetec.com/"
+        self.base_url = self.base_url[:-1] if self.base_url.endswith("/") else self.base_url
+
+        # 存储账号密码（密码在请求时进行MD5加密）
+        self.account = account or ""
+        self.password = password or ""
+
+        # 配置缓存参数，使用默认值与用户配置合并
+        self.cache_config = cache_config or {}
+        self.cache_config = {
+            **{
+                "instance": None,  # 缓存实例
+                "key": f"py_wisharetec_saas_{self.account}",  # 缓存键
+                "expire": 7100,  # 过期时间（秒）
+            },
+            **self.cache_config,
+        }
+
+        # 配置httpx客户端参数，使用默认值与用户配置合并
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs = {
+            **{
+                "base_url": self.base_url,  # 基础URL
+                "timeout": 60,  # 请求超时时间（秒）
+                "verify": False,  # 禁用SSL证书验证
+                "headers": {
+                    "client": "co-pc"  # 客户端标识
+                }
+            },
+            **self.client_kwargs,
+        }
+
+        # 初始化token为空，需要通过login或refresh_token获取
+        self.token = ""
+
+    def query_space_manage_tree(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        查询空间管理树结构
+
+        该方法用于获取当前用户有权限访问的空间管理树数据，常用于验证Token是否有效。
+        请求会携带账号和MD5加密后的密码进行身份验证。
+
+        :param client: 可选的同步httpx.Client实例，若未提供则使用默认客户端
+        :param client_kwargs: 可选的客户端配置参数
+        :param kwargs: 额外的请求参数，可覆盖默认配置（如method、url、headers等）
+        :return: httpx.Response - HTTP响应对象，成功时包含空间管理树数据
+        """
+        # 处理参数默认值
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+
+        # 构建请求参数，合并默认配置与用户传入的配置
+        kwargs = {
+            **{
+                "method": "GET",
+                "url": "/api/space/space/manageTree",
+                "headers": {
+                    "client": "co-pc",
+                    "authorization": self.token,
+                },
+                "json": {
+                    "account": self.account,
+                    "password": hashlib.md5(self.password.encode("utf-8")).hexdigest(),  # 密码MD5加密
+                },
+            },
+            **kwargs,
+        }
+
+        # 调用父类的request方法发送请求
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    def login(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        用户登录SaaS系统
+
+        该方法向登录接口发送POST请求，携带账号和MD5加密后的密码进行身份认证。
+        登录成功后，从响应头中提取authorization token并存储在实例中。
+
+        :param client: 可选的同步httpx.Client实例，若未提供则使用默认客户端
+        :param client_kwargs: 可选的客户端配置参数
+        :param kwargs: 额外的请求参数，可覆盖默认配置
+        :return: httpx.Response - HTTP响应对象
+        """
+        # 处理参数默认值
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+
+        # 构建登录请求参数
+        kwargs = {
+            **{
+                "method": "POST",
+                "url": "/api/user/loginInteractive",  # 登录接口路径
+                "headers": {
+                    "client": "co-pc"
+                },
+                "json": {
+                    "account": self.account,
+                    "password": hashlib.md5(self.password.encode("utf-8")).hexdigest(),  # 密码MD5加密
+                },
+            },
+            **kwargs,
+        }
+
+        # 发送登录请求
+        response = self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+        # 解析响应，提取token
+        if response.is_success:
+            # 使用JSON Schema校验响应数据结构是否符合预期
+            if json_is_valid(
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "userLoginV": {
+                                "type": "object",
+                                "properties": {
+                                    "userInfoV": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "string", "minLength": 1}
+                                        },
+                                        "required": ["id"]
+                                    },
+                                },
+                                "required": ["userInfoV"]
+                            }
+                        },
+                        "required": ["userLoginV"],
+                    },
+                    data=response.json(),
+            ):
+                # 从响应头中获取authorization token
+                self.token = response.headers.get("authorization", "")
+            else:
+                # 响应数据结构不符合预期，清空token
+                self.token = ""
+
+        return response
+
+    def refresh_token(
+            self,
+            login_func_kwargs: Optional[dict] = None,
+            query_space_manage_tree_func_kwargs: Optional[dict] = None,
+    ) -> "Saas":
+        """
+        刷新并获取有效的认证Token
+
+        该方法实现了智能Token刷新逻辑：
+        1. 如果未配置缓存实例，直接调用login获取新token
+        2. 如果配置了缓存，优先从缓存中读取token
+        3. 缓存中没有token或token无效时，调用login重新获取
+        4. 通过query_space_manage_tree验证token是否有效
+        5. 验证通过后将token存入缓存
+
+        :param login_func_kwargs: 传递给login方法的额外参数
+        :param query_space_manage_tree_func_kwargs: 传递给query_space_manage_tree方法的额外参数
+        :return: Saas实例本身，支持链式调用
+        """
+        # 处理参数默认值
+        login_func_kwargs = login_func_kwargs or {}
+        query_space_manage_tree_func_kwargs = query_space_manage_tree_func_kwargs or {}
+
+        # 获取缓存配置
+        cache_key = self.cache_config.get("key", f"py_wisharetec_saas_{self.account}")
+        cache_expire = self.cache_config.get("expire", 7100)
+        cache_instance = self.cache_config.get("instance", None)
+
+        # 判断是否配置了有效的缓存实例
+        if not isinstance(cache_instance, Union[diskcache.Cache, redis.Redis]):
+            # 未配置缓存，直接登录获取token
+            self.login(**login_func_kwargs)
+        else:
+            # 从缓存中读取token
+            self.token = cache_instance.get(cache_key)
+
+            # 如果缓存中没有token或token无效，重新登录
+            if not isinstance(self.token, str) or not len(self.token):
+                self.login(**login_func_kwargs)
+
+            # 查询空间管理树验证token是否有效
+            response_json = self.query_space_manage_tree(**query_space_manage_tree_func_kwargs).json()
+
+            # 如果token无效，重新登录
+            if not json_is_valid(
+                    schema={
+                        "type": "array",
+                        "minItems": 1,
+                    },
+                    data=response_json,
+            ):
+                self.login(**login_func_kwargs)
+
+            # 如果token有效，将其存入缓存
+            if json_is_valid(
+                    schema={
+                        "type": "array",
+                        "minItems": 1,
+                    },
+                    data=response_json,
+            ):
+                if isinstance(cache_instance, diskcache.Cache):
+                    cache_instance.set(cache_key, self.token, expire=cache_expire)
+                elif isinstance(cache_instance, redis.Redis):
+                    cache_instance.set(cache_key, self.token, ex=cache_expire)
+
+        return self
+
+    def request_with_token(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        发送请求并自动添加授权头
+
+        该方法会在请求头中自动添加client标识和authorization token，
+        确保请求携带有效的身份认证信息。
+
+        :param client: 可选的同步httpx.Client实例，若未提供则使用默认客户端
+        :param client_kwargs: 可选的客户端配置参数
+        :param kwargs: 传递给request的额外参数，可覆盖headers配置
+        :return: httpx.Response - HTTP响应对象
+        """
+        # 处理参数默认值
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+
+        # 构建请求头，添加认证信息
+        kwargs = {
+            "headers": {
+                "client": "co-pc",  # 客户端标识
+                "authorization": self.token,  # 认证token
+            },
+            **kwargs,
+        }
+
+        # 调用父类的request方法发送请求
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_query_space_manage_tree(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步查询空间管理树结构
+
+        该方法用于异步获取当前用户有权限访问的空间管理树数据，常用于验证Token是否有效。
+        请求会携带账号和MD5加密后的密码进行身份验证。
+
+        :param client: 可选的异步httpx.AsyncClient实例，若未提供则使用默认客户端
+        :param client_kwargs: 可选的客户端配置参数
+        :param kwargs: 额外的请求参数，可覆盖默认配置
+        :return: httpx.Response - HTTP响应对象，成功时包含空间管理树数据
+        """
+        # 处理参数默认值
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+
+        # 构建请求参数，合并默认配置与用户传入的配置
+        kwargs = {
+            **{
+                "method": "GET",
+                "url": "/api/space/space/manageTree",
+                "headers": {
+                    "client": "co-pc",
+                    "authorization": self.token,
+                },
+                "json": {
+                    "account": self.account,
+                    "password": hashlib.md5(self.password.encode("utf-8")).hexdigest(),  # 密码MD5加密
+                },
+            },
+            **kwargs,
+        }
+
+        # 调用异步请求方法，自动添加授权头
+        return await self.async_request_with_token(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_login(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步用户登录SaaS系统
+
+        该方法向登录接口异步发送POST请求，携带账号和MD5加密后的密码进行身份认证。
+        登录成功后，从响应头中提取authorization token并存储在实例中。
+
+        :param client: 可选的异步httpx.AsyncClient实例，若未提供则使用默认客户端
+        :param client_kwargs: 可选的客户端配置参数
+        :param kwargs: 额外的请求参数，可覆盖默认配置
+        :return: httpx.Response - HTTP响应对象
+        """
+        # 处理参数默认值
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+
+        # 构建登录请求参数
+        kwargs = {
+            **{
+                "method": "POST",
+                "url": "/api/user/loginInteractive",  # 登录接口路径
+                "headers": {
+                    "client": "co-pc"
+                },
+                "json": {
+                    "account": self.account,
+                    "password": hashlib.md5(self.password.encode("utf-8")).hexdigest(),  # 密码MD5加密
+                },
+            },
+            **kwargs,
+        }
+
+        # 发送异步登录请求
+        response = await self.async_request_with_token(client=client, client_kwargs=client_kwargs, **kwargs)
+
+        # 解析响应，提取token
+        if response.is_success:
+            # 使用JSON Schema校验响应数据结构是否符合预期
+            if json_is_valid(
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "userLoginV": {
+                                "type": "object",
+                                "properties": {
+                                    "userInfoV": {
+                                        "type": "object",
+                                        "properties": {
+                                            "id": {"type": "string", "minLength": 1}
+                                        },
+                                        "required": ["id"]
+                                    },
+                                },
+                                "required": ["userInfoV"]
+                            }
+                        },
+                        "required": ["userLoginV"],
+                    },
+                    data=response.json(),
+            ):
+                # 从响应头中获取authorization token
+                self.token = response.headers.get("authorization", "")
+            else:
+                # 响应数据结构不符合预期，清空token
+                self.token = ""
+
+        return response
+
+    async def async_refresh_token(
+            self,
+            login_func_kwargs: Optional[dict] = None,
+            query_space_manage_tree_func_kwargs: Optional[dict] = None,
+    ) -> "Saas":
+        """
+        异步刷新并获取有效的认证Token
+
+        该方法实现了异步的智能Token刷新逻辑：
+        1. 如果未配置缓存实例，直接调用async_login获取新token
+        2. 如果配置了缓存，优先从缓存中读取token
+        3. 缓存中没有token或token无效时，调用async_login重新获取
+        4. 通过async_query_space_manage_tree验证token是否有效
+        5. 验证通过后将token存入缓存
+
+        :param login_func_kwargs: 传递给async_login方法的额外参数
+        :param query_space_manage_tree_func_kwargs: 传递给async_query_space_manage_tree方法的额外参数
+        :return: Saas实例本身，支持链式调用
+        """
+        # 处理参数默认值
+        login_func_kwargs = login_func_kwargs or {}
+        query_space_manage_tree_func_kwargs = query_space_manage_tree_func_kwargs or {}
+
+        # 获取缓存配置
+        cache_key = self.cache_config.get("key", f"py_wisharetec_saas_{self.account}")
+        cache_expire = self.cache_config.get("expire", 7100)
+        cache_instance = self.cache_config.get("instance", None)
+
+        # 判断是否配置了有效的缓存实例
+        if not isinstance(cache_instance, Union[diskcache.Cache, redis.Redis]):
+            # 未配置缓存，直接异步登录获取token
+            await self.async_login(**login_func_kwargs)
+        else:
+            # 从缓存中读取token
+            self.token = cache_instance.get(cache_key)
+
+            # 如果缓存中没有token或token无效，重新异步登录
+            if not isinstance(self.token, str) or not len(self.token):
+                await self.async_login(**login_func_kwargs)
+
+            # 异步查询空间管理树验证token是否有效
+            response = await self.async_query_space_manage_tree(**query_space_manage_tree_func_kwargs)
+
+            # 如果token无效，重新异步登录
+            if not json_is_valid(
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "children": {"type": "array", "minItems": 1},
+                        },
+                        "required": ["children"],
+                    },
+                    data=response.json(),
+            ):
+                await self.async_login(**login_func_kwargs)
+
+            # 再次验证token并保存到缓存
+            response = await self.async_query_space_manage_tree(**query_space_manage_tree_func_kwargs)
+            if json_is_valid(
+                    schema={
+                        "type": "object",
+                        "properties": {
+                            "children": {"type": "array", "minItems": 1},
+                        },
+                        "required": ["children"],
+                    },
+                    data=response.json(),
+            ):
+                if isinstance(cache_instance, diskcache.Cache):
+                    cache_instance.set(cache_key, self.token, expire=cache_expire)
+                elif isinstance(cache_instance, redis.Redis):
+                    cache_instance.set(cache_key, self.token, ex=cache_expire)
+
+        return self
+
+    async def async_request_with_token(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步发送请求并自动添加授权头
+
+        该方法会在请求头中自动添加client标识和authorization token，
+        确保请求携带有效的身份认证信息。
+
+        :param client: 可选的异步httpx.AsyncClient实例，若未提供则使用默认客户端
+        :param client_kwargs: 可选的客户端配置参数
+        :param kwargs: 传递给async_request的额外参数，可覆盖headers配置
+        :return: httpx.Response - HTTP响应对象
+        """
+        # 处理参数默认值
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+
+        # 构建请求头，添加认证信息
+        kwargs = {
+            "headers": {
+                "client": "co-pc",  # 客户端标识
+                "authorization": self.token,  # 认证token
+            },
+            **kwargs,
+        }
+
+        # 调用父类的async_request方法发送异步请求
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit/saas/utils.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from datetime import datetime
+from typing import Any, Optional, Union
+
+import httpx
+from jsonpath_ng import parse
+from jsonschema.validators import Draft202012Validator
+
+
+def json_find_first(expression: str, data: Any) -> Any:
+    """
+    使用 JSONPath 表达式从 JSON 数据中查找第一个匹配项
+
+    该函数使用 jsonpath-ng 库解析 JSONPath 表达式，并从给定的数据中提取第一个匹配的值。
+    常用于从复杂的 JSON 结构中快速定位特定字段。
+
+    :param expression: JSONPath 表达式，用于指定要查找的数据路径
+                       例如: "$.userInfoV.id" 表示查找根节点下的 userInfoV 对象的 id 字段
+    :param data: 待查询的 JSON 数据（字典或列表）
+    :return: Any - 第一个匹配的值，如果没有匹配项则返回 None
+    """
+    # 使用 jsonpath-ng 解析表达式并查找所有匹配项
+    results = [i.value for i in parse(expression).find(data)]
+
+    # 检查结果列表是否非空，返回第一个匹配项
+    if isinstance(results, list) and len(results) > 0:
+        return results[0]
+
+    # 没有找到匹配项，返回 None
+    return None
+
+
+def json_is_valid(schema: Optional[dict], data: Any) -> bool:
+    """
+    校验 JSON 数据是否符合指定的 JSON Schema
+
+    该函数使用 JSON Schema Draft 2020-12 规范对数据进行校验，
+    确保数据结构符合预期。常用于 API 响应数据的格式验证。
+
+    :param schema: JSON Schema 字典，定义了数据应满足的结构约束
+                   例如: {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}
+    :param data: 待校验的 JSON 数据（可以是任意类型）
+    :return: bool - 校验是否成功，符合 Schema 返回 True，否则返回 False
+    """
+    # 使用 Draft202012Validator 进行 Schema 校验
+    return Draft202012Validator(schema).is_valid(data)

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: py-wisharetec-toolkit
+Version: 1.0.0
+Summary: Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。
+Author-email: Guolei <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 郭磊
+        
+        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.git
+Keywords: wisharetec,python,client,api,wisharetec saas,saas
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: redis>=4.6.0
+Requires-Dist: py-httpx-toolkit>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# py-wisharetec-toolkit
+
+Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力。
+
+## 功能特性
+
+- 封装 SaaS 系统的认证机制，包括登录、令牌刷新和令牌缓存
+- 提供同步和异步两种 HTTP 请求模式
+- 集成 JSON Schema 校验和 JSONPath 查询工具
+- 支持 diskcache 和 Redis 两种缓存后端
+
+## 安装
+
+### 使用 uv（推荐）
+
+```bash
+uv add py-wisharetec-toolkit
+```
+
+### 使用 pip
+
+```bash
+pip install py-wisharetec-toolkit
+```
+
+## 依赖包
+
+| 依赖包 | 版本要求 | 说明 |
+|--------|----------|------|
+| httpx | >=0.27.0 | HTTP 客户端库，支持同步和异步请求 |
+| pydantic | >=2.0 | 数据验证和序列化 |
+| jsonpath-ng | >=1.5.3 | JSONPath 查询工具 |
+| jsonschema | >=4.21.0 | JSON Schema 校验 |
+| diskcache | >=5.6.3 | 本地磁盘缓存 |
+| redis | >=4.6.0 | Redis 缓存支持 |
+| py-httpx-toolkit | >=1.0.0 | HTTP 请求工具封装 |
+
+## API 说明
+
+### Saas 类
+
+#### 初始化
+
+```python
+from py_wisharetec_toolkit.saas import Saas
+
+saas = Saas(
+    base_url="https://saas.wisharetec.com/",
+    account="your_account",
+    password="your_password",
+    cache_config={
+        "instance": None,  # diskcache.Cache 或 redis.Redis 实例
+        "key": "py_wisharetec_saas_account",
+        "expire": 7100,
+    },
+    client_kwargs={
+        "timeout": 60,
+        "verify": False,
+    }
+)
+```
+
+#### 同步方法
+
+| 方法 | 说明 |
+|------|------|
+| `login()` | 用户登录，获取认证 Token |
+| `refresh_token()` | 智能刷新 Token（支持缓存） |
+| `query_space_manage_tree()` | 查询空间管理树结构 |
+| `request_with_token()` | 发送带授权头的请求 |
+
+#### 异步方法
+
+| 方法 | 说明 |
+|------|------|
+| `async_login()` | 异步用户登录 |
+| `async_refresh_token()` | 异步智能刷新 Token |
+| `async_query_space_manage_tree()` | 异步查询空间管理树 |
+| `async_request_with_token()` | 异步发送带授权头的请求 |
+
+## utils 工具函数
+
+### json_find_first
+
+使用 JSONPath 表达式从 JSON 数据中查找第一个匹配项。
+
+```python
+from py_wisharetec_toolkit.saas.utils import json_find_first
+
+data = {"userInfoV": {"id": "123"}}
+result = json_find_first("$.userInfoV.id", data)
+# 返回: "123"
+```
+
+### json_is_valid
+
+校验 JSON 数据是否符合指定的 JSON Schema。
+
+```python
+from py_wisharetec_toolkit.saas.utils import json_is_valid
+
+schema = {
+    "type": "object",
+    "properties": {"id": {"type": "string"}},
+    "required": ["id"]
+}
+data = {"id": "123"}
+result = json_is_valid(schema, data)
+# 返回: True
+```
+
+## 使用示例
+
+### 同步方式
+
+```python
+from py_wisharetec_toolkit.saas import Saas
+
+saas = Saas(
+    account="test",
+    password="password"
+)
+
+# 登录获取 Token
+saas.login()
+
+# 发送请求
+response = saas.request_with_token(
+    method="GET",
+    url="/api/data/list"
+)
+print(response.json())
+```
+
+### 异步方式
+
+```python
+import asyncio
+from py_wisharetec_toolkit.saas import Saas
+
+async def main():
+    saas = Saas(
+        account="test",
+        password="password"
+    )
+    
+    # 异步登录
+    await saas.async_login()
+    
+    # 异步发送请求
+    response = await saas.async_request_with_token(
+        method="GET",
+        url="/api/data/list"
+    )
+    print(response.json())
+
+asyncio.run(main())
+```
+
+### 使用缓存
+
+```python
+import diskcache
+from py_wisharetec_toolkit.saas import Saas
+
+cache = diskcache.Cache("./cache")
+
+saas = Saas(
+    account="test",
+    password="password",
+    cache_config={
+        "instance": cache,
+        "key": "saas_token",
+        "expire": 7100
+    }
+)
+
+# 自动从缓存获取或刷新 Token
+saas.refresh_token()
+```
+
+## 作者
+
+**Guolei**
+
+- 邮箱: 174000902@qq.com
+
+## 项目主页
+
+- **Gitee**: [https://gitee.com/guolei19850528/py_wisharetec_toolkit](https://gitee.com/guolei19850528/py_wisharetec_toolkit)
+
+## 许可证
+
+MIT License

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/py_wisharetec_toolkit/__init__.py
+src/py_wisharetec_toolkit.egg-info/PKG-INFO
+src/py_wisharetec_toolkit.egg-info/SOURCES.txt
+src/py_wisharetec_toolkit.egg-info/dependency_links.txt
+src/py_wisharetec_toolkit.egg-info/requires.txt
+src/py_wisharetec_toolkit.egg-info/top_level.txt
+src/py_wisharetec_toolkit/saas/__init__.py
+src/py_wisharetec_toolkit/saas/utils.py

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit.egg-info/requires.txt

@@ -0,0 +1,13 @@
+httpx>=0.27.0
+pydantic>=2.0
+jsonpath-ng>=1.5.3
+jsonschema>=4.21.0
+diskcache>=5.6.3
+redis>=4.6.0
+py-httpx-toolkit>=1.0.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+setuptools>=61.0
+twine>=4.0

py_wisharetec_toolkit-1.0.0/src/py_wisharetec_toolkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+py_wisharetec_toolkit