Metadata-Version: 2.4
Name: gxy-wes
Version: 0.1.0
Summary: A tiny standalone client and CLI for Galaxy's GA4GH WES API
Author-email: Galaxy Project and Community <jmchilton@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jmchilton/gxy-wes
Keywords: galaxy,ga4gh,wes,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# gxy-wes

A tiny, dependency-light client and command line tool for [Galaxy](https://galaxyproject.org)'s
[GA4GH Workflow Execution Service (WES)](https://ga4gh.github.io/workflow-execution-service-schemas/)
API. It depends only on requests, so it runs cleanly under `uvx` and is meant
for documentation examples and quick interactive exploration of a Galaxy WES
endpoint.

It walks the same flow the Galaxy developer docs describe: discover the service,
stage an input dataset, submit a workflow, poll the run, and read outputs and
per-task logs.

## Scope

This project exists to **demonstrate the WES API** — it is not meant for
production or user-facing applications.

- For user-facing applications, use [Planemo](https://planemo.readthedocs.io/).
- For production applications, build on the
  [BioBlend](https://bioblend.readthedocs.io/) abstractions.

## Install

Run it without installing using [uv](https://docs.astral.sh/uv/):

```console
$ uvx gxy-wes service-info --galaxy-url http://localhost:8080
```

Or install it:

```console
$ pip install gxy-wes
```

## Authentication

Every endpoint except `service-info` needs a Galaxy API key, sent as the
`x-api-key` header. Pass `--api-key` or set `GXY_WES_API_KEY`; set the server
with `--galaxy-url` or `GXY_WES_URL`. Get a key with:

```console
$ curl -s -u you@example.com:password \
    http://localhost:8080/api/authenticate/baseauth
```

## Usage

Each WES endpoint is a subcommand:

```console
$ gxy-wes service-info
$ gxy-wes stage --content $'hello\nworld\n'          # -> {history_id, hda_id}
$ gxy-wes submit --workflow simple.gxwf.yml \
    --params '{"input1": {"src": "hda", "id": "<hda_id>"}}' \
    --engine-parameters '{"history_id": "<history_id>"}'
$ gxy-wes status <run_id>
$ gxy-wes get <run_id>
$ gxy-wes tasks <run_id>
$ gxy-wes task <run_id> 1
$ gxy-wes list
$ gxy-wes cancel <run_id>
$ gxy-wes job-output <job_id> --which stderr
```

The `demo` subcommand runs the whole example end to end against a live Galaxy
(stage an input, submit the bundled Format2 workflow, poll, print outputs and
tasks):

```console
$ export GXY_WES_API_KEY=...
$ uvx gxy-wes demo --galaxy-url http://localhost:8080
```

## As a library

```python
from gxy_wes import WesClient

client = WesClient("http://localhost:8080", api_key="...")
info = client.service_info()
run = client.submit_run(
    workflow_type="gx_workflow_format2",
    workflow_path="simple.gxwf.yml",
    params={"input1": {"src": "hda", "id": hda_id}},
    engine_parameters={"history_id": history_id},
)
status = client.get_run_status(run["run_id"])
```

## Notes

- `workflow_type` is one of Galaxy's formats: `gx_workflow_format2` (Format2 YAML)
  or `gx_workflow_ga` (native `.ga` JSON). It is detected from the workflow
  content when you pass `--workflow`.
- WES has no data-staging endpoint; dataset inputs must already exist in Galaxy
  and are referenced as `{"src": "hda", "id": ...}`. The `stage` subcommand uses
  Galaxy's native API to create those.
- Run success is determined by the WES run `state` (`COMPLETE`), not by per-task
  exit codes — a failed job can be a normal part of a valid workflow.

## License

MIT. See [LICENSE](https://github.com/jmchilton/gxy-wes/blob/main/LICENSE).
