Metadata-Version: 2.4
Name: py-wisharetec
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
Project-URL: Repository, https://gitee.com/guolei19850528/py_wisharetec.git
Project-URL: Issues, https://gitee.com/guolei19850528/py_wisharetec/issues
Keywords: wisharetec,python,client,api,saas,http,async
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Framework :: AsyncIO
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
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: setuptools>=61.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Dynamic: license-file

# py-wisharetec

Wisharetec SaaS 系统的 Python 客户端库，提供同步和异步接口调用能力，帮助开发者快速集成 SaaS 系统功能。

## 功能特性

- **同步/异步支持**：提供完整的同步和异步 API，满足不同应用场景需求
- **登录认证**：支持账号密码登录，自动管理访问令牌
- **智能令牌刷新**：自动检测令牌有效性，支持自动刷新
- **令牌缓存**：支持 diskcache 和 Redis 两种缓存后端，减少重复登录
- **请求封装**：统一处理认证头，简化业务请求调用
- **数据校验**：内置 JSON Schema 校验和 JSONPath 查询工具
- **类型提示**：完整的类型注解，支持 IDE 智能提示

## 安装

### 使用 pip

```bash
pip install py_wisharetec
```

### 使用 uv（推荐）

```bash
uv add py-wisharetec
```

### 开发模式

```bash
git clone https://gitee.com/guolei19850528/py_wisharetec.git
cd py_wisharetec
uv sync
```

## 快速开始

### 同步模式

```python
from py_wisharetec.saas import Saas

# 初始化客户端
saas = Saas(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password"
)

# 登录并刷新令牌（自动处理令牌缓存）
saas.refresh_token()

# 发起请求
response = saas.request(
    method="GET",
    url="/api/your-endpoint"
)

print(response.json())
```

### 异步模式

```python
import asyncio
from py_wisharetec.saas import Saas

async def main():
    # 初始化客户端
    saas = Saas(
        base_url="https://saas.wisharetec.com/",
        account="your_account",
        password="your_password"
    )
    
    # 异步登录并刷新令牌
    await saas.async_refresh_token()
    
    # 发起异步请求
    response = await saas.async_request(
        method="GET",
        url="/api/your-endpoint"
    )
    
    print(response.json())

asyncio.run(main())
```

## 配置选项

### 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| base_url | str | https://saas.wisharetec.com/ | SaaS 服务基础 URL |
| account | str | None | 用户账号 |
| password | str | None | 用户密码（会进行 MD5 加密传输） |
| cache_config | dict | {} | 缓存配置 |
| client_kwargs | dict | {} | HTTP 客户端额外参数 |

### 缓存配置

```python
cache_config = {
    "instance": None,           # diskcache.Cache 或 redis.Redis 实例
    "key": "py_wisharetec_saas_{account}",  # 缓存键名
    "expire": 7100             # 过期时间（秒），约 2 小时
}
```

### 客户端配置

```python
client_kwargs = {
    "timeout": 60,             # 请求超时时间（秒）
    "verify": False,           # 是否验证 SSL 证书
    "headers": {
        "client": "co-pc"      # 客户端标识
    }
}
```

## API 参考

### Saas 类

#### 同步方法

| 方法 | 说明 |
|------|------|
| `client()` | 创建同步 HTTP 客户端实例 |
| `login(**kwargs)` | 登录系统，获取访问令牌 |
| `refresh_token(**kwargs)` | 智能刷新令牌（支持缓存） |
| `request(**kwargs)` | 发起通用 HTTP 请求 |
| `query_space_manage_tree(**kwargs)` | 查询空间管理树结构 |

#### 异步方法

| 方法 | 说明 |
|------|------|
| `async_client()` | 创建异步 HTTP 客户端实例 |
| `async_login(**kwargs)` | 异步登录系统 |
| `async_refresh_token(**kwargs)` | 异步智能刷新令牌 |
| `async_request(**kwargs)` | 发起异步 HTTP 请求 |
| `async_query_space_manage_tree(**kwargs)` | 异步查询空间管理树 |

### 工具函数

| 函数 | 说明 |
|------|------|
| `json_find_first(expression, data)` | 使用 JSONPath 查找第一个匹配项 |
| `json_is_valid(schema, data)` | 校验 JSON 数据是否符合 Schema |

## 使用示例

### 使用 diskcache 缓存

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

# 创建缓存实例
cache = diskcache.Cache("./cache")

# 初始化客户端（带缓存）
saas = Saas(
    account="your_account",
    password="your_password",
    cache_config={
        "instance": cache,
        "expire": 7200
    }
)

# 登录（自动使用缓存）
saas.refresh_token()

# 发起请求
response = saas.request(method="GET", url="/api/endpoint")
```

### 使用 Redis 缓存

```python
import redis
from py_wisharetec.saas import Saas

# 创建 Redis 连接
redis_client = redis.Redis(host="localhost", port=6379, db=0)

# 初始化客户端（带 Redis 缓存）
saas = Saas(
    account="your_account",
    password="your_password",
    cache_config={
        "instance": redis_client,
        "key": "my_custom_key",
        "expire": 7200
    }
)

# 登录并刷新令牌
saas.refresh_token()
```

### 自定义 HTTP 客户端

```python
import httpx
from py_wisharetec.saas import Saas

# 创建自定义客户端
custom_client = httpx.Client(
    base_url="https://saas.wisharetec.com/",
    timeout=30,
    headers={"client": "co-pc"}
)

# 初始化客户端
saas = Saas(account="your_account", password="your_password")

# 使用自定义客户端登录
saas.login(client=custom_client)

# 使用自定义客户端发起请求
response = saas.request(client=custom_client, method="GET", url="/api/endpoint")

# 关闭客户端
custom_client.close()
```

### 异步使用示例

```python
import asyncio
import diskcache
from py_wisharetec.saas import Saas

async def main():
    # 创建缓存实例
    cache = diskcache.Cache("./cache")
    
    # 初始化客户端
    saas = Saas(
        account="your_account",
        password="your_password",
        cache_config={"instance": cache}
    )
    
    # 异步刷新令牌
    await saas.async_refresh_token()
    
    # 批量发起异步请求
    tasks = [
        saas.async_request(method="GET", url="/api/endpoint1"),
        saas.async_request(method="GET", url="/api/endpoint2"),
        saas.async_request(method="GET", url="/api/endpoint3"),
    ]
    
    responses = await asyncio.gather(*tasks)
    
    for response in responses:
        print(response.json())

asyncio.run(main())
```

## 开发指南

### 运行测试

```bash
# 运行所有测试
uv run pytest

# 运行测试并生成覆盖率报告
uv run pytest --cov=src --cov-report=html

# 仅运行异步测试
uv run pytest -k async
```

### 代码格式化

```bash
# 使用 black 格式化代码
uv run black src/

# 使用 isort 排序导入
uv run isort src/

# 使用 flake8 检查代码风格
uv run flake8 src/

# 使用 mypy 进行类型检查
uv run mypy src/
```

### 构建包

```bash
# 构建源代码包和 wheel
uv build

# 上传到 PyPI
uv run twine upload dist/*
```

## 依赖

| 依赖 | 最低版本 | 说明 |
|------|----------|------|
| 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 缓存（可选） |

### 开发依赖

| 依赖 | 最低版本 | 说明 |
|------|----------|------|
| pytest | >= 7.0 | 测试框架 |
| pytest-cov | >= 4.0 | 测试覆盖率 |
| pytest-asyncio | >= 0.21.0 | 异步测试支持 |
| flake8 | >= 6.0 | 代码风格检查 |
| black | >= 23.0 | 代码格式化 |
| isort | >= 5.12.0 | 导入排序 |
| mypy | >= 1.5.0 | 类型检查 |
| twine | >= 4.0 | PyPI 上传工具 |

## 项目结构

```
py_wisharetec/
├── src/
│   └── py_wisharetec/
│       ├── __init__.py          # 包入口，导出核心类
│       └── saas/
│           ├── __init__.py      # Saas 客户端核心实现
│           └── utils.py         # 工具函数（JSON 处理）
├── tests/                       # 测试文件（可选）
├── .gitignore
├── LICENSE
├── pyproject.toml               # 项目配置
├── README.md                    # 项目文档
└── uv.lock                      # 依赖锁定文件
```

## 许可证

MIT License

## 主页

[https://gitee.com/guolei19850528/py_wisharetec](https://gitee.com/guolei19850528/py_wisharetec)

## 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献流程

1. Fork 仓库
2. 创建功能分支 (`git checkout -b feature/your-feature`)
3. 提交更改 (`git commit -am 'Add some feature'`)
4. 推送到分支 (`git push origin feature/your-feature`)
5. 创建 Pull Request
