miniwdl

1.13.1 · active · verified Thu Apr 16

miniwdl is a Python library and command-line tool for running and developing Workflow Description Language (WDL) workflows locally. It provides a WDL runtime, a parser, and utilities for WDL authors. The current version is 1.13.1, and it maintains an active release cadence, addressing bugs, updating dependencies, and enhancing WDL specification compliance.

Common errors

```
RuntimeError: There is no current event loop in thread '...'
```
cause This error typically occurs on Python 3.10+ when asynchronous code attempts to access an event loop that hasn't been set up or has been closed. miniwdl versions prior to 1.13.1 had specific issues with `asyncio.get_event_loop()`.

fix Upgrade miniwdl to version 1.13.1 or newer. This version includes a fix for this `asyncio` compatibility problem.
```
WDL.Error.TypeError: Optional[String] cannot be coerced to String
```
cause You are attempting to use an optional WDL variable (e.g., `String?`) in a context that requires a non-optional type (e.g., `String`) without explicitly handling the optionality. This behavior was disallowed from v1.9.0.

fix Explicitly handle optional values. If the value is known to be present, cast it using `as String`. If it might be null, ensure the receiving variable is also optional, or use conditional logic (`if defined(x) then x else 'default'`).
```
miniwdl: error: the following arguments are required: WDL_FILE
```
cause When running miniwdl from the command line, you must specify the path to your main WDL workflow file.

fix Provide the path to your WDL file, e.g., `miniwdl run my_workflow.wdl inputs.json`.
```
WDL.Error.SyntaxError: unknown field "xyz" in struct type MyStruct
```
cause You are providing a struct literal with a field that is not defined in the corresponding WDL struct type, or there's a typo. This became stricter with WDL 1.1 compliance.

fix Ensure all fields in your struct literal exactly match the fields defined in your WDL struct type. Review the WDL 1.1 specification for struct definition and usage.

Warnings

breaking Implicit coercions from optional types (e.g., `String?`) to non-optional types (`String`) were disallowed starting in v1.9.0.
Fix: Explicitly cast optional values to their non-optional counterparts using `as String` or ensure the target variable is also optional. For example, `my_optional_string_var as String`.
breaking The default `-l` (login shell) flag for task command bash interpreters was removed in v1.9.0. This can change the environment available to your tasks.
Fix: If your tasks rely on login shell features (e.g., specific `~/.bashrc` settings), you can restore this behavior by configuring `[task_runtime] bash_cmd_shell_opts = ['-l']` in your miniwdl configuration file.
gotcha With Python 3.10+ and `asyncio`, you might encounter errors related to the event loop. v1.13.1 fixed an issue with `asyncio.get_event_loop()`.
Fix: Upgrade to miniwdl v1.13.1 or newer to resolve `asyncio.get_event_loop()` related errors on modern Python versions.
gotcha v1.13.0 introduced changes for WDL 1.1 spec compliance, including dedenting task commands before interpolation and stricter type checking for struct literals. This could subtly alter behavior for existing WDLs.
Fix: Review WDLs for reliance on specific command indentation or implicit field handling in structs. Update WDLs to conform strictly to WDL 1.1 specification and declare all struct fields explicitly.
gotcha Internal migration from `pkg_resources` to `importlib_metadata` in v1.13.1. While this primarily affects miniwdl's internals, outdated `setuptools` in the user environment could cause issues.
Fix: Ensure your `setuptools` package is up-to-date (`pip install --upgrade setuptools`) if you encounter any import or packaging-related errors.

Install

pip install miniwdl Install latest version

Imports

run
wrong:
```
import miniwdl.run
```
correct:
```
from miniwdl import runner
```
The primary `run` function for executing WDLs is found within the `runner` submodule.
main
```
from miniwdl import main
```
The `main` submodule provides access to CLI functionalities programmatically.
wdl
```
from miniwdl import wdl
```
The `wdl` submodule contains parsing and AST (Abstract Syntax Tree) functionalities for WDL documents.

Quickstart

This quickstart demonstrates how to programmatically run a simple WDL workflow using `miniwdl.runner.run`. It creates a temporary WDL file, defines inputs, executes the workflow, and prints the output.

import miniwdl.runner
import os

# Create a simple WDL file for demonstration
wdl_content = """
version 1.0
workflow hello {
  input { String name }
  call hello_task { input: name = name }
}
task hello_task {
  input { String name }
  command { echo "Hello, ${name}!" }
  output { String message = read_string(stdout()) }
}
"""
with open("hello.wdl", "w") as f:
    f.write(wdl_content)

# Define inputs as a dictionary
inputs = {"hello.name": "WDL User"}

# Run the WDL workflow
try:
    run_result = miniwdl.runner.run(
        wdl="hello.wdl",
        inputs=inputs,
        dir=os.getcwd() # Specify directory where WDL is found
    )
    # Access outputs
    print(f"Workflow output: {run_result.outputs['hello.hello_task.message']}")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy WDL file
    if os.path.exists("hello.wdl"):
        os.remove("hello.wdl")

view raw JSON →