Galaxy Tool Utilities

Common errors

• ImportError: No module named 'galaxy.tool_util'

  cause The `galaxy-tool-util` package is not installed or the Python environment is not correctly configured.
  fix Ensure you have activated the correct Python environment and run `pip install galaxy-tool-util`.

• xml.etree.ElementTree.ParseError: not well-formed (invalid token): line X, column Y

  cause The provided XML file or string is malformed or contains syntax errors, preventing successful parsing.
  fix Review your tool XML file for syntax errors, missing closing tags, invalid characters, or incorrect XML structure. Use an XML validator to pinpoint the exact issue.

• AttributeError: 'ToolSource' object has no attribute 'some_nonexistent_method'

  cause You are attempting to call a method or access an attribute that does not exist on the `ToolSource` object, or you are expecting it to expose a direct mapping to XML elements that it doesn't.
  fix Consult the source code or official documentation for the `ToolSource` class and its subclasses to understand the available API. Use methods like `parse_id()`, `parse_name()`, `parse_version()` or specific parsing functions for inputs/outputs.

Warnings

• breaking As an internal utility library, `galaxy-tool-util`'s APIs, especially for advanced features or internal representations, can change without explicit 'breaking change' announcements specific to this package. Such changes are often part of larger refactorings within the main Galaxy project.
  Fix: Always refer to the latest Galaxy documentation and source code when building integrations. Pin your `galaxy-tool-util` version to match your Galaxy server's version.
• gotcha Parsing untrusted XML via functions like `get_tool_source` can expose applications to XML External Entity (XXE) attacks or other parser vulnerabilities. While underlying libraries like `lxml` often provide some default protections, vigilance is required.
  Fix: Ensure that any tool XML files processed originate from trusted sources. If parsing untrusted XML, implement additional input validation and configure XML parsers (if directly using `lxml` or `ElementTree`) to explicitly disable DTD processing and external entity resolution.
• gotcha The `ToolSource` object returned by `get_tool_source` represents the parsed tool definition and its methods provide access to various parts of the tool. However, its methods might not directly expose every single XML attribute or element, and some advanced features (e.g., job parameters) might require deeper introspection or specific utility functions.
  Fix: Consult the Galaxy source code for `ToolSource` and related classes to understand its full capabilities and how to access specific tool definition components. Avoid directly manipulating the underlying XML tree unless absolutely necessary and you understand the implications.

Install

• pip install galaxy-tool-util Install latest version

Imports

• get_tool_source

  from galaxy.tool_util.parser import get_tool_source

• lint_tool_xml

  from galaxy.tool_util.linters import lint_tool_xml

• tool_dependencies

  from galaxy.tool_util.deps import dependencies as tool_dependencies

Quickstart

This quickstart demonstrates how to parse a Galaxy tool XML definition using `get_tool_source`. It creates a simple XML file, parses it, and prints basic metadata. Note that full linting (`lint_tool_xml`) often requires a more complete Galaxy environment or specific mock objects for its various checks.

import os
from galaxy.tool_util.parser import get_tool_source
from galaxy.tool_util.linters import lint_tool_xml

# Create a dummy tool XML file for demonstration
tool_xml_content = """
<tool id="test_tool" name="Test Tool" version="1.0.0">
    <description>A simple test tool</description>
    <command>echo "Hello World"</command>
    <inputs>
        <param name="input_text" type="text" label="Input text"/>
    </inputs>
    <outputs>
        <data name="output_file" format="txt" label="Output Text File"/>
    </outputs>
    <tests>
        <test>
            <param name="input_text" value="test"/>
            <output name="output_file" ftype="txt" value="Hello World" compare="re"/>
        </test>
    </tests>
</tool>
"""

tool_path = "dummy_tool.xml"
with open(tool_path, "w") as f:
    f.write(tool_xml_content)

# 1. Parse the tool XML
try:
    tool_source = get_tool_source(tool_path)
    print(f"Successfully parsed tool: {tool_source.parse_id()} (version {tool_source.parse_version()})")

    # 2. Linter (basic validation)
    # The lint_tool_xml function typically requires a tool_shed_repository mock for full functionality
    # For a simple local file, we can run it with minimal context.
    # In a real Galaxy environment, this would be part of a larger object.
    print("Running linter...")
    lint_problems = []
    # The linter expects an XML root element, not a path directly.
    # For this quickstart, we'll demonstrate using a basic parse.
    from xml.etree import ElementTree
    root = ElementTree.parse(tool_path).getroot()

    # lint_tool_xml needs a ToolSource object, not just the root.
    # For a basic lint, you often need the full Galaxy context or specific mocks.
    # This example focuses on parsing.
    print("Basic parsing complete. Full linting requires more context.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(tool_path):
        os.remove(tool_path)