Metadata-Version: 2.1
Name: Yucebio-Wdladaptor
Version: 1.0.4
Summary: Yucebio Wdl适配器
Home-page: UNKNOWN
Author: huangqingjun
Author-email: huangqingjun@yucebio.com
License: MIT
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: Yucebio-Config (>=0.1.0)
Requires-Dist: json5
Requires-Dist: click
Requires-Dist: requests
Requires-Dist: pymongo
Requires-Dist: batchcompute (>=2.1)

# Yucebio Wdl适配器

- 根据不同云平台的Cromwell基础设施将通用的workflow内容转换适合对应平台的版本
- 已经支持的云
    - Yucebio 本地SGE集群
    - 阿里云批量计算平台
    - 亚马逊云Batch平台
- 适配器安装成功后会在本地python环境中添加`yc2_wdl`的命令行工具.使用人员可以通过输入该命令检查是否安装成功.
- 适配器目前提供了6个子命令
    - `yc2_wdl version`: 查看版本信息. 目前应当是 1.0.0
    - `yc2_wdl login`: 用于登录, 使用适配器必须先登录
    - `yc2_wdl config`: 用于配置Cromwell 和 API
    - `yc2_wdl adaptor`: 用于投递作业
        - `yc2_wdl adaptor submit` 生产人员投递通用流程
        - `yc2_wdl adaptor restart` 生产人员重投作业, 重投之前,需要先中止运行中的作业
        - `yc2_wdl adaptor abort` 中止作业
        - `yc2_wdl adaptor convert` 生信研发人员投递(或重新投递)开发中的流程作业
        - `yc2_wdl adaptor update-bcs-instance` 生信研发人员更新本地阿里云实例配置信息.避免因阿里云平台实例类型错误导致分析失败
    - `yc2_wdl api`: 提供API相关的辅助命令
        - `yc2_wdl api sync-backends` 将本地Cromwell配置上传到服务器或从服务器下载Cromwell配置到本地
        - `yc2_wdl api list-backends` 列出服务器上保存的Cromwell配置
        - `yc2_wdl api link-job` 该命令用于管理历史作业, 手动将历史作业信息上传到服务器.
        - `yc2_wdl api export-workflow` 导出作业适配后的JSON或WDL内容
    - `yc2_wdl monitor`: 提供查询作业信息相关的辅助命令
        - `yc2_wdl monitor query`: 基于Cromwell原生接口查询指定Cromwell服务器上的所有作业信息
        - `yc2_wdl monitor ls`: 查询个人(JSON中的owner)投递的作业.
    - **所有子命令（和二级子命令）支持最小前缀匹配的简写模式，即根据子命令前缀自动识别要执行的命令**

# 安装

```bash
# 初始化环境，如通过conda初始化python>=3.9的环境
$ conda create -n python3.9 python=3.9

# 安装
$ pip install Yucebio-Wdladaptor

# 使用
$ yc2_wdl --help
```

# 使用

**查看使用方式**
```bash
$ yc2_wdl --help
# Usage: yc2_wdl [OPTIONS] COMMAND [ARGS]...

# Options:
#   --help  Show this message and exit.

# Commands:
#   adaptor  WDL适配器 V2
#   api      通过适配器服务的形式管理Cromwell作业、Backend等
#   config   查看或管理配置
#   login    基于gitlab api v4实现登录认证。登录成功后可以根据需要执行初次配置同步
#   monitor  作业监控
#   version  显示版本信息
```
## 登录(`yc2_wdl login`)
> 为了准确识别当前操作人，从0.1.0版本开始，必须进行登录操作

```bash
$ yc2_wdl login --help
# Usage: yc2_wdl login [OPTIONS]

#   基于gitlab api v4实现登录认证。登录成功后可以根据需要执行初次配置同步

# Options:
#   -g, --gitlab_host TEXT  自建或公共Gitlab API地址
#   -u, --username TEXT     用户名  [required]
#   -o, --owner TEXT        投递分析任务时的属主信息(默认与用户名保持一致)
#   -p, --password TEXT     密码
#   -s, --sync              是否需要自动同步配置到本地  [default: False]
#   --help                  Show this message and exit.
```

## 配置（`yc2_wdl config`）
> 基于Yucebio-Config，配置文件在~/.yucebioconfig/...

**查看帮助**
```bash
$ yc2_wdl config --help
# Usage: yc2_wdl config [OPTIONS] COMMAND [ARGS]...

#   查看或管理配置

# Options:
#   --help  Show this message and exit.

# Commands:
#   add-cromwell     新增或更新更新Cromwell Server平台配置
#   api-service      配置适配器专用的API服务器地址
#   delete-cromwell  查看Cromwell Server平台配置
#   list-cromwell    查看Cromwell Server平台配置
#   sync           执行配置同步：上传或下载配置
```

**新增Cromwell Server配置项**
```bash
$ yc2_wdl config add-cromwell -p <platform> -a <any_name> -g <global_path> -s <simg_path> -h <host> -r runtime1,runtime2
# -p --platform     需要设置的平台
#  -a, --alias TEXT 配置别名，支持同一平台下的多个cromwell服务
# -h --host         待设置平台的cromwell api地址，如 http://host:port
# -g --global_path  公共文件路径，用于替换输入文件中的__GLOBAL__
# -s --simg_path    singularity镜像路径，用于替换输入文件中的__SIMG__
# -r --runtimes     当前平台需要支持的额外自定义runtime属性（未知的runtime将被移除）
```


## WDL处理(`yc2_wdl adaptor`)
**通用WDL转换，并投递到指定Cromwell Server**
```bash
$ yc2_wdl adaptor convert -p <platform_alias> -i <json> [--submit|-s] [--runtimes|-r runtime1,runtime2] <WDL>
# -i --input            JSON文件路径
# -b, --backend_name    平台配置名称
# -s --submit           是否直接投递任务【default:False】
# -r --runtimes         转换过程中每个task都需要添加的自定义runtime属性，多个属性之间使用逗号分隔，每个属性都必须在JSON文件中存在对应的初始值。
# WDL                   workflow文件路径
```

**更新阿里云可用实例类型**
> 转换任务到阿里云平台时，需要将cpu和memory资源的使用情况转换成阿里云支持的cluster属性，为了提高效率，需要提前获取阿里云可用实例类型与资源对应关系

> 第一次执行时必须提供ACCESS_KEY ID 和 SECRECT。第一次执行成功后，会自动保存到配置文件中

```bash
$ yc2_wdl adaptor update-bcs-instance -i <ACCESS_KEY_ID> -s <ACCESS_KEY_SECRECT>
# -i --access_id        阿里云ACCESS_KEY_ID
# -s --access_secrect   阿里云ACCESS_KEY_SECRECT
```

## 任务管理(`yc2_wdl monitor`)
> 为了区分当前执行人员，需要提前配置好个人信息

**使用说明**
```bash
$ yc2_wdl monitor --help
# Usage: yc2_wdl monitor [OPTIONS] COMMAND [ARGS]...

#   作业监控

# Options:
#   --help  Show this message and exit.

# Commands:
#   ls       查看本人提交的任务最新状态
#   query    基于Cromwell API接口查询所有任务基本信息
```



# 附录

## 各个平台可用自定义RUNTIME属性

**通用属性**
- cpu
- memory

**阿里云**
- rescource_type 控制生成竞价型或按需型实例
- systemDisk
- cluster
- mounts, vpc
- continueOnReturnCode, failOnStderr

**SGE**
- owner： 指定sge任务属主
- 'cpu', 'memory', "sge_queue", "sge_project", "mount", 'continueOnReturnCode'
- simg

**亚马逊**
- cpu
- memory
- docker
- disk

## [更新日志](CHANGELOG.md)



