click2cwl

Name	click2cwl JSON
Version	0.0.4 JSON
	download
home_page	None
Summary	Generates CWL documents and associated parameters from a Click CLI definition
upload_time	2024-08-27 12:25:26
maintainer	None
docs_url	None
author	None
requires_python	None
license	Apache License, Version 2.0
keywords	click2cwl cwl
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Click2CWL - from a Click context to a CWL document

## Rational and context

EO application developers use Click to create command line tools to process EO data.

> [Click](https://click.palletsprojects.com/) is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It’s the “Command Line Interface Creation Kit”. It’s highly configurable but comes with sensible defaults out of the box.
> It aims to make the process of writing command line tools quick and fun while also preventing any frustration caused by the inability to implement an intended CLI API.

To deploy these applications on an Exploitation Plaform on the Cloud, the EO application developers generate a CWL document that becomes an Application Package.

The repo contains a helper Python module that exploits the information contained in a **Click** [context object](https://click.palletsprojects.com/en/7.x/api/?highlight=context#click.Context) to generate the CWL document and eventually the parameters.

This helper Python module can thus be used to add "CWL dump" behaviour to a Python CLI that uses Click by adding an import and call to the `dump(ctx)` function provided in the helper Python module. 

## Installation

Install this Python module in your conda environment using `conda` or `mamba` (see this [article](https://wolfv.medium.com/mamba-development-news-29e32aaa8d6c) to learn about mamba):

```console
conda install -c terradue click2cwl
```

**Note:** Add `click2cwl` dependency and `terradue` channel in your environment.yml file, e.g.:

```yaml
name: my_env
channels:
  - terradue
  - conda-forge
dependencies:
  - python
  - click2cwl
```

## Usage

First import the click2cwl `dump` function with:

```python
from click2cwl import dump
```

Then, in the Python application entry point function, update and enrich the Click function decorator with the information for generating the CWL document.

The information defined at the Click function decorator is explained below:

### @click.command

The `@click.command` decorator must:

- set the `allow_extra_args` flag to `True`. This allows using the command line interface to pass the runtime information to generate the CWL.
- set the `short_help` to define the CWL Workflow class **label**
- set the `help` to define the CWL Workflow class **doc**

```python
@click.command(
    short_help="This is Workflow class label",
    help="This is Workflow class doc",
    context_settings=dict(
        ignore_unknown_options=True,
        allow_extra_args=True,
    ),
)
```

### @click.option

The `@click.option` decorator must:

- define the option type that can be `click.Path` for a `Directory`, a `click.File` for a `File` or the default, a `String` to map as `string`
- set the `help` to define the CWL Workflow class **doc** and **label**
- set the `required` flag to `False` if the parameter is optional

```python
@click.option(
    "--input_path",
    "-i",
    "input_path",
    type=click.Path(),
    help="this input path",
    multiple=False,
    required=True,
)
```

Finally, invoke the `dump` function in your Click decorated function with:

```python
@click.command ...
@click.option ...
@click.pass_context
def main(ctx, **kwargs):

    dump(ctx)

    print("business as usual")
    print(kwargs)

if __name__ == '__main__':
    main()
```

**Note:** See the examples folder to discover typical use cases.

Install your application with:

```console
python setup.py install
```

When the app help is invoked, it will only show the arguments defined by the click.decorators:  

```console
myapp --help
```

but it now supports additional args to drive the generation of the CWL document and associated parameters:

The additional args are:

- `--dump` `cwl`|`params`|`clt`. Example `--dump cwl --dump params` will dump the CWL document and the CWL parameters template in YAML. `clt` will dump the CWl `CommandLineTool` class only (no Workflow)
- `--requirement` with `requirement=value` where requirement here is one of `"coresMin"`, `"coresMax"`, `"ramMin"`, `"ramMax"`. Example: 
 `--requirement ramMax=1 --requirement ramMin=2`
 - `--docker <docker image>` if set, the `DockerRequirement` hint is set to pull the `<docker image>`
 - `--env` sets environment variables in the CWL with `env_var=env_var_value`. Example `--env A=1 --env B=2` where A and B are the environment variables to set in the CWL `EnvVarRequirement` requirement
 - `--wall-time <wall-time in seconds>` if set, the `ToolTimeLimit` cWL requirement is set and the CWL document version is set to v1.1 (instead of default 1.0)
 - `--cwl-version`, if set, the `cwlVersion` uses that value

## Try me on Binder

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Terradue/click2cwl/develop)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "click2cwl",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": "click2cwl, CWL",
    "author": null,
    "author_email": "Fabrice Brito <fabrice.brito@terradue.com>, Parham Membari <parham.membari@terradue.com>",
    "download_url": "https://files.pythonhosted.org/packages/4e/fd/1f485aae55a65f7a632361f0d4eac59eb53d1442351f5bad16a515550bca/click2cwl-0.0.4.tar.gz",
    "platform": null,
    "description": "# Click2CWL - from a Click context to a CWL document\n\n## Rational and context\n\nEO application developers use Click to create command line tools to process EO data.\n\n> [Click](https://click.palletsprojects.com/) is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It\u2019s the \u201cCommand Line Interface Creation Kit\u201d. It\u2019s highly configurable but comes with sensible defaults out of the box.\n> It aims to make the process of writing command line tools quick and fun while also preventing any frustration caused by the inability to implement an intended CLI API.\n\nTo deploy these applications on an Exploitation Plaform on the Cloud, the EO application developers generate a CWL document that becomes an Application Package.\n\nThe repo contains a helper Python module that exploits the information contained in a **Click** [context object](https://click.palletsprojects.com/en/7.x/api/?highlight=context#click.Context) to generate the CWL document and eventually the parameters.\n\nThis helper Python module can thus be used to add \"CWL dump\" behaviour to a Python CLI that uses Click by adding an import and call to the `dump(ctx)` function provided in the helper Python module. \n\n## Installation\n\nInstall this Python module in your conda environment using `conda` or `mamba` (see this [article](https://wolfv.medium.com/mamba-development-news-29e32aaa8d6c) to learn about mamba):\n\n```console\nconda install -c terradue click2cwl\n```\n\n**Note:** Add `click2cwl` dependency and `terradue` channel in your environment.yml file, e.g.:\n\n```yaml\nname: my_env\nchannels:\n  - terradue\n  - conda-forge\ndependencies:\n  - python\n  - click2cwl\n```\n\n## Usage\n\nFirst import the click2cwl `dump` function with:\n\n```python\nfrom click2cwl import dump\n```\n\nThen, in the Python application entry point function, update and enrich the Click function decorator with the information for generating the CWL document.\n\nThe information defined at the Click function decorator is explained below:\n\n### @click.command\n\nThe `@click.command` decorator must:\n\n- set the `allow_extra_args` flag to `True`. This allows using the command line interface to pass the runtime information to generate the CWL.\n- set the `short_help` to define the CWL Workflow class **label**\n- set the `help` to define the CWL Workflow class **doc**\n\n```python\n@click.command(\n    short_help=\"This is Workflow class label\",\n    help=\"This is Workflow class doc\",\n    context_settings=dict(\n        ignore_unknown_options=True,\n        allow_extra_args=True,\n    ),\n)\n```\n\n### @click.option\n\nThe `@click.option` decorator must:\n\n- define the option type that can be `click.Path` for a `Directory`, a `click.File` for a `File` or the default, a `String` to map as `string`\n- set the `help` to define the CWL Workflow class **doc** and **label**\n- set the `required` flag to `False` if the parameter is optional\n\n```python\n@click.option(\n    \"--input_path\",\n    \"-i\",\n    \"input_path\",\n    type=click.Path(),\n    help=\"this input path\",\n    multiple=False,\n    required=True,\n)\n```\n\nFinally, invoke the `dump` function in your Click decorated function with:\n\n```python\n@click.command ...\n@click.option ...\n@click.pass_context\ndef main(ctx, **kwargs):\n\n    dump(ctx)\n\n    print(\"business as usual\")\n    print(kwargs)\n\nif __name__ == '__main__':\n    main()\n```\n\n**Note:** See the examples folder to discover typical use cases.\n\nInstall your application with:\n\n```console\npython setup.py install\n```\n\nWhen the app help is invoked, it will only show the arguments defined by the click.decorators:  \n\n```console\nmyapp --help\n```\n\nbut it now supports additional args to drive the generation of the CWL document and associated parameters:\n\nThe additional args are:\n\n- `--dump` `cwl`|`params`|`clt`. Example `--dump cwl --dump params` will dump the CWL document and the CWL parameters template in YAML. `clt` will dump the CWl `CommandLineTool` class only (no Workflow)\n- `--requirement` with `requirement=value` where requirement here is one of `\"coresMin\"`, `\"coresMax\"`, `\"ramMin\"`, `\"ramMax\"`. Example: \n `--requirement ramMax=1 --requirement ramMin=2`\n - `--docker <docker image>` if set, the `DockerRequirement` hint is set to pull the `<docker image>`\n - `--env` sets environment variables in the CWL with `env_var=env_var_value`. Example `--env A=1 --env B=2` where A and B are the environment variables to set in the CWL `EnvVarRequirement` requirement\n - `--wall-time <wall-time in seconds>` if set, the `ToolTimeLimit` cWL requirement is set and the CWL document version is set to v1.1 (instead of default 1.0)\n - `--cwl-version`, if set, the `cwlVersion` uses that value\n\n## Try me on Binder\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Terradue/click2cwl/develop)\n",
    "bugtrack_url": null,
    "license": "Apache License,  Version 2.0",
    "summary": "Generates CWL documents and associated parameters from a Click CLI definition",
    "version": "0.0.4",
    "project_urls": {
        "Homepage": "https://github.com/Terradue/click2cwl"
    },
    "split_keywords": [
        "click2cwl",
        " cwl"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "dd719c549174a072438c5e9cd62c2123f9796ba57222aac33175d53f3afc6088",
                "md5": "6eb9ff87a88ea2bf65dc3e2bf4977303",
                "sha256": "7daef980f79590fd522e0dc3cabc90b8b9a44d6a4db0b6e783a9976ec9141603"
            },
            "downloads": -1,
            "filename": "click2cwl-0.0.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "6eb9ff87a88ea2bf65dc3e2bf4977303",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 12043,
            "upload_time": "2024-08-27T12:25:24",
            "upload_time_iso_8601": "2024-08-27T12:25:24.191491Z",
            "url": "https://files.pythonhosted.org/packages/dd/71/9c549174a072438c5e9cd62c2123f9796ba57222aac33175d53f3afc6088/click2cwl-0.0.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4efd1f485aae55a65f7a632361f0d4eac59eb53d1442351f5bad16a515550bca",
                "md5": "2e9a4b2c8392097acc7ba1334da461b0",
                "sha256": "0f14818283fd624234b4ea28c004cedd89e7b1d49eee9e2aacc4cd1e676d3532"
            },
            "downloads": -1,
            "filename": "click2cwl-0.0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "2e9a4b2c8392097acc7ba1334da461b0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 16077,
            "upload_time": "2024-08-27T12:25:26",
            "upload_time_iso_8601": "2024-08-27T12:25:26.162015Z",
            "url": "https://files.pythonhosted.org/packages/4e/fd/1f485aae55a65f7a632361f0d4eac59eb53d1442351f5bad16a515550bca/click2cwl-0.0.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-08-27 12:25:26",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Terradue",
    "github_project": "click2cwl",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "click2cwl"
}