Metadata-Version: 2.4
Name: gravity-material-upload
Version: 1.0.3
Summary: Python SDK for material upload
Home-page: 
Author: GravityEngine
Author-email: pony@gravity-engine.com
License: Apache-2.0
Platform: all
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Requires-Dist: tos>=2.6.0
Requires-Dist: requests>=2.20.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: typing_extensions>=3.7
Requires-Dist: PyJWT>=2.0.0
Dynamic: author-email
Dynamic: license-file
Dynamic: platform

# Gravity Material Upload

Python SDK，用于批量上传图片和视频素材。

## 功能特性

- 🔍 **智能文件扫描** — 支持扫描目录、指定文件、通配符匹配，自动过滤有效的图片/视频文件
- 📤 **分片上传** — 基于 TOS 对象存储的分片上传，支持大文件传输
- 📊 **进度显示** — 双层进度条实时展示文件级和字节级上传进度
- 🖼️ **自动解析** — 自动获取图片/视频的宽高、时长、MD5 等元信息

## 支持的文件格式

| 类型 | 后缀                         |
| ---- | ---------------------------- |
| 图片 | `.png` `.jpg` `.jpeg` `.gif` |
| 视频 | `.mp4` `.3gp` `.avi` `.mov`  |

## 快速开始

### 1. 安装依赖

```bash
pip install gravity-material-upload
```

### 2. 使用示例

```python
from gravity_material_upload import MaterialClient

# 1. 创建客户端
client = MaterialClient(
    # app_key: 请在引力后台-设置-引力开发者中查看
    # URL: https://web.gravity-engine.com/#/manage/develop
    app_key="your_app_key",
)

# 2. 一键上传素材（扫描 + 上传）
client.upload_material(
    source_paths=["./video1.mp4", "./image1.png"], # 目标路径，支持目录、文件列表、通配符
    recursive=True,                           # 是否递归搜索子目录，在source_paths传入目录时生效
    allowed_extensions=[".png", ".mp4"], # 可选：自定义文件后缀白名单
    max_workers=5,                            # 可选：最大并发上传数
    upload_config={                           # 必填：自定义上传配置参数
        "album_id": 123,
        "remark": "your_remark",
    },
)
```

### `MaterialClient` 参数说明

| 参数      | 类型  | 说明                                                                                                                |
| --------- | ----- | ------------------------------------------------------------------------------------------------------------------- |
| `app_key` | `str` | **必填**。请在 [引力后台-设置-引力开发者](https://web.gravity-engine.com/#/manage/develop) 中查看 |

### `upload_material()` 参数说明

| 参数                 | 类型               | 默认值   | 说明                                                                                                                                                                 |
| -------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_paths`       | `str \| List[str]` | `"."`    | 目标路径。用法示例：<br>1. `["./file1.mp4", "./file2.png"]`: 仅上传这两个文件<br>2. `"./"`: 上传当前目录下所有匹配的文件<br>3. `"./data/*.mp4"`: 使用通配符匹配文件 |
| `recursive`          | `bool`             | `True`   | 是否递归搜索子目录                                                                                                                                                   |
| `allowed_extensions` | `Tuple[str, ...]`  | `None`   | 自定义文件后缀白名单，仅保留在默认支持列表中的后缀                                                                                                                   |
| `max_workers`        | `int`              | `5`      | 最大并发上传线程数                                                                                                                                                   |
| `upload_config`      | `Object`           | **必填** | 自定义上传配置参数，合并到接口根层级                                                                                                                                 |

## 环境要求

- Python >= 3.7

## 许可证

[Apache-2.0](LICENSE)
