Metadata-Version: 2.4
Name: gravity-material-upload
Version: 1.0.1
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
python -m pip install -e .
```

> 该命令会以**开发模式**安装本包及所有依赖（Pillow、tos、requests、opencv-python、tqdm）。

### 2. 使用示例

```python
from gravity_material_upload import MaterialClient

# 1. 创建客户端
client = MaterialClient(
    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",
    },
)
```

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

| 参数                 | 类型                  | 默认值         | 说明                                                                                   |
| -------------------- | --------------------- | -------------- | -------------------------------------------------------------------------------------- |
| `source_paths`       | `str \| List[str]`    | `"."`          | 目标路径，支持文件、目录、通配符，可使用相对路径                                       |
| `recursive`          | `bool`                | `True`         | 是否递归搜索子目录                                                                     |
| `allowed_extensions` | `Tuple[str, ...]`     | `None`         | 自定义文件后缀白名单，仅保留在默认支持列表中的后缀                                     |
| `max_workers`        | `int`                 | `5`            | 最大并发上传线程数                                                                     |
| `upload_config`      | `Object`         | **必填**       | 自定义上传配置参数，合并到接口根层级                                                   |

## 环境要求

- Python >= 3.7

## 许可证

[Apache-2.0](LICENSE)
