Metadata-Version: 2.4
Name: lims2-sdk
Version: 0.10.0
Summary: 生信云平台 Python SDK，提供图表上传和文件存储功能
Author-email: Lims2 Team <support@lims2.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: click>=8.0.0
Requires-Dist: oss2>=2.15.0
Requires-Dist: orjson>=3.8.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: plotly==6.2.0
Requires-Dist: kaleido

# Lims2 SDK

[![Python](https://img.shields.io/badge/python-≥3.9-green.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/lims2-sdk.svg)](https://pypi.org/project/lims2-sdk/)

生信云平台 Python SDK，提供图表上传和文件存储功能。

## 安装与配置

```bash
pip install -U lims2-sdk
```

设置环境变量：

```bash
export LIMS2_API_URL="your-api"
export LIMS2_API_TOKEN="your-api-token"
```

## 命令行使用

完整命令树和参数通过 `--help` 查看：

```bash
lims2 --help                          # 查看所有子命令
lims2 chart upload --help             # 查看图表上传所有参数
lims2 storage upload --help           # 查看文件上传所有参数
lims2 storage upload-dir --help       # 查看目录上传所有参数
lims2 storage info --help             # 查看文件信息查询参数
```

### 图表上传

参数说明（`lims2 chart upload --help`）：

```
Usage: lims2 chart upload [OPTIONS] [FILE_PATH]

  上传图表文件。FILE_PATH 为图表 JSON 文件路径；传 `-` 表示从标准输入读取。

Options:
  -p, --project-id TEXT      项目 ID  [required]
  -n, --name TEXT            图表名称（默认使用文件名）
  -s, --sample-id TEXT       样本 ID
  -t, --chart-type TEXT      图表类型（示例模式下必填）
  -d, --description TEXT     图表描述
  -c, --contrast TEXT        对比策略
  -a, --analysis-node TEXT   分析节点名称
  --precision INTEGER RANGE  浮点数精度（小数位数，0-10，默认 3）
  --retry INTEGER RANGE      网络重试次数（1-10，默认从配置读取）
  --timeout INTEGER          超时时间（秒，默认从配置读取）
  --example                  上传为示例数据（不会被自动删除）
  --data-file PATH           关联的数据文件路径（可多次指定挂载多个文件）
  --thumbnail PATH           用户指定的缩略图文件（png/jpg/jpeg/webp/svg），指定后跳过自动生成
  --help                     显示帮助信息
```

示例：

```bash
# 基本用法
lims2 chart upload plot.json -p proj_001 -n "基因表达分析" -t heatmap

# 完整参数
lims2 chart upload plot.json -p proj_001 -n "基因表达分析" \
  -s sample_001 -t heatmap -d "差异表达热图" \
  -c A_vs_B -a Expression_statistics --precision 3

# 上传示例图表（不会被自动清理，chart_type 必填，可附带数据文件）
lims2 chart upload plot.json -p proj_001 -n "示例散点图" \
  -t scatter --example --data-file data.xlsx

# 一次挂载多个数据文件（每个 --data-file 一个，name 自动取文件 stem）
lims2 chart upload plot.json -p proj_001 -n "热图" -t heatmap \
  --data-file matrix.csv --data-file groups.tsv --data-file metadata.json

# 显式指定缩略图（跳过 kaleido 自动生成，适合无法跑 Chrome 的环境）
lims2 chart upload plot.json -p proj_001 -n "热图" \
  -t heatmap --thumbnail thumb.png

# 管道输入
echo '{"data": [...], "layout": {...}}' | lims2 chart upload - -p proj_001 -n "管道图表"
```

#### chart_type 说明

`-t, --chart-type` / `chart_type=` 是图表类型标识。SDK **不做枚举校验**，传入字符串原样发送给后端：

- 普通模式下可选
- `--example` 模式下必填（缺失会在客户端抛 `ValueError`）

下表是和前端展示组件对应的建议命名，**能用 Plotly 原生类型时优先使用**。

**Plotly 原生（推荐）：**

| chart_type | 中文名 |
|---|---|
| `scatter` | 散点图 |
| `bar` | 柱形图 |
| `line` | 折线图 |
| `box` | 箱线图 |
| `violin` | 小提琴图 |
| `heatmap` | 热力图 |
| `pie` | 饼图 |
| `funnel` | 漏斗图 |
| `sankey` | 桑基图 |
| `treemap` | 矩形树图 |
| `sunburst` | 旭日图 |

**业务扩展类型：**

| chart_type | 中文名 | 备注 |
|---|---|---|
| `radar` | 雷达图 | |
| `tree` | 树图 | |
| `chord` | 和弦图 | |
| `venn` | 韦恩图 | |
| `graph` | 关系图 | |
| `special` | 特殊类 | 静态图片，如 KEGG Pathway |
| `combination` | 组合图 | 如 GSEA |

### 文件存储

参数说明（`lims2 storage upload --help`）：

```
Usage: lims2 storage upload [OPTIONS] FILE_PATH

Options:
  -p, --project-id TEXT     项目 ID  [required]
  --base-path TEXT          OSS 中的基础路径
  -a, --analysis-node TEXT  分析节点名称
  -c, --file-category TEXT  文件分类（默认: result）
  -s, --sample-id TEXT      样本 ID
  -k, --key TEXT            自定义 OSS 键名
  -d, --description TEXT    文件描述
  --progress                显示上传进度
  --help                    显示帮助信息
```

示例：

```bash
# 基本上传
lims2 storage upload results.csv -p proj_001

# 指定基础路径 + 进度条
lims2 storage upload results.csv -p proj_001 --base-path analysis --progress

# 完整参数
lims2 storage upload results.csv -p proj_001 --base-path results \
  -a qc -c processed -s sample_001 -d "QC 结果表"

# 上传目录（递归），与 upload 共享 -a/-c/-s/--base-path
lims2 storage upload-dir output/ -p proj_001 --base-path analysis -a preprocessing

# 查询文件（--json 输出原始结构）
lims2 storage info biofile/.../file.txt -p proj_001
lims2 storage info biofile/.../file.txt -p proj_001 --json
lims2 storage exists biofile/.../file.txt -p proj_001
```

## Python SDK 使用

多个图表上传推荐复用客户端实例，共享连接池：

```python
from lims2 import Lims2Client

client = Lims2Client()

for chart_file in ["plot1.json", "plot2.json", "plot3.json"]:
    client.chart.upload(
        data_source=chart_file,
        project_id="proj_001",
        chart_name=f"图表_{chart_file}",
        analysis_node="Expression_statistics",
        precision=3,
    )
```

### 完整参数示例

```python
# 图表上传
client.chart.upload(
    data_source="plot.json",        # 图表数据：字典、文件路径或 Path 对象
    project_id="proj_001",          # 项目 ID（必需）
    chart_name="基因表达分析",        # 图表名称（必需）
    sample_id="sample_001",         # 样本 ID（可选）
    chart_type="heatmap",           # 图表类型（示例模式下必填）
    description="差异表达基因热图",
    contrast="A_vs_B",
    analysis_node="Expression_statistics",
    precision=3,                    # 浮点数精度 0-10（默认 3）
    generate_thumbnail=True,        # 是否自动生成缩略图
    thumbnail_path="thumb.png",     # 显式缩略图，跳过自动生成（png/jpg/jpeg/webp/svg）
    file_name="gene_expression",    # 自定义文件名
    example=True,                   # 上传为示例数据（不会被自动清理）
    data_files=[                    # 关联数据文件列表
        "matrix.csv",                #   纯路径：name 自动取 stem -> "matrix"
        {"path": "groups.tsv",       #   dict 形式可自定义 name / label
         "name": "groups",
         "label": "样本分组"},
    ],
)

# 文件存储
client.storage.upload_file("results.csv", "proj_001")
client.storage.upload_file("results.csv", "proj_001", base_path="analysis")
client.storage.upload_directory("output/", "proj_001")
```

## 支持的数据格式

**图表**：
- **Plotly**: 含 `data` / `layout` 字段的字典（自动生成缩略图）
- **Cytoscape**: 含 `elements` 或 `nodes`+`edges` 的字典（使用预设缩略图）
- **图片/文档**: PNG, JPG, SVG, PDF, HTML

**缩略图策略**（按优先级）：
1. 显式 `--thumbnail` / `thumbnail_path=` → 直接上传指定文件
2. `generate_thumbnail=False` → 不生成
3. 否则按图表类型自动生成（Plotly 用 kaleido 渲染，Cytoscape 用预设图）

> kaleido 1.x 需要系统装新版 Chrome；老系统（如 CentOS 7 glibc 2.17）建议 `pip install "kaleido==0.2.1"` 用自带 Chromium，或直接用 `--thumbnail` 跳过自动生成。

**文件存储**：任意格式，大文件（>10MB）自动断点续传。

## 可选环境变量

```bash
# 网络
export LIMS2_CONNECTION_TIMEOUT=30
export LIMS2_READ_TIMEOUT=300
export LIMS2_MAX_RETRIES=3

# 缩略图
export LIMS2_THUMBNAIL_WIDTH=800
export LIMS2_THUMBNAIL_HEIGHT=600
export LIMS2_THUMBNAIL_FORMAT=webp

# 日志（CLI 默认 INFO）
export LIMS2_LOG_LEVEL=DEBUG
```

## 许可证

MIT License
