zyd-dataset-up 0.17.0
Dataset Uploader SDK

# Dataset Uploader SDK 文档

用于上传文件和文件夹到数据集平台的 SDK。

## 目录
- [功能特性](#功能特性)
- [安装](#安装)
  - [pip 安装](#pip-安装推荐)
  - [开发模式安装](#开发模式安装)
  - [卸载与更新](#卸载与更新)
- [认证配置](#认证配置)
- [命令行使用](#命令行使用)
  - [上传文件](#上传单个文件)
  - [上传文件夹](#上传整个文件夹)
  - [目录操作](#目录操作)
  - [文件管理](#文件管理)
  - [任务控制](#停止正在运行的上传任务)
- [依赖项](#依赖项)

## 功能特性

- 上传单个文件到指定数据集
- 上传整个文件夹到指定数据集
- 支持指定目标路径
- 支持数据集版本控制
- 可以停止正在运行的上传任务
- 支持创建目录
- 支持删除文件
- 支持删除整个文件夹（包括子文件）
- 支持列出目录内容

## 安装

### pip 安装（推荐）

```bash
pip install dataset-up
```

### 开发模式安装

```bash
# 克隆仓库
git clone https://github.com/your-repo/dataset-up.git
cd dataset-up
# 构建分发包
python setup.py sdist bdist_wheel

# 安装构建好的包
pip install dist/dataset_up-0.1.0-py3-none-any.whl
# 以开发模式安装（代码修改即时生效）
pip install -e .
```

### 卸载与更新

```bash
# 卸载
pip uninstall dataset-up

# 更新到最新版本
pip install --upgrade dataset-up

# 更新到指定版本
pip install dataset-up==0.1.0
```

## 认证配置

在使用SDK功能前，需要先进行认证：

```bash
dataset-up login --ak YOUR_ACCESS_KEY --sk YOUR_SECRET_KEY
```

**参数说明**：
- `--ak`: Access Key（必需）
- `--sk`: Secret Key（必需）

## 命令行使用

### 上传单个文件

```bash
dataset-up upload-file \
  --dataset-id DATASET_ID \
  [--version VERSION] \
  --source-path SOURCE_PATH \
  [--target-path TARGET_PATH]
```

**参数说明**：
- `--dataset-id`: 数据集ID（必需）
- `--version`: 数据集版本（默认: "master"）
- `--source-path`: 本地文件路径（必需）
- `--target-path`: 目标路径（默认: "/"）

**示例**：
```bash
dataset-up upload-file \
  --dataset-id "8046425445713243579" \
  --version "master" \
  --source-path "D:\\test.txt" \
  --target-path "/test.txt"
```

### 上传整个文件夹

```bash
dataset-up upload-folder \
  --dataset-id DATASET_ID \
  [--version VERSION] \
  --source-path SOURCE_PATH \
  [--target-path TARGET_PATH]
```

**参数说明**：
- `--dataset-id`: 数据集ID（必需）
- `--version`: 数据集版本（默认: "master"）
- `--source-path`: 本地文件夹路径（必需）
- `--target-path`: 目标路径（默认: "/"）

**示例**：
```bash
dataset-up upload-folder \
  --dataset-id "8046425445713243579" \
  --version "master" \
  --source-path "D:\\test\\test_folder" \
  --target-path "/test_folder"
```

### 目录操作

#### 创建目录

```bash
dataset-up mkdir \
  --dataset-id DATASET_ID \
  [--version VERSION] \
  --target-path TARGET_PATH
```

**示例**：
```bash
dataset-up mkdir \
  --dataset-id "8046425445713243579" \
  --version "master" \
  --target-path "/new-directory"
```

#### 列出目录内容

```bash
dataset-up list \
  --dataset-id DATASET_ID \
  [--version VERSION] \
  [--target-path TARGET_PATH]
```

**示例**：
```bash
# 列出根目录
dataset-up list --dataset-id "8046425445713243579" --version "master"

# 列出指定目录
dataset-up list \
  --dataset-id "8046425445713243579" \
  --version "master" \
  --target-path "/test_dir"
```

### 文件管理

#### 删除文件

```bash
dataset-up delete-file \
  --dataset-id DATASET_ID \
  [--version VERSION] \
  --file FILE_PATH
```

**示例**：
```bash
dataset-up delete-file \
  --dataset-id "8046425445713243579" \
  --version "master" \
  --file "/path/to/file.txt"
```

#### 删除文件夹

```bash
dataset-up rmdir \
  --dataset-id DATASET_ID \
  [--version VERSION] \
  --dir DIRECTORY
```

**示例**：
```bash
dataset-up rmdir \
  --dataset-id "8046425445713243579" \
  --version "master" \
  --dir "/directory-to-delete"
```

### 停止正在运行的上传任务

```bash
dataset-up stop-running-uploading-process
```

## 依赖项

| 依赖包       | 安装命令                          | 平台特定说明                     |
|--------------|----------------------------------|--------------------------------|
| tqdm         | `pip install tqdm`               |                                |
| requests     | `pip install requests`           |                                |
| click        | `pip install click`              |                                |
| psutil       | `pip install psutil`             |                                |
| pytz         | `pip install pytz`               |                                |
| filelock     | `pip install filelock`           |                                |
| python-magic | 见下文                           | 需要系统级库支持               |

### python-magic 安装说明

- **Windows**:
  ```bash
  pip install python-magic-bin
  ```

- **Ubuntu/Debian**:
  ```bash
  sudo apt-get install libmagic1
  pip install python-magic
  ```

- **CentOS/RHEL**:
  ```bash
  sudo yum install libmagic
  pip install python-magic
  ```

- **macOS**:
  ```bash
  brew install libmagic
  pip install python-magic
  ```

### 断点续传

- 如果上传中断，只需重新执行相同的命令，程序会自动从断点处继续上传。