{"id":7121,"library":"cwl-utils","title":"cwl-utils: Common Workflow Language Utilities","description":"cwl-utils is a Python library providing utilities and autogenerated classes for loading, manipulating, and parsing Common Workflow Language (CWL) v1.0, v1.1, and v1.2 documents. It is the reference implementation of CWL, offering comprehensive validation and various tools for working with CWL files. The library is actively maintained with frequent releases, typically several times a year.","status":"active","version":"0.41","language":"en","source_language":"en","source_url":"https://github.com/common-workflow-language/cwl-utils","tags":["CWL","workflow","parser","schema-validation","bioinformatics","scientific-workflow"],"install":[{"cmd":"pip install cwl-utils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python <3.15, >=3.10 as of version 0.41.","package":"python","optional":false},{"reason":"Core dependency for schema parsing and code generation. Version requirements can change between cwl-utils releases.","package":"schema-salad","optional":false},{"reason":"Used for YAML parsing of CWL documents.","package":"ruamel.yaml","optional":false}],"imports":[{"note":"Primary function to load a CWL document from a URI or file path.","symbol":"load_document_by_uri","correct":"from cwl_utils.parser import load_document_by_uri"},{"note":"Function to export a loaded CWL object into a built-in typed object.","symbol":"save","correct":"from cwl_utils.parser import save"}],"quickstart":{"code":"from pathlib import Path\nfrom cwl_utils.parser import load_document_by_uri\n\n# Create a dummy CWL file for the example\ncwl_content = \"\"\"\ncwlVersion: v1.2\nclass: CommandLineTool\nbaseCommand: echo\ninputs:\n  message:\n    type: string\n    default: \"Hello World from cwl-utils!\"\n    inputBinding:\n      position: 1\noutputs:\n  output:\n    type: stdout\n\"\"\"\n\ncwl_file_path = Path(\"hello_world.cwl\")\ncwl_file_path.write_text(cwl_content)\n\ntry:\n    # Load the CWL object from the file URI\n    # Note: For local files, str(Path_object) is often needed for older APIs\n    cwl_obj = load_document_by_uri(str(cwl_file_path))\n\n    print(f\"Successfully loaded CWL Tool ID: {cwl_obj.id}\")\n    print(f\"CWL Version: {cwl_obj.cwlVersion}\")\n    if hasattr(cwl_obj, 'inputs') and cwl_obj.inputs:\n        print(f\"First input message default: {cwl_obj.inputs[0].default}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if cwl_file_path.exists():\n        cwl_file_path.unlink()","lang":"python","description":"This quickstart demonstrates how to programmatically load a CWL CommandLineTool document using `cwl-utils` from a local file. It creates a simple 'hello_world.cwl' file, loads it using `load_document_by_uri`, and then prints some attributes of the parsed CWL object. The example also includes cleanup for the created file."},"warnings":[{"fix":"Upgrade Python environment to 3.10 or newer. Check `requires_python` in PyPI for exact current compatibility.","message":"Dropped support for Python 3.9. Users on Python 3.9 must upgrade to a newer Python version (>=3.10).","severity":"breaking","affected_versions":">=0.41"},{"fix":"Upgrade Python environment to 3.9 or newer. Check `requires_python` in PyPI for exact current compatibility.","message":"Dropped support for Python 3.8. Users on Python 3.8 must upgrade to a newer Python version (>=3.9).","severity":"breaking","affected_versions":">=0.36"},{"fix":"Ensure `ruamel.yaml` is updated to a compatible version (0.18.x or newer). Re-evaluate any custom YAML parsing logic that might be affected.","message":"Support for `ruamel.yaml` 0.18+ was introduced, which might cause compatibility issues if your environment uses an older, incompatible version or if specific behaviors of older `ruamel.yaml` were relied upon.","severity":"gotcha","affected_versions":">=0.38"},{"fix":"Review CWL documents for strict compliance with the CWL specification if encountering unexpected parsing behavior. Keep `schema-salad` updated alongside `cwl-utils`.","message":"Internal parser generation and dependency on `schema-salad` has seen updates across versions (e.g., requiring map & union enabled version). This could subtly change parsing behavior for complex CWL documents.","severity":"gotcha","affected_versions":">=0.32"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `cwl-utils` is installed: `pip install cwl-utils`. If already installed, try upgrading: `pip install --upgrade cwl-utils`. Verify correct import path from documentation.","cause":"The `cwl_utils.parser` module or the specific function `load_document_by_uri` might not exist in an older installed version of `cwl-utils`, or the library is not installed correctly.","error":"ImportError: cannot import name 'load_document_by_uri' from 'cwl_utils.parser'"},{"fix":"Validate your CWL document using `cwltool --validate your_workflow.cwl`. Consult the CWL specification for the version you are using. Ensure your `cwl-utils` is up-to-date for the CWL version.","cause":"The CWL file being loaded does not conform to the Common Workflow Language specification, or it uses a CWL version not fully supported by the installed `cwl-utils` version.","error":"schema_salad.exceptions.ValidationException: ... is not a valid CWL document."},{"fix":"Carefully inspect the CWL YAML file for syntax errors, especially around the indicated line and column. Use a YAML linter or editor with YAML validation features.","cause":"The CWL document (which is typically YAML) contains malformed syntax, such as incorrect indentation, invalid characters, or missing delimiters.","error":"yaml.scanner.ScannerError: while scanning for the next token Found character that cannot start any token"},{"fix":"Check if the file path passed to `load_document_by_uri` is correct and accessible. Ensure the CWL file is not empty and contains valid CWL content. Add checks for `None` return values after loading.","cause":"`load_document_by_uri` or a similar parsing function returned `None`, likely because the specified file path was incorrect, the file was empty, or an internal parsing error occurred without raising a more specific exception.","error":"AttributeError: 'NoneType' object has no attribute 'id'"}]}