Metadata-Version: 2.1
Name: xzstudio
Version: 1.0.0
Summary: XZStudio校验码发送工具库 - 支持GUI界面与批量操作
Home-page: https://github.com/frasht
Author: xzstudio
Author-email: XZ Team <xzteam@example.com>
License: MIT
Project-URL: Homepage, https://github.com/xzteam/xzstudio
Project-URL: Documentation, https://github.com/xzteam/xzstudio#readme
Project-URL: Repository, https://github.com/xzteam/xzstudio
Project-URL: Issues, https://github.com/xzteam/xzstudio/issues
Keywords: verification-code,api-client,gui,batch-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: openpyxl>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: build>=0.7.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# XZStudio - 校验码发送工具库

> **相关内容含AI生成**
> **相关第三方库系XZ团队内部开发，不建议外部人员使用**

## 简介

XZStudio 是一个功能完善的校验码发送工具库，支持通过API向用户发送临时或永久校验码。提供直观的GUI界面和批量操作功能，可封装为标准Python第三方库。

## 特性

- **双模式操作**：支持单用户发送和批量发送两种模式
- **校验码类型**：支持临时校验码（需指定有效期）和永久校验码
- **GUI界面**：基于tkinter的直观图形界面，无需额外依赖
- **批量处理**：支持Excel文件导入导出，一键批量发送
- **错误处理**：完善的异常处理机制和用户反馈
- **配置持久化**：API Token等配置自动保存

## 安装

```bash
pip install xzstudio
```

或从源码安装：

```bash
git clone https://github.com/xzteam/xzstudio.git
cd xzstudio
pip install -e .
```

## 快速开始

### 命令行启动GUI

```bash
xzstudio
```

### 代码中使用

```python
from xzstudio import APIClient, Config

# 方式1：使用配置文件中的Token
client = APIClient()

# 方式2：直接指定Token
client = APIClient(api_token="your_api_token_here")

# 发送临时校验码
result = client.send_verification_code(
    username="张三",
    code_type="temp",
    email="zhangsan@example.com",
    date="2026-12-31"
)

# 发送永久校验码
result = client.send_verification_code(
    username="李四",
    code_type="permanent",
    email="lisi@example.com"
)

print(result)
```

### 批量处理Excel

```python
from xzstudio import ExcelHandler, APIClient

handler = ExcelHandler()
client = APIClient(api_token="your_api_token_here")

# 读取Excel文件
users = handler.read_excel("users.xlsx")

# 批量发送
for user in users:
    try:
        result = client.send_verification_code(
            username=user['username'],
            code_type=user['code_type'],
            email=user['email'],
            date=user.get('date')
        )
        user['status'] = '成功'
        user['verification_code'] = result.get('data', {}).get('code', '')
    except Exception as e:
        user['status'] = '失败'
        user['message'] = str(e)

# 导出结果
handler.write_excel("results.xlsx", users)
```

## GUI使用说明

1. **设置页面**：首次使用请先配置API Token
2. **单用户发送**：
   - 输入用户名、选择类型、填写邮箱
   - 临时校验码需填写有效期（YYYY-MM-DD格式）
   - 点击"发送校验码"
3. **批量发送**：
   - 点击"生成模板文件"获取Excel模板
   - 填写用户信息后点击"导入Excel文件"
   - 预览数据确认无误后点击"批量发送校验码"
   - 完成后可"导出结果"

## Excel模板格式

| 用户名 | 类型 | 邮箱 | 日期 |
|--------|------|------|------|
| 张三 | temp | zhangsan@example.com | 2026-12-31 |
| 李四 | permanent | lisi@example.com | |

- **类型**：temp（临时）或 permanent（永久）
- **日期**：仅临时校验码需要填写

## API参考

### APIClient

```python
client = APIClient(api_token=None, config=None)
```

**参数**：
- `api_token` (str, optional): API认证Token
- `config` (Config, optional): 配置对象

**方法**：

#### send_verification_code()

```python
client.send_verification_code(username, code_type, email, date=None)
```

发送校验码到指定邮箱。

**参数**：
- `username` (str): 用户名
- `code_type` (str): 校验码类型，'temp' 或 'permanent'
- `email` (str): 用户邮箱
- `date` (str, optional): 有效期截止日期，仅临时校验码需要

**返回**：
```python
{
    "success": True,
    "status_code": 200,
    "data": {...},
    "message": "校验码发送成功"
}
```

### ExcelHandler

```python
handler = ExcelHandler()
```

**方法**：
- `read_excel(file_path)`: 读取Excel文件，返回用户列表
- `write_excel(file_path, data)`: 写入结果到Excel文件
- `create_template(file_path)`: 创建Excel模板文件

## 异常处理

```python
from xzstudio.exceptions import (
    XZStudioError,      # 基础异常
    NetworkError,       # 网络错误
    APIError,           # API调用错误
    AuthenticationError,# 认证错误
    ValidationError,    # 数据验证错误
    ExcelProcessingError,# Excel处理错误
    ConfigurationError, # 配置错误
)

try:
    client.send_verification_code(...)
except AuthenticationError:
    print("Token无效或已过期")
except NetworkError:
    print("网络连接失败")
except APIError as e:
    print(f"API错误: {e.message}")
```

## 依赖

- Python >= 3.7
- requests >= 2.25.0
- openpyxl >= 3.0.0

## 许可证

MIT License

---

**XZ Team**
