# clouds-storage-sdk

**Repository Path**: snail_tech/clouds-storage-sdk

## Basic Information

- **Project Name**: clouds-storage-sdk
- **Description**: 云存储sdk （类似openlist ），只提供基础的sdk功能
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-17
- **Last Updated**: 2025-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 云存储SDK

一个统一的云存储SDK，目前支持天翼云盘TV版，提供简洁易用的API接口。

## 🚀 功能特性

- **统一API接口**: 基于抽象基类的统一接口设计
- **天翼云盘TV版支持**: 完整支持天翼云盘TV版所有功能
- **四阶段登录流程**: 支持二维码登录、状态检测、序列化和恢复
- **文件操作**: 上传、下载、删除、移动、重命名等基本操作
- **文件夹管理**: 创建、删除、移动文件夹
- **文件搜索**: 支持全局文件搜索功能
- **快速上传**: 支持秒传功能，提高上传效率
- **回收站管理**: 支持回收站文件列表和清空操作

## 📦 安装

```bash
# 从源码安装
git clone https://gitee.com/snail_tech/clouds-storage-sdk.git
cd clouds-storage-sdk
pip install -e .
```

## 🎯 快速开始

### 基本使用示例

```python
from clouds_storage_sdk import CloudStorageClientFactory, LoginCredentials, PROVIDER_TIANYI_TV

# 1. 创建客户端
client = CloudStorageClientFactory.create_client(PROVIDER_TIANYI_TV)

# 2. 登录流程
# 触发登录
credentials = LoginCredentials(username='your_username', password='')
session_id = client.trigger_login(credentials)
print(f"请扫描二维码登录: {session_id}")

# 检测登录状态
import time
while True:
    persistent_info = client.check_login_status(session_id)
    if persistent_info:
        print("登录成功！")
        break
    time.sleep(5)

# 3. 基本操作
# 获取账户信息
account_info = client.get_account_info()
print(f"总空间: {account_info.total_space:,} bytes")

# 创建文件夹
folder = client.create_folder('我的测试文件夹')
print(f"创建文件夹: {folder.name} (ID: {folder.file_id})")

# 上传文件
with open('test.txt', 'rb') as f:
    file_data = f.read()
uploaded_file = client.upload_file('test.txt', file_data, folder.file_id)
print(f"上传成功: {uploaded_file.name} (ID: {uploaded_file.file_id})")

# 获取文件信息
file_info = client.get_file_info(uploaded_file.file_id, folder.file_id)
print(f"文件信息: {file_info.name}, 大小: {file_info.size} bytes")

# 下载文件
client.download_file(uploaded_file.file_id, 'downloaded_test.txt')
print("下载完成")

# 搜索文件
search_results = client.search_files('test')
print(f"搜索到 {len(search_results)} 个文件")

# 重命名文件
renamed_file = client.rename_file(uploaded_file.file_id, 'renamed_test.txt')
print(f"重命名成功: {renamed_file.name}")

# 移动文件
moved_file = client.move_file(renamed_file.file_id, folder.file_id)
print(f"移动成功: {moved_file.name}")

# 删除文件
client.delete_file(moved_file.file_id)
print("文件已删除")

# 删除文件夹
client.delete_file(folder.file_id)
print("文件夹已删除")
```

### 高级功能示例

```python
# 快速上传（秒传）
with open('large_file.zip', 'rb') as f:
    file_data = f.read()

# 检查是否可以秒传
if client.check_fast_upload('large_file.zip', file_data):
    # 使用秒传
    fast_uploaded = client.fast_upload_file('large_file.zip', file_data)
    print("秒传成功")
else:
    # 使用普通上传
    uploaded = client.upload_file('large_file.zip', file_data)
    print("普通上传成功")

# 获取下载链接
download_url = client.get_download_url(file_id)
print(f"下载链接: {download_url}")

# 回收站操作
trash_files = client.list_trash()
print(f"回收站文件: {len(trash_files)} 个")

# 清空回收站
client.empty_trash()
print("回收站已清空")

# 登录状态序列化与恢复
# 序列化登录信息
serialized_info = client.serialize_login_info()
print(f"序列化信息: {serialized_info}")

# 恢复登录状态
new_client = CloudStorageClientFactory.create_client(PROVIDER_TIANYI_TV)
if new_client.restore_login_from_string(serialized_info):
    print("登录状态恢复成功")
```

## 📚 核心API

### 登录相关

| 方法 | 描述 | 参数 | 返回值 |
|------|------|------|--------|
| `trigger_login` | 触发登录 | `credentials: LoginCredentials` | `str` |
| `check_login_status` | 检测登录状态 | `session_id: str` | `Optional[PersistentLoginInfo]` |
| `serialize_login_info` | 序列化登录信息 | 无 | `str` |
| `restore_login_from_string` | 恢复登录状态 | `serialized_info: str` | `bool` |

### 文件操作

| 方法 | 描述 | 参数 | 返回值 |
|------|------|------|--------|
| `list_files` | 列出文件 | `folder_id: str = None` | `List[CloudFile]` |
| `create_folder` | 创建文件夹 | `name: str, parent_id: str = None` | `CloudFile` |
| `upload_file` | 上传文件 | `file_name, file_data, parent_id=None, overwrite=False` | `CloudFile` |
| `download_file` | 下载文件 | `file_id: str, local_path: str` | `None` |
| `delete_file` | 删除文件 | `file_id: str` | `None` |
| `move_file` | 移动文件 | `file_id: str, target_folder_id: str` | `CloudFile` |
| `rename_file` | 重命名文件 | `file_id: str, new_name: str` | `CloudFile` |
| `get_file_info` | 获取文件信息 | `file_id: str, folder_id: str = None` | `CloudFile` |
| `search_files` | 搜索文件 | `query: str` | `List[CloudFile]` |
| `get_download_url` | 获取下载链接 | `file_id: str` | `str` |

### 快速上传

| 方法 | 描述 | 参数 | 返回值 |
|------|------|------|--------|
| `check_fast_upload` | 检查快速上传 | `file_name: str, file_data: bytes` | `bool` |
| `fast_upload_file` | 快速上传文件 | `file_name, file_data, parent_id=None` | `CloudFile` |

### 回收站操作

| 方法 | 描述 | 参数 | 返回值 |
|------|------|------|--------|
| `list_trash` | 回收站列表 | 无 | `List[TrashItem]` |
| `empty_trash` | 清空回收站 | 无 | `None` |

### 账户信息

| 方法 | 描述 | 参数 | 返回值 |
|------|------|------|--------|
| `get_account_info` | 获取账户信息 | 无 | `AccountInfo` |

## 📁 数据模型

### CloudFile
```python
@dataclass
class CloudFile:
    file_id: str          # 文件ID
    name: str            # 文件名
    path: str            # 完整路径
    size: int            # 文件大小（字节）
    is_folder: bool      # 是否为文件夹
    parent_id: Optional[str] = None      # 父文件夹ID
    created_at: Optional[datetime] = None  # 创建时间
    modified_at: Optional[datetime] = None # 修改时间
    md5: Optional[str] = None            # MD5哈希
```

### AccountInfo
```python
@dataclass
class AccountInfo:
    user_id: str         # 用户ID
    username: str        # 用户名
    email: Optional[str] = None         # 邮箱
    phone: Optional[str] = None         # 手机号
    total_space: int     # 总空间（字节）
    used_space: int      # 已用空间（字节）
```

## 🧪 测试

运行完整测试用例：

```bash
python test_comprehensive_real.py
```

测试用例包含以下功能测试：
- 登录流程测试
- 账户信息获取
- 文件夹创建
- 文件上传
- 文件信息获取
- 文件搜索
- 文件重命名
- 文件移动
- 快速上传（秒传）
- 文件下载
- 文件删除

## 📁 项目结构

```
clouds-storage-sdk/
├── clouds_storage_sdk/           # 核心SDK代码
│   ├── base/                    # 基础抽象类
│   ├── providers/               # 提供商实现
│   │   └── tianyi_tv/          # 天翼云盘TV版实现
│   ├── factory.py               # 工厂模式
│   └── constants.py             # 常量定义
├── test_comprehensive_real.py   # 综合测试用例
└── README.md                   # 使用说明
```

## 📋 版本信息

- **当前版本**: v0.3.0
- **支持平台**: 天翼云盘TV版
- **Python版本**: 3.8+

## 📄 许可证

MIT License