# ZFile SDK
一个功能完整的 Python SDK，用于与 ZFile 文件管理系统进行交互。该 SDK 封装了前端用户和管理员的完整 API 接口，提供了基于
Pydantic 的类型安全请求/响应处理和统一的错误管理机制。
## ✨ 特性
- 🔐 **完整的认证系统** - 支持用户登录、管理员认证、验证码和会话管理
- 📁 **文件管理功能** - 文件列表查看、文件操作（上传、下载、重命名、移动、复制、删除）
- 🔗 **链接管理** - 批量生成直链和短链
- 🌐 **多平台集成** - 支持 Google Drive、OneDrive、SharePoint、S3、115网盘等存储源
- ⚙️ **站点配置** - 获取站点全局设置、存储源配置等
- 👨💼 **管理员功能** - 完整的后台管理功能，包括用户管理、权限控制、存储源管理等
- 📝 **类型安全** - 基于 Pydantic 2.x 的强类型支持和数据验证
- 🛡️ **错误处理** - 统一的异常处理和错误管理机制
- 📊 **日志记录** - 完整的操作日志和调试信息
- 🔧 **装饰器支持** - 自动参数解析和模型验证
## 📦 安装（两种安装方式选择一种即可，建议从PyPI安装）
### 从 PyPI 安装（推荐）
```bash
pip install zfile-pysdk
```
### 从源码安装
```bash
git clone https://github.com/cuckoo711/zfile_sdk.git
cd zfile_sdk
pip install -r requirements.txt
pip install -e .
```
### 依赖要求
- Python 3.10+
- requests ~= 2.32.4
- pydantic ~= 2.11.7
- urllib3 ~= 2.5.0
### 更新方式
#### 从 PyPI 更新
```bash
pip install --upgrade zfile-pysdk
```
#### 从源码更新
```bash
git pull origin main
pip install -r requirements.txt
pip install -e .
```
## 🚀 快速开始
### 基础用法
```python
# 导入核心客户端
from ZfileSDK.utils import ApiClient
```
### 创建客户端实例
```python
# 创建客户端实例
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()
```
### 使用上下文管理器
```python
# 使用上下文管理器自动处理登录和注销
with ApiClient(base_url="http://localhost:8080") as client:
client.login(username="admin", password="password")
# 执行各种操作...
# 自动清理资源
```
### 文件操作示例
```python
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
)
```
### 管理员功能示例
```python
from ZfileSDK.admin import UserManagement, StorageSourceModuleBasic
# 用户管理
user_mgmt = UserManagement(client)
users = user_mgmt.list_users(
page=1,
size=10,
order_by="id",
order_direction="desc"
)
# 存储源管理
storage_mgmt = StorageSourceModuleBasic(client)
storages = storage_mgmt.list_storage_sources()
```
### 短链生成示例
```python
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 # 主模块初始化导入
│ ├── admin/ # 管理员功能模块
│ │ ├── __init__.py # 后台管理员模块导入
│ │ ├── user_management.py # 用户管理
│ │ ├── login_module.py # 登录模块
│ │ ├── permission_module.py # 权限模块
│ │ ├── login_log_management.py # 登录日志管理
│ │ ├── single_sign_on_management.py # 单点登录管理
│ │ ├── site_setting_module.py # 站点设置
│ │ ├── storage_source_module_basic.py # 存储源基础管理
│ │ ├── storage_source_module_filter_file.py # 存储源过滤文件
│ │ ├── storage_source_module_metadata.py # 存储源元数据
│ │ ├── storage_source_module_permission.py # 存储源权限
│ │ ├── storage_source_module_readme.py # 存储源README
│ │ ├── rule_management_view_rules.py # 显示规则管理
│ │ ├── rule_management_upload_rules.py # 上传规则管理
│ │ ├── rule_matcher_helper.py # 规则匹配辅助
│ │ ├── direct_link_management.py # 直链管理
│ │ ├── direct_link_log_management.py # 直链日志管理
│ │ └── ip_address_helper.py # IP地址辅助工具
│ ├── 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 # 单点登录模块
│ │ ├── single_sign_on_interface.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 认证回调
│ ├── utils/ # 核心工具模块
│ │ ├── __init__.py # 工具初始化导入
│ │ ├── api_client.py # HTTP 客户端封装
│ │ ├── models.py # Pydantic 数据模型
│ │ ├── exceptions.py # 异常定义
│ │ ├── logger.py # 日志处理
│ │ └── base.py # 基础类和装饰器
│ └── py.typed # 类型标注文件
├── docs/ # 文档目录
│ ├── README.md # 项目说明
│ ├── LICENSE # 许可证
│ └── LICENSE_CN # 中文许可证
├── requirements.txt # 依赖列表
├── setup.py # 安装脚本
├── pyproject.toml # 项目配置
├── MANIFEST.in # 打包配置
├── clean_for_release.sh # 发布清理脚本
└── update_version.py # 版本更新脚本
```
## 🔧 核心功能
### 前台功能模块 (front/)
| 模块 | 功能描述 |
|---------------------------------------------|--------------------------|
| **file_list_module** | 文件列表查看、存储搜索、单个文件信息获取 |
| **file_operation_module** | 文件操作（创建、删除、重命名、移动、复制、上传） |
| **site_basic_module** | 站点基础信息和配置获取、存储源配置 |
| **user_interface** | 用户登录、密码管理、验证码获取 |
| **short_link** | 批量生成直链和短链 |
| **direct_short_chain_module** | 直链短链生成和管理 |
| **initialization_module** | 系统初始化和配置检查 |
| **single_sign_on** | 单点登录功能 |
| **single_sign_on_interface** | 单点登录接口 |
| **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网盘集成 |
| **open_115_url_controller** | 115网盘 URL 控制器 |
| **onedrive_authentication_callback_module** | OneDrive 认证回调 |
### 管理员功能模块 (admin/)
| 模块 | 功能描述 |
|---------------------------------------|--------------------|
| **user_management** | 用户管理（增删改查、复制、权限设置） |
| **login_module** | 登录模块（2FA验证、设备绑定） |
| **permission_module** | 权限模块（权限列表查看） |
| **login_log_management** | 登录日志管理（日志查询） |
| **single_sign_on_management** | 单点登录管理（SSO服务商配置） |
| **site_setting_module** | 站点设置（全局配置管理） |
| **storage_source_module_basic** | 存储源基础管理（增删改查、排序） |
| **storage_source_module_filter_file** | 存储源过滤文件管理 |
| **storage_source_module_metadata** | 存储源元数据（支持类型、参数定义） |
| **storage_source_module_permission** | 存储源权限控制 |
| **storage_source_module_readme** | 存储源README和密码文件夹管理 |
| **rule_management_view_rules** | 显示规则管理（规则增删改查、测试） |
| **rule_management_upload_rules** | 上传规则管理（规则增删改查、测试） |
| **rule_matcher_helper** | 规则匹配测试辅助工具 |
| **direct_link_management** | 直链管理（直链增删改查） |
| **direct_link_log_management** | 直链日志管理（日志查询） |
| **ip_address_helper** | IP地址辅助工具（IP信息查询） |
### 工具模块 (utils/)
- **ApiClient**: 核心 HTTP 客户端，提供统一的 API 调用接口和会话管理
- **Models**: 基于 Pydantic 2.x 的数据模型，确保类型安全和数据验证
- **Exceptions**: 自定义异常类，提供详细的错误信息和统一的错误处理
- **Logger**: 日志处理工具，支持多级别日志记录
- **Base**: 基础类和装饰器，提供自动参数解析功能
## 🔐 认证和安全
### 登录认证
```python
# 基础登录
client.login(username="user", password="pass")
# 带验证码登录
client.login(
username="user",
password="pass",
verify_code="1234",
verify_code_uuid="uuid-string"
)
```
### Token 管理
```python
# 获取当前 token
token = client.token
# 使用预设 token 创建客户端
client = ApiClient(base_url="http://localhost:8080", token="your-token")
# 检查管理员权限
if client.is_admin:
print("当前用户具有管理员权限")
```
## 🛠️ 高级用法
### 自定义请求
```python
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"})
```
### 错误处理
```python
from ZfileSDK.utils 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}")
```
### 使用装饰器
```python
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文档](https://api.zfile.vip/)。
## 🤝 贡献指南
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) 文件了解详情，或查看 [LICENSE_CN](./LICENSE_CN) 文件的中文版本。
## 🔗 相关链接
- [PyPI 包页面](https://pypi.org/project/zfile-pysdk/)
- [ZFile 官方网站](https://www.zfile.vip/)
- [ZFile GitHub](https://github.com/zfile-dev/zfile)
- [问题反馈](https://github.com/cuckoo711/zfile_sdk/issues)
## 📞 支持
如果您在使用过程中遇到问题，请通过以下方式获取帮助：
- 查看 [官方API文档](https://api.zfile.vip/)
- 提交 [Issue](https://github.com/cuckoo711/zfile_sdk/issues)
- 向我发送[邮件](mailto:3038604221@qq.com)获取支持
## 📝 注意事项
- 本 SDK 仅支持 ZFile 版本 4.0.1 及以上。
- 当前版本：**1.1.1**
- 包名：**zfile-pysdk**
---
**注意**: 本 SDK 需要配合 ZFile 后端服务使用，请确保您的 ZFile 服务正常运行。
Raw data
{
"_id": null,
"home_page": "https://github.com/cuckoo711/zfile_sdk",
"name": "zfile-pysdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "zfile, file management, api, sdk, cloud storage, file sharing",
"author": "cuckoo",
"author_email": "cuckoo <3038604221@qq.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/f3/39362898158ea54d4082f1225e5047849e52edcc89a2bd70c73a09893286/zfile_pysdk-1.1.1.tar.gz",
"platform": null,
"description": "# ZFile SDK\n\n\u4e00\u4e2a\u529f\u80fd\u5b8c\u6574\u7684 Python SDK\uff0c\u7528\u4e8e\u4e0e ZFile \u6587\u4ef6\u7ba1\u7406\u7cfb\u7edf\u8fdb\u884c\u4ea4\u4e92\u3002\u8be5 SDK \u5c01\u88c5\u4e86\u524d\u7aef\u7528\u6237\u548c\u7ba1\u7406\u5458\u7684\u5b8c\u6574 API \u63a5\u53e3\uff0c\u63d0\u4f9b\u4e86\u57fa\u4e8e\nPydantic \u7684\u7c7b\u578b\u5b89\u5168\u8bf7\u6c42/\u54cd\u5e94\u5904\u7406\u548c\u7edf\u4e00\u7684\u9519\u8bef\u7ba1\u7406\u673a\u5236\u3002\n\n## \u2728 \u7279\u6027\n\n- \ud83d\udd10 **\u5b8c\u6574\u7684\u8ba4\u8bc1\u7cfb\u7edf** - \u652f\u6301\u7528\u6237\u767b\u5f55\u3001\u7ba1\u7406\u5458\u8ba4\u8bc1\u3001\u9a8c\u8bc1\u7801\u548c\u4f1a\u8bdd\u7ba1\u7406\n- \ud83d\udcc1 **\u6587\u4ef6\u7ba1\u7406\u529f\u80fd** - \u6587\u4ef6\u5217\u8868\u67e5\u770b\u3001\u6587\u4ef6\u64cd\u4f5c\uff08\u4e0a\u4f20\u3001\u4e0b\u8f7d\u3001\u91cd\u547d\u540d\u3001\u79fb\u52a8\u3001\u590d\u5236\u3001\u5220\u9664\uff09\n- \ud83d\udd17 **\u94fe\u63a5\u7ba1\u7406** - \u6279\u91cf\u751f\u6210\u76f4\u94fe\u548c\u77ed\u94fe\n- \ud83c\udf10 **\u591a\u5e73\u53f0\u96c6\u6210** - \u652f\u6301 Google Drive\u3001OneDrive\u3001SharePoint\u3001S3\u3001115\u7f51\u76d8\u7b49\u5b58\u50a8\u6e90\n- \u2699\ufe0f **\u7ad9\u70b9\u914d\u7f6e** - \u83b7\u53d6\u7ad9\u70b9\u5168\u5c40\u8bbe\u7f6e\u3001\u5b58\u50a8\u6e90\u914d\u7f6e\u7b49\n- \ud83d\udc68\u200d\ud83d\udcbc **\u7ba1\u7406\u5458\u529f\u80fd** - \u5b8c\u6574\u7684\u540e\u53f0\u7ba1\u7406\u529f\u80fd\uff0c\u5305\u62ec\u7528\u6237\u7ba1\u7406\u3001\u6743\u9650\u63a7\u5236\u3001\u5b58\u50a8\u6e90\u7ba1\u7406\u7b49\n- \ud83d\udcdd **\u7c7b\u578b\u5b89\u5168** - \u57fa\u4e8e Pydantic 2.x \u7684\u5f3a\u7c7b\u578b\u652f\u6301\u548c\u6570\u636e\u9a8c\u8bc1\n- \ud83d\udee1\ufe0f **\u9519\u8bef\u5904\u7406** - \u7edf\u4e00\u7684\u5f02\u5e38\u5904\u7406\u548c\u9519\u8bef\u7ba1\u7406\u673a\u5236\n- \ud83d\udcca **\u65e5\u5fd7\u8bb0\u5f55** - \u5b8c\u6574\u7684\u64cd\u4f5c\u65e5\u5fd7\u548c\u8c03\u8bd5\u4fe1\u606f\n- \ud83d\udd27 **\u88c5\u9970\u5668\u652f\u6301** - \u81ea\u52a8\u53c2\u6570\u89e3\u6790\u548c\u6a21\u578b\u9a8c\u8bc1\n\n## \ud83d\udce6 \u5b89\u88c5\uff08\u4e24\u79cd\u5b89\u88c5\u65b9\u5f0f\u9009\u62e9\u4e00\u79cd\u5373\u53ef\uff0c\u5efa\u8bae\u4ecePyPI\u5b89\u88c5\uff09\n\n### \u4ece PyPI \u5b89\u88c5\uff08\u63a8\u8350\uff09\n\n```bash\npip install zfile-pysdk\n```\n\n### \u4ece\u6e90\u7801\u5b89\u88c5\n\n```bash\ngit clone https://github.com/cuckoo711/zfile_sdk.git\ncd zfile_sdk\npip install -r requirements.txt\npip install -e .\n```\n\n### \u4f9d\u8d56\u8981\u6c42\n\n- Python 3.10+\n- requests ~= 2.32.4\n- pydantic ~= 2.11.7\n- urllib3 ~= 2.5.0\n\n### \u66f4\u65b0\u65b9\u5f0f\n\n#### \u4ece PyPI \u66f4\u65b0\n\n```bash\npip install --upgrade zfile-pysdk\n```\n\n#### \u4ece\u6e90\u7801\u66f4\u65b0\n\n```bash\ngit pull origin main\npip install -r requirements.txt\npip install -e .\n```\n\n## \ud83d\ude80 \u5feb\u901f\u5f00\u59cb\n\n### \u57fa\u7840\u7528\u6cd5\n\n```python\n# \u5bfc\u5165\u6838\u5fc3\u5ba2\u6237\u7aef\nfrom ZfileSDK.utils import ApiClient\n```\n\n### \u521b\u5efa\u5ba2\u6237\u7aef\u5b9e\u4f8b\n\n```python\n# \u521b\u5efa\u5ba2\u6237\u7aef\u5b9e\u4f8b\nclient = ApiClient(base_url=\"http://localhost:8080\")\n\n# \u7528\u6237\u767b\u5f55\nclient.login(username=\"your_username\", password=\"your_password\")\n\n# \u68c0\u67e5\u767b\u5f55\u72b6\u6001\nprint(f\"\u662f\u5426\u4e3a\u7ba1\u7406\u5458: {client.is_admin}\")\nprint(f\"\u5f53\u524d Token: {client.token}\")\n\n# \u4f7f\u7528\u5b8c\u6bd5\u540e\u6ce8\u9500\nclient.logout()\n```\n\n### \u4f7f\u7528\u4e0a\u4e0b\u6587\u7ba1\u7406\u5668\n\n```python\n# \u4f7f\u7528\u4e0a\u4e0b\u6587\u7ba1\u7406\u5668\u81ea\u52a8\u5904\u7406\u767b\u5f55\u548c\u6ce8\u9500\nwith ApiClient(base_url=\"http://localhost:8080\") as client:\n client.login(username=\"admin\", password=\"password\")\n # \u6267\u884c\u5404\u79cd\u64cd\u4f5c...\n # \u81ea\u52a8\u6e05\u7406\u8d44\u6e90\n```\n\n### \u6587\u4ef6\u64cd\u4f5c\u793a\u4f8b\n\n```python\nfrom ZfileSDK.front import FileListModule, FileOperationModule\n\n# \u83b7\u53d6\u6587\u4ef6\u5217\u8868\nfile_list_module = FileListModule(client)\nfiles = file_list_module.storage_files(\n storage_key=\"local\",\n path=\"/\",\n password=None\n)\n\n# \u521b\u5efa\u6587\u4ef6\u5939\nfile_op_module = FileOperationModule(client)\nresult = file_op_module.mkdir(\n storage_key=\"local\",\n path=\"/\",\n name=\"\u65b0\u6587\u4ef6\u5939\",\n password=None\n)\n```\n\n### \u7ba1\u7406\u5458\u529f\u80fd\u793a\u4f8b\n\n```python\nfrom ZfileSDK.admin import UserManagement, StorageSourceModuleBasic\n\n# \u7528\u6237\u7ba1\u7406\nuser_mgmt = UserManagement(client)\nusers = user_mgmt.list_users(\n page=1,\n size=10,\n order_by=\"id\",\n order_direction=\"desc\"\n)\n\n# \u5b58\u50a8\u6e90\u7ba1\u7406\nstorage_mgmt = StorageSourceModuleBasic(client)\nstorages = storage_mgmt.list_storage_sources()\n```\n\n### \u77ed\u94fe\u751f\u6210\u793a\u4f8b\n\n```python\nfrom ZfileSDK.front import DirectShortChainModule\n\n# \u751f\u6210\u77ed\u94fe\nshort_link_module = DirectShortChainModule(client)\nlinks = short_link_module.batch_generate(\n storage_key=\"local\",\n paths=[\"/file1.txt\", \"/file2.txt\"],\n expire_time=3600,\n)\n```\n\n## \ud83d\udcc1 \u9879\u76ee\u7ed3\u6784\n\n```\nzfile_sdk/\n\u251c\u2500\u2500 ZfileSDK/\n\u2502 \u251c\u2500\u2500 __init__.py # \u4e3b\u6a21\u5757\u521d\u59cb\u5316\u5bfc\u5165\n\u2502 \u251c\u2500\u2500 admin/ # \u7ba1\u7406\u5458\u529f\u80fd\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # \u540e\u53f0\u7ba1\u7406\u5458\u6a21\u5757\u5bfc\u5165\n\u2502 \u2502 \u251c\u2500\u2500 user_management.py # \u7528\u6237\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 login_module.py # \u767b\u5f55\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 permission_module.py # \u6743\u9650\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 login_log_management.py # \u767b\u5f55\u65e5\u5fd7\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 single_sign_on_management.py # \u5355\u70b9\u767b\u5f55\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 site_setting_module.py # \u7ad9\u70b9\u8bbe\u7f6e\n\u2502 \u2502 \u251c\u2500\u2500 storage_source_module_basic.py # \u5b58\u50a8\u6e90\u57fa\u7840\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 storage_source_module_filter_file.py # \u5b58\u50a8\u6e90\u8fc7\u6ee4\u6587\u4ef6\n\u2502 \u2502 \u251c\u2500\u2500 storage_source_module_metadata.py # \u5b58\u50a8\u6e90\u5143\u6570\u636e\n\u2502 \u2502 \u251c\u2500\u2500 storage_source_module_permission.py # \u5b58\u50a8\u6e90\u6743\u9650\n\u2502 \u2502 \u251c\u2500\u2500 storage_source_module_readme.py # \u5b58\u50a8\u6e90README\n\u2502 \u2502 \u251c\u2500\u2500 rule_management_view_rules.py # \u663e\u793a\u89c4\u5219\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 rule_management_upload_rules.py # \u4e0a\u4f20\u89c4\u5219\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 rule_matcher_helper.py # \u89c4\u5219\u5339\u914d\u8f85\u52a9\n\u2502 \u2502 \u251c\u2500\u2500 direct_link_management.py # \u76f4\u94fe\u7ba1\u7406\n\u2502 \u2502 \u251c\u2500\u2500 direct_link_log_management.py # \u76f4\u94fe\u65e5\u5fd7\u7ba1\u7406\n\u2502 \u2502 \u2514\u2500\u2500 ip_address_helper.py # IP\u5730\u5740\u8f85\u52a9\u5de5\u5177\n\u2502 \u251c\u2500\u2500 front/ # \u524d\u53f0\u7528\u6237\u529f\u80fd\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # \u7528\u6237\u524d\u53f0\u521d\u59cb\u5316\u5bfc\u5165\n\u2502 \u2502 \u251c\u2500\u2500 file_list_module.py # \u6587\u4ef6\u5217\u8868\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 file_operation_module.py # \u6587\u4ef6\u64cd\u4f5c\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 site_basic_module.py # \u7ad9\u70b9\u57fa\u7840\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 user_interface.py # \u7528\u6237\u63a5\u53e3\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 short_link.py # \u77ed\u94fe\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 direct_short_chain_module.py # \u76f4\u94fe\u77ed\u94fe\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 initialization_module.py # \u521d\u59cb\u5316\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 single_sign_on.py # \u5355\u70b9\u767b\u5f55\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 single_sign_on_interface.py # \u5355\u70b9\u767b\u5f55\u63a5\u53e3\n\u2502 \u2502 \u251c\u2500\u2500 server_proxy_download.py # \u670d\u52a1\u5668\u4ee3\u7406\u4e0b\u8f7d\n\u2502 \u2502 \u251c\u2500\u2500 server_proxy_upload.py # \u670d\u52a1\u5668\u4ee3\u7406\u4e0a\u4f20\n\u2502 \u2502 \u251c\u2500\u2500 onlyoffice_related_interfaces.py # OnlyOffice \u63a5\u53e3\n\u2502 \u2502 \u251c\u2500\u2500 gd_tools_assistive_module.py # Google Drive \u5de5\u5177\n\u2502 \u2502 \u251c\u2500\u2500 sharepoint_tools_assistive_module.py # SharePoint \u5de5\u5177\n\u2502 \u2502 \u251c\u2500\u2500 s3_tools_assistive_module.py # S3 \u5de5\u5177\n\u2502 \u2502 \u251c\u2500\u2500 oneonefive_tools_assistive_module.py # 115\u7f51\u76d8\u5de5\u5177\n\u2502 \u2502 \u251c\u2500\u2500 open_115_url_controller.py # 115\u7f51\u76d8 URL \u63a7\u5236\u5668\n\u2502 \u2502 \u2514\u2500\u2500 onedrive_authentication_callback_module.py # OneDrive \u8ba4\u8bc1\u56de\u8c03\n\u2502 \u251c\u2500\u2500 utils/ # \u6838\u5fc3\u5de5\u5177\u6a21\u5757\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # \u5de5\u5177\u521d\u59cb\u5316\u5bfc\u5165\n\u2502 \u2502 \u251c\u2500\u2500 api_client.py # HTTP \u5ba2\u6237\u7aef\u5c01\u88c5\n\u2502 \u2502 \u251c\u2500\u2500 models.py # Pydantic \u6570\u636e\u6a21\u578b\n\u2502 \u2502 \u251c\u2500\u2500 exceptions.py # \u5f02\u5e38\u5b9a\u4e49\n\u2502 \u2502 \u251c\u2500\u2500 logger.py # \u65e5\u5fd7\u5904\u7406\n\u2502 \u2502 \u2514\u2500\u2500 base.py # \u57fa\u7840\u7c7b\u548c\u88c5\u9970\u5668\n\u2502 \u2514\u2500\u2500 py.typed # \u7c7b\u578b\u6807\u6ce8\u6587\u4ef6\n\u251c\u2500\u2500 docs/ # \u6587\u6863\u76ee\u5f55\n\u2502 \u251c\u2500\u2500 README.md # \u9879\u76ee\u8bf4\u660e\n\u2502 \u251c\u2500\u2500 LICENSE # \u8bb8\u53ef\u8bc1\n\u2502 \u2514\u2500\u2500 LICENSE_CN # \u4e2d\u6587\u8bb8\u53ef\u8bc1\n\u251c\u2500\u2500 requirements.txt # \u4f9d\u8d56\u5217\u8868\n\u251c\u2500\u2500 setup.py # \u5b89\u88c5\u811a\u672c\n\u251c\u2500\u2500 pyproject.toml # \u9879\u76ee\u914d\u7f6e\n\u251c\u2500\u2500 MANIFEST.in # \u6253\u5305\u914d\u7f6e\n\u251c\u2500\u2500 clean_for_release.sh # \u53d1\u5e03\u6e05\u7406\u811a\u672c\n\u2514\u2500\u2500 update_version.py # \u7248\u672c\u66f4\u65b0\u811a\u672c\n```\n\n## \ud83d\udd27 \u6838\u5fc3\u529f\u80fd\n\n### \u524d\u53f0\u529f\u80fd\u6a21\u5757 (front/)\n\n| \u6a21\u5757 | \u529f\u80fd\u63cf\u8ff0 |\n|---------------------------------------------|--------------------------|\n| **file_list_module** | \u6587\u4ef6\u5217\u8868\u67e5\u770b\u3001\u5b58\u50a8\u641c\u7d22\u3001\u5355\u4e2a\u6587\u4ef6\u4fe1\u606f\u83b7\u53d6 |\n| **file_operation_module** | \u6587\u4ef6\u64cd\u4f5c\uff08\u521b\u5efa\u3001\u5220\u9664\u3001\u91cd\u547d\u540d\u3001\u79fb\u52a8\u3001\u590d\u5236\u3001\u4e0a\u4f20\uff09 |\n| **site_basic_module** | \u7ad9\u70b9\u57fa\u7840\u4fe1\u606f\u548c\u914d\u7f6e\u83b7\u53d6\u3001\u5b58\u50a8\u6e90\u914d\u7f6e |\n| **user_interface** | \u7528\u6237\u767b\u5f55\u3001\u5bc6\u7801\u7ba1\u7406\u3001\u9a8c\u8bc1\u7801\u83b7\u53d6 |\n| **short_link** | \u6279\u91cf\u751f\u6210\u76f4\u94fe\u548c\u77ed\u94fe |\n| **direct_short_chain_module** | \u76f4\u94fe\u77ed\u94fe\u751f\u6210\u548c\u7ba1\u7406 |\n| **initialization_module** | \u7cfb\u7edf\u521d\u59cb\u5316\u548c\u914d\u7f6e\u68c0\u67e5 |\n| **single_sign_on** | \u5355\u70b9\u767b\u5f55\u529f\u80fd |\n| **single_sign_on_interface** | \u5355\u70b9\u767b\u5f55\u63a5\u53e3 |\n| **server_proxy_download** | \u670d\u52a1\u5668\u4ee3\u7406\u4e0b\u8f7d |\n| **server_proxy_upload** | \u670d\u52a1\u5668\u4ee3\u7406\u4e0a\u4f20 |\n| **onlyoffice_related_interfaces** | OnlyOffice \u6587\u6863\u9884\u89c8\u548c\u5728\u7ebf\u7f16\u8f91 |\n| **gd_tools_assistive_module** | Google Drive \u96c6\u6210\u548c\u6587\u4ef6\u64cd\u4f5c |\n| **sharepoint_tools_assistive_module** | SharePoint \u96c6\u6210\u548c\u6587\u4ef6\u7ba1\u7406 |\n| **s3_tools_assistive_module** | AWS S3 \u517c\u5bb9\u5b58\u50a8\u96c6\u6210 |\n| **oneonefive_tools_assistive_module** | 115\u7f51\u76d8\u96c6\u6210 |\n| **open_115_url_controller** | 115\u7f51\u76d8 URL \u63a7\u5236\u5668 |\n| **onedrive_authentication_callback_module** | OneDrive \u8ba4\u8bc1\u56de\u8c03 |\n\n### \u7ba1\u7406\u5458\u529f\u80fd\u6a21\u5757 (admin/)\n\n| \u6a21\u5757 | \u529f\u80fd\u63cf\u8ff0 |\n|---------------------------------------|--------------------|\n| **user_management** | \u7528\u6237\u7ba1\u7406\uff08\u589e\u5220\u6539\u67e5\u3001\u590d\u5236\u3001\u6743\u9650\u8bbe\u7f6e\uff09 |\n| **login_module** | \u767b\u5f55\u6a21\u5757\uff082FA\u9a8c\u8bc1\u3001\u8bbe\u5907\u7ed1\u5b9a\uff09 |\n| **permission_module** | \u6743\u9650\u6a21\u5757\uff08\u6743\u9650\u5217\u8868\u67e5\u770b\uff09 |\n| **login_log_management** | \u767b\u5f55\u65e5\u5fd7\u7ba1\u7406\uff08\u65e5\u5fd7\u67e5\u8be2\uff09 |\n| **single_sign_on_management** | \u5355\u70b9\u767b\u5f55\u7ba1\u7406\uff08SSO\u670d\u52a1\u5546\u914d\u7f6e\uff09 |\n| **site_setting_module** | \u7ad9\u70b9\u8bbe\u7f6e\uff08\u5168\u5c40\u914d\u7f6e\u7ba1\u7406\uff09 |\n| **storage_source_module_basic** | \u5b58\u50a8\u6e90\u57fa\u7840\u7ba1\u7406\uff08\u589e\u5220\u6539\u67e5\u3001\u6392\u5e8f\uff09 |\n| **storage_source_module_filter_file** | \u5b58\u50a8\u6e90\u8fc7\u6ee4\u6587\u4ef6\u7ba1\u7406 |\n| **storage_source_module_metadata** | \u5b58\u50a8\u6e90\u5143\u6570\u636e\uff08\u652f\u6301\u7c7b\u578b\u3001\u53c2\u6570\u5b9a\u4e49\uff09 |\n| **storage_source_module_permission** | \u5b58\u50a8\u6e90\u6743\u9650\u63a7\u5236 |\n| **storage_source_module_readme** | \u5b58\u50a8\u6e90README\u548c\u5bc6\u7801\u6587\u4ef6\u5939\u7ba1\u7406 |\n| **rule_management_view_rules** | \u663e\u793a\u89c4\u5219\u7ba1\u7406\uff08\u89c4\u5219\u589e\u5220\u6539\u67e5\u3001\u6d4b\u8bd5\uff09 |\n| **rule_management_upload_rules** | \u4e0a\u4f20\u89c4\u5219\u7ba1\u7406\uff08\u89c4\u5219\u589e\u5220\u6539\u67e5\u3001\u6d4b\u8bd5\uff09 |\n| **rule_matcher_helper** | \u89c4\u5219\u5339\u914d\u6d4b\u8bd5\u8f85\u52a9\u5de5\u5177 |\n| **direct_link_management** | \u76f4\u94fe\u7ba1\u7406\uff08\u76f4\u94fe\u589e\u5220\u6539\u67e5\uff09 |\n| **direct_link_log_management** | \u76f4\u94fe\u65e5\u5fd7\u7ba1\u7406\uff08\u65e5\u5fd7\u67e5\u8be2\uff09 |\n| **ip_address_helper** | IP\u5730\u5740\u8f85\u52a9\u5de5\u5177\uff08IP\u4fe1\u606f\u67e5\u8be2\uff09 |\n\n### \u5de5\u5177\u6a21\u5757 (utils/)\n\n- **ApiClient**: \u6838\u5fc3 HTTP \u5ba2\u6237\u7aef\uff0c\u63d0\u4f9b\u7edf\u4e00\u7684 API \u8c03\u7528\u63a5\u53e3\u548c\u4f1a\u8bdd\u7ba1\u7406\n- **Models**: \u57fa\u4e8e Pydantic 2.x \u7684\u6570\u636e\u6a21\u578b\uff0c\u786e\u4fdd\u7c7b\u578b\u5b89\u5168\u548c\u6570\u636e\u9a8c\u8bc1\n- **Exceptions**: \u81ea\u5b9a\u4e49\u5f02\u5e38\u7c7b\uff0c\u63d0\u4f9b\u8be6\u7ec6\u7684\u9519\u8bef\u4fe1\u606f\u548c\u7edf\u4e00\u7684\u9519\u8bef\u5904\u7406\n- **Logger**: \u65e5\u5fd7\u5904\u7406\u5de5\u5177\uff0c\u652f\u6301\u591a\u7ea7\u522b\u65e5\u5fd7\u8bb0\u5f55\n- **Base**: \u57fa\u7840\u7c7b\u548c\u88c5\u9970\u5668\uff0c\u63d0\u4f9b\u81ea\u52a8\u53c2\u6570\u89e3\u6790\u529f\u80fd\n\n## \ud83d\udd10 \u8ba4\u8bc1\u548c\u5b89\u5168\n\n### \u767b\u5f55\u8ba4\u8bc1\n\n```python\n# \u57fa\u7840\u767b\u5f55\nclient.login(username=\"user\", password=\"pass\")\n\n# \u5e26\u9a8c\u8bc1\u7801\u767b\u5f55\nclient.login(\n username=\"user\",\n password=\"pass\",\n verify_code=\"1234\",\n verify_code_uuid=\"uuid-string\"\n)\n```\n\n### Token \u7ba1\u7406\n\n```python\n# \u83b7\u53d6\u5f53\u524d token\ntoken = client.token\n\n# \u4f7f\u7528\u9884\u8bbe token \u521b\u5efa\u5ba2\u6237\u7aef\nclient = ApiClient(base_url=\"http://localhost:8080\", token=\"your-token\")\n\n# \u68c0\u67e5\u7ba1\u7406\u5458\u6743\u9650\nif client.is_admin:\n print(\"\u5f53\u524d\u7528\u6237\u5177\u6709\u7ba1\u7406\u5458\u6743\u9650\")\n```\n\n## \ud83d\udee0\ufe0f \u9ad8\u7ea7\u7528\u6cd5\n\n### \u81ea\u5b9a\u4e49\u8bf7\u6c42\n\n```python\nfrom ZfileSDK.utils.models import AjaxJsonVoid\n\n# GET \u8bf7\u6c42\nresponse = client.make_common_request(\"GET\", \"/api/endpoint\", params={\"key\": \"value\"})\n\n# POST \u8bf7\u6c42\nresponse = client.post(\"POST\", \"/api/endpoint\", data={\"key\": \"value\"})\n```\n\n### \u9519\u8bef\u5904\u7406\n\n```python\nfrom ZfileSDK.utils import ApiException, CustomException\n\ntry:\n client.login(username=\"invalid\", password=\"invalid\")\nexcept CustomException as e:\n print(f\"\u4e1a\u52a1\u9519\u8bef: {e.msg} (\u4ee3\u7801: {e.code})\")\nexcept ApiException as e:\n print(f\"API \u9519\u8bef: {e.message}\")\n```\n\n### \u4f7f\u7528\u88c5\u9970\u5668\n\n```python\nfrom ZfileSDK.utils.base import auto_args_from_model\nfrom ZfileSDK.utils.models import FileListRequest\n\n\n# \u88c5\u9970\u5668\u81ea\u52a8\u89e3\u6790\u53c2\u6570\n@auto_args_from_model(model=FileListRequest)\ndef get_files(*, data: FileListRequest):\n # \u81ea\u52a8\u9a8c\u8bc1\u548c\u89e3\u6790\u53c2\u6570\n pass\n```\n\n## \ud83d\udcda API \u6587\u6863\n\n\u8be6\u7ec6\u7684 API \u6587\u6863\u8bf7\u53c2\u8003 [ZFile \u5b98\u65b9API\u6587\u6863](https://api.zfile.vip/)\u3002\n\n## \ud83e\udd1d \u8d21\u732e\u6307\u5357\n\n1. Fork \u672c\u4ed3\u5e93\n2. \u521b\u5efa\u7279\u6027\u5206\u652f (`git checkout -b feature/AmazingFeature`)\n3. \u63d0\u4ea4\u66f4\u6539 (`git commit -m 'Add some AmazingFeature'`)\n4. \u63a8\u9001\u5230\u5206\u652f (`git push origin feature/AmazingFeature`)\n5. \u521b\u5efa Pull Request\n6. \u786e\u4fdd\u4ee3\u7801\u7b26\u5408 PEP 8 \u98ce\u683c\u6307\u5357\n\n> \u8bf7\u786e\u4fdd\u60a8\u7684\u4ee3\u7801\u7ecf\u8fc7\u6d4b\u8bd5\uff0c\u5e76\u4e14\u6dfb\u52a0\u4e86\u5fc5\u8981\u7684\u6587\u6863\u6ce8\u91ca\u3002\n\n## \ud83d\udcc4 \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u91c7\u7528 MIT \u8bb8\u53ef\u8bc1 - \u67e5\u770b [LICENSE](./LICENSE) \u6587\u4ef6\u4e86\u89e3\u8be6\u60c5\uff0c\u6216\u67e5\u770b [LICENSE_CN](./LICENSE_CN) \u6587\u4ef6\u7684\u4e2d\u6587\u7248\u672c\u3002\n\n## \ud83d\udd17 \u76f8\u5173\u94fe\u63a5\n\n- [PyPI \u5305\u9875\u9762](https://pypi.org/project/zfile-pysdk/)\n- [ZFile \u5b98\u65b9\u7f51\u7ad9](https://www.zfile.vip/)\n- [ZFile GitHub](https://github.com/zfile-dev/zfile)\n- [\u95ee\u9898\u53cd\u9988](https://github.com/cuckoo711/zfile_sdk/issues)\n\n## \ud83d\udcde \u652f\u6301\n\n\u5982\u679c\u60a8\u5728\u4f7f\u7528\u8fc7\u7a0b\u4e2d\u9047\u5230\u95ee\u9898\uff0c\u8bf7\u901a\u8fc7\u4ee5\u4e0b\u65b9\u5f0f\u83b7\u53d6\u5e2e\u52a9\uff1a\n\n- \u67e5\u770b [\u5b98\u65b9API\u6587\u6863](https://api.zfile.vip/)\n- \u63d0\u4ea4 [Issue](https://github.com/cuckoo711/zfile_sdk/issues)\n- \u5411\u6211\u53d1\u9001[\u90ae\u4ef6](mailto:3038604221@qq.com)\u83b7\u53d6\u652f\u6301\n\n## \ud83d\udcdd \u6ce8\u610f\u4e8b\u9879\n\n- \u672c SDK \u4ec5\u652f\u6301 ZFile \u7248\u672c 4.0.1 \u53ca\u4ee5\u4e0a\u3002\n- \u5f53\u524d\u7248\u672c\uff1a**1.1.1**\n- \u5305\u540d\uff1a**zfile-pysdk**\n\n---\n\n**\u6ce8\u610f**: \u672c SDK \u9700\u8981\u914d\u5408 ZFile \u540e\u7aef\u670d\u52a1\u4f7f\u7528\uff0c\u8bf7\u786e\u4fdd\u60a8\u7684 ZFile \u670d\u52a1\u6b63\u5e38\u8fd0\u884c\u3002\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for ZFile API - \u529f\u80fd\u5b8c\u6574\u7684ZFile\u6587\u4ef6\u7ba1\u7406\u7cfb\u7edfSDK",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/cuckoo711/zfile_sdk/issues",
"Documentation": "https://api.zfile.vip/",
"Homepage": "https://github.com/cuckoo711/zfile_sdk",
"Source Code": "https://github.com/cuckoo711/zfile_sdk"
},
"split_keywords": [
"zfile",
" file management",
" api",
" sdk",
" cloud storage",
" file sharing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "10089d1ea9f51599b423b2bf17a19c70ee04a5bfa4e05677c9e8cd590fffe0c2",
"md5": "06fc97a523304cd8510d1486c5679a78",
"sha256": "a961d09f61981a70a53d10071ba16e3725cbb5d9e085b3cd6ce0dc5d9393c1f0"
},
"downloads": -1,
"filename": "zfile_pysdk-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06fc97a523304cd8510d1486c5679a78",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 75391,
"upload_time": "2025-07-12T15:12:13",
"upload_time_iso_8601": "2025-07-12T15:12:13.228451Z",
"url": "https://files.pythonhosted.org/packages/10/08/9d1ea9f51599b423b2bf17a19c70ee04a5bfa4e05677c9e8cd590fffe0c2/zfile_pysdk-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2ff339362898158ea54d4082f1225e5047849e52edcc89a2bd70c73a09893286",
"md5": "bbd991b07c2c94a25e95a2027359374b",
"sha256": "7d2fe4c306769e90fa9e935d2ce01afd674a1d98069458b10134e39c272128d7"
},
"downloads": -1,
"filename": "zfile_pysdk-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "bbd991b07c2c94a25e95a2027359374b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 60432,
"upload_time": "2025-07-12T15:12:15",
"upload_time_iso_8601": "2025-07-12T15:12:15.060447Z",
"url": "https://files.pythonhosted.org/packages/2f/f3/39362898158ea54d4082f1225e5047849e52edcc89a2bd70c73a09893286/zfile_pysdk-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 15:12:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cuckoo711",
"github_project": "zfile_sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
"~=",
"2.32.4"
]
]
},
{
"name": "pydantic",
"specs": [
[
"~=",
"2.11.7"
]
]
},
{
"name": "urllib3",
"specs": [
[
"~=",
"2.5.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
"~=",
"80.3.1"
]
]
},
{
"name": "requests-toolbelt",
"specs": [
[
"~=",
"1.0.0"
]
]
}
],
"lcname": "zfile-pysdk"
}
JSON
