cwl2puml

cwl2puml converts Common Workflow Language workflows into PlantUML diagrams.

It provides a Python API and a transpiler-mate plugin that write PlantUML source and optionally render PNG or SVG images through a PlantUML server.

Supported Diagrams

activity, component, class, sequence, state, ogc_processes_inputs, and ogc_processes_outputs.

Requirements

• Python >=3.10

Local quality checks

Install Hatch and Taskfiles and then install the Git hook:

task quality:pre-commit:install

Every commit runs Ruff (including the configured McCabe complexity limit), Ruff formatting, mypy checks, Bandit security checks, and the pytest suite. Run the complete hook explicitly with:

task quality:pre-commit:run

Installation

For command-line use, install the runtime and plugin together:

pip install transpiler-mate-runtime "cwl2puml>=0.48.0"

For the Python library alone, use pip install cwl2puml. To install the current checkout, use pip install ..

CLI Usage

Note

Since release 0.48.0, cwl2puml is a transpiler-mate plugin. The standalone command was removed; use transpiler-mate cwl2puml. The Python library remains available.

transpiler-mate cwl2puml --help
transpiler-mate cwl2puml --output ./out 'workflow.cwl#main'

Omit #main to render all workflows. Select diagram types by repeating --diagrams, and optionally request images:

transpiler-mate cwl2puml \
  --diagrams component \
  --diagrams sequence \
  --output ./out \
  --convert-image \
  --image-format svg \
  'workflow.cwl#main'

Output

The plugin writes <output>/<workflow.id>/<diagram>.puml, plus .png or .svg files when image conversion is enabled. The default output directory is ./docs; images are disabled by default. All seven diagram types are selected unless --diagrams is supplied.

Start with the first-diagram tutorial, or see the command-line guide and Python guide for specific tasks. Options and API signatures are in the reference.

Development

Install Hatch with pip install hatch, then run the test matrix:

hatch run test:test

Run coverage:

hatch run test:test-cov

Format the code:

hatch run dev:lint

Run Ruff fixes:

hatch run dev:check

Documentation

Project documentation: https://Terradue.github.io/cwl2puml/

To preview the documentation locally, use an isolated environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install mkdocs mkdocs-mermaid2-plugin mkdocs-jupyter "mkdocstrings[python]" pymdown-extensions
mkdocs serve

Run mkdocs build --strict to validate the documentation. Notebook pages use their saved outputs; regenerate those outputs in Jupyter when updating examples.

Contributing

Open an issue at https://github.com/Terradue/cwl2puml/issues if you find a bug or want to propose a change.

License