zfile-pysdk 1.0.0

Python SDK for ZFile API - 功能完整的ZFile文件管理系统SDK

ZFile SDK

一个功能完整的 Python SDK，用于与 ZFile 文件管理系统进行交互。该 SDK 封装了前端用户和管理员的完整 API 接口，提供了基于 Pydantic 的类型安全请求/响应处理和统一的错误管理机制。

✨ 特性

• 🔐 完整的认证系统 - 支持用户登录、管理员认证、验证码和会话管理
• 📁 文件管理功能 - 文件列表查看、文件操作（上传、下载、重命名、移动、复制、删除）
• 🔗 链接管理 - 批量生成直链和短链
• 🌐 多平台集成 - 支持 Google Drive、OneDrive、SharePoint、S3、115网盘等存储源
• ⚙️ 站点配置 - 获取站点全局设置、存储源配置等
• 📝 类型安全 - 基于 Pydantic 2.x 的强类型支持和数据验证
• 🛡️ 错误处理 - 统一的异常处理和错误管理机制
• 📊 日志记录 - 完整的操作日志和调试信息
• 🔧 装饰器支持 - 自动参数解析和模型验证

📦 安装

从源码安装

git clone https://github.com/cuckoo711/zfile_sdk.git
cd zfile_sdk
pip install -r requirements.txt
pip install -e .

依赖要求

• Python 3.8+
• requests ~= 2.32.4
• pydantic ~= 2.11.7
• urllib3 ~= 2.5.0

🚀 快速开始

基础用法

# 导入核心客户端
from ZfileSDK.utils.api_client import ApiClient

创建客户端实例

# 创建客户端实例
client = ApiClient(base_url="http://localhost:8080")

# 用户登录
client.login(username="your_username", password="your_password")

# 检查登录状态
print(f"是否为管理员: {client.is_admin}")
print(f"当前 Token: {client.token}")

# 使用完毕后注销
client.logout()

使用上下文管理器

# 使用上下文管理器自动处理登录和注销
with ApiClient(base_url="http://localhost:8080") as client:
    client.login(username="admin", password="password")
    # 执行各种操作...
    # 自动清理资源

文件操作示例

from ZfileSDK.front import FileListModule, FileOperationModule

# 获取文件列表
file_list_module = FileListModule(client)
files = file_list_module.storage_files(
    storage_key="local",
    path="/",
    password=None
)

# 创建文件夹
file_op_module = FileOperationModule(client)
result = file_op_module.mkdir(
    storage_key="local",
    path="/",
    name="新文件夹",
    password=None
)

短链生成示例

from ZfileSDK.front import DirectShortChainModule

# 生成短链
short_link_module = DirectShortChainModule(client)
links = short_link_module.batch_generate(
    storage_key="local",
    paths=["/file1.txt", "/file2.txt"],
    expire_time=3600,
)

📁 项目结构

zfile_sdk/
├── ZfileSDK/
│   ├── __init__.py
│   ├── utils/                          # 核心工具模块
│   │   ├── __init__.py
│   │   ├── api_client.py               # HTTP 客户端封装
│   │   ├── models.py                   # Pydantic 数据模型
│   │   ├── exceptions.py               # 异常定义
│   │   ├── logger.py                   # 日志处理
│   │   └── base.py                     # 基础类和装饰器
│   ├── front/                          # 前端用户功能模块
│   │   ├── __init__.py
│   │   ├── file_list_module.py         # 文件列表模块
│   │   ├── file_operation_module.py    # 文件操作模块
│   │   ├── site_basic_module.py        # 站点基础模块
│   │   ├── user_interface.py           # 用户接口模块
│   │   ├── short_link.py               # 短链模块
│   │   ├── direct_short_chain_module.py # 直链短链模块
│   │   ├── initialization_module.py    # 初始化模块
│   │   ├── single_sign_on.py           # 单点登录模块
│   │   ├── server_proxy_download.py    # 服务器代理下载
│   │   ├── server_proxy_upload.py      # 服务器代理上传
│   │   ├── onlyoffice_related_interfaces.py # OnlyOffice 接口
│   │   ├── gd_tools_assistive_module.py # Google Drive 工具
│   │   ├── sharepoint_tools_assistive_module.py # SharePoint 工具
│   │   ├── s3_tools_assistive_module.py # S3 工具
│   │   ├── oneonefive_tools_assistive_module.py # 115网盘工具
│   │   ├── open_115_url_controller.py  # 115网盘 URL 控制器
│   │   ├── onedrive_authentication_callback_module.py # OneDrive 认证回调
│   │   └── single_sign_on_interface.py # 单点登录接口
│   └── admin/                          # 管理员功能模块
│       └── __init__.py
├── docs/                               # 文档目录
│   ├── README.md                       # 项目说明
│   ├── LICENSE                         # 许可证
│   └── LICENSE_CN                      # 中文许可证
├── requirements.txt                    # 依赖列表
├── setup.py                           # 安装脚本
└── test.py                            # 测试文件

🔧 核心功能

前端功能模块 (front/)

模块	功能描述
file_list_module	文件列表查看、存储搜索、单个文件信息获取
file_operation_module	文件操作（创建、删除、重命名、移动、复制、上传）
site_basic_module	站点基础信息和配置获取、存储源配置
user_interface	用户登录、密码管理、验证码获取
short_link	批量生成直链和短链
initialization_module	系统初始化和配置检查
single_sign_on	单点登录功能
server_proxy_download	服务器代理下载
server_proxy_upload	服务器代理上传
onlyoffice_related_interfaces	OnlyOffice 文档预览和在线编辑
gd_tools_assistive_module	Google Drive 集成和文件操作
sharepoint_tools_assistive_module	SharePoint 集成和文件管理
s3_tools_assistive_module	AWS S3 兼容存储集成
oneonefive_tools_assistive_module	115网盘集成

工具模块 (utils/)

• ApiClient: 核心 HTTP 客户端，提供统一的 API 调用接口和会话管理
• Models: 基于 Pydantic 2.x 的数据模型，确保类型安全和数据验证
• Exceptions: 自定义异常类，提供详细的错误信息和统一的错误处理
• Logger: 日志处理工具，支持多级别日志记录
• Base: 基础类和装饰器，提供自动参数解析功能

🔐 认证和安全

登录认证

# 基础登录
client.login(username="user", password="pass")

# 带验证码登录
client.login(
    username="user",
    password="pass",
    verify_code="1234",
    verify_code_uuid="uuid-string"
)

Token 管理

# 获取当前 token
token = client.token

# 使用预设 token 创建客户端
client = ApiClient(base_url="http://localhost:8080", token="your-token")

# 检查管理员权限
if client.is_admin:
    print("当前用户具有管理员权限")

🛠️ 高级用法

自定义请求

from ZfileSDK.utils.models import AjaxJsonVoid

# GET 请求
response = client.make_common_request("GET", "/api/endpoint", params={"key": "value"})

# POST 请求
response = client.post("POST", "/api/endpoint", data={"key": "value"})

错误处理

from ZfileSDK.utils.exceptions import ApiException, CustomException

try:
    client.login(username="invalid", password="invalid")
except CustomException as e:
    print(f"业务错误: {e.msg} (代码: {e.code})")
except ApiException as e:
    print(f"API 错误: {e.message}")

使用装饰器

from ZfileSDK.utils.base import auto_args_from_model
from ZfileSDK.utils.models import FileListRequest


# 装饰器自动解析参数
@auto_args_from_model(model=FileListRequest)
def get_files(*, data: FileListRequest):
    # 自动验证和解析参数
    pass

📚 API 文档

详细的 API 文档请参考 ZFile 官方API文档。

🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request
6. 确保代码符合 PEP 8 风格指南

请确保您的代码经过测试，并且添加了必要的文档注释。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情，或查看 LICENSE_CN 文件的中文版本。

🔗 相关链接

• ZFile 官方网站
• ZFile GitHub
• 问题反馈

📞 支持

如果您在使用过程中遇到问题，请通过以下方式获取帮助：

• 查看 官方API文档
• 提交 Issue
• 向我发送邮件获取支持

📝 注意事项

• 本 SDK 仅支持 ZFile 版本 4.0.1 及以上。

---

注意: 本 SDK 需要配合 ZFile 后端服务使用，请确保您的 ZFile 服务正常运行。