Galaxy Workflow Format 2 Descriptions

0.24.0 · active · verified Thu Apr 16

gxformat2 defines a high-level, human-readable, and human-writable workflow description format for Galaxy, known as Format 2. This package facilitates the creation, parsing, and conversion of Galaxy workflows, addressing the limitations of the older `.ga` format and moving towards compatibility with standards like the Common Workflow Language (CWL). It is actively developed and supports Galaxy versions 19.09 and newer, though the format is still somewhat experimental and may undergo minor backward-incompatible changes. The current version is 0.24.0, with a somewhat regular release cadence.

Common errors

```
YAMLError: while parsing a block mapping
```
cause Incorrect YAML syntax in the workflow definition file.

fix Check your `.gxwf.yml` file for proper indentation, colon usage, and valid YAML structure. Tools like `gxwf-lint` or VSCode extensions for YAML can help identify syntax errors.
```
ValidationError: 'tool_id' is a required field
```
cause The workflow definition is missing a required field, or a field has an incorrect type/value, failing schema validation.

fix Consult the Format 2 schema documentation (available on the `gxformat2` GitHub repository) to ensure all required fields are present and correctly formatted for workflow inputs, steps, and outputs.
```
ModuleNotFoundError: No module named 'gxformat2'
```
cause The `gxformat2` library is not installed in the current Python environment.

fix Install the library using `pip install gxformat2`.
```
RuntimeError: Requires Python >= 3.9
```
cause Attempting to run `gxformat2` with an unsupported Python version (older than 3.9).

fix Upgrade your Python interpreter to version 3.9 or newer. You might need to create a new virtual environment with a compatible Python version.

Warnings

gotcha The Format 2 workflow description is still considered somewhat experimental. It may undergo small, potentially backward-incompatible changes, particularly until it is exported by Galaxy as the default format. Users should regularly review changelogs for updates.
Fix: Stay updated with releases, consult the official documentation, and test workflows after upgrading the library or Galaxy.
breaking Support for Python 3.5 was dropped, and Python 3.9 was added as the minimum required version in `gxformat2` v0.16.0.
Fix: Ensure your environment uses Python 3.9 or newer. Upgrade your Python interpreter if necessary.
gotcha When defining workflows, use the `label` field instead of `name` for workflow validation against the schema. While Galaxy may still process `name` for legacy reasons, `label` is the correct attribute for adherence to the Format 2 schema.
Fix: Always use `label: Your Workflow Name` for workflow definitions in Format 2 YAML files to ensure proper validation.
deprecated The `ImportOptions` class is being replaced by `ConversionOptions` for conversion and expansion layers, as part of an architectural refactor. Using `ImportOptions` might become deprecated or removed in future versions.
Fix: Monitor future `gxformat2` releases for the official switch. When `ConversionOptions` is introduced, migrate any usage of `ImportOptions` to the new class.

Install

pip install gxformat2 Install latest stable version

Imports

parse_yaml_workflow
```
from gxformat2.yaml import parse_yaml_workflow
```
Used for loading Format 2 workflows from YAML files.
dump_format2_workflow_to_native
```
from gxformat2.converter import dump_format2_workflow_to_native
```
Used for converting a Format 2 workflow model to the native Galaxy .ga format.
python_to_workflow
```
from gxformat2.converter import python_to_workflow
```
Converts a Python dictionary representation of a Format 2 workflow into a typed workflow model.

Quickstart

This quickstart demonstrates how to parse a Format 2 workflow from a YAML string into a Python object using `parse_yaml_workflow`, and then convert it to the native Galaxy `.ga` format using `dump_format2_workflow_to_native`. It also shows how to access basic properties of the parsed workflow model.

from gxformat2.yaml import parse_yaml_workflow
from gxformat2.converter import dump_format2_workflow_to_native
import yaml

# Example Format 2 Workflow content (minimal example)
workflow_content = '''
class: GalaxyWorkflow
inputs:
  - id: input_file
    type: File
steps:
  - id: cat_tool
    tool_id: cat1
    in:
      input1: input_file
outputs:
  - id: output_file
    outputSource: cat_tool/out_file
'''

# 1. Parse a Format 2 YAML workflow string
# In a real scenario, you'd load this from a .gxwf.yml file
workflow_path = '/tmp/my_workflow.gxwf.yml'
with open(workflow_path, 'w') as f:
    f.write(workflow_content)

try:
    workflow_model = parse_yaml_workflow(workflow_path)
    print(f"Successfully parsed workflow: {workflow_model.label or workflow_model.id}")

    # 2. Convert the Format 2 workflow model to native Galaxy .ga format
    native_workflow_dict = dump_format2_workflow_to_native(workflow_model)
    print("\nConverted to native Galaxy workflow (excerpt):")
    print(yaml.dump(native_workflow_dict, indent=2, default_flow_style=False)[:200] + '...') # Print first 200 chars

    # You can access properties of the parsed model
    print(f"\nNumber of steps: {len(workflow_model.steps)}")
    print(f"First step tool_id: {workflow_model.steps[0].tool_id}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →