API documentation for interacting with the Galaxy Toolshed

ToolShedInstance

class bioblend.toolshed.ToolShedInstance(url: str, key: Optional[str] = None, email: Optional[str] = None, password: Optional[str] = None, verify: bool = True)[source]

A base representation of a connection to a ToolShed instance, identified by the ToolShed URL and user credentials.

After you have created a ToolShedInstance object, access various modules via the class fields. For example, to work with repositories and get a list of all public repositories, the following should be done:

from bioblend import toolshed

ts = toolshed.ToolShedInstance(url='https://testtoolshed.g2.bx.psu.edu')

rl = ts.repositories.get_repositories()

tools = ts.tools.search_tools('fastq')
Parameters

  • url (str) – A FQDN or IP for a given instance of ToolShed. For example: https://testtoolshed.g2.bx.psu.edu . If a ToolShed instance is served under a prefix (e.g. http://127.0.0.1:8080/toolshed/), supply the entire URL including the prefix (note that the prefix must end with a slash).

  • key (str) – If required, user’s API key for the given instance of ToolShed, obtained from the user preferences.

  • email (str) – ToolShed e-mail address corresponding to the user. Ignored if key is supplied directly.

  • password (str) – Password of ToolShed account corresponding to the above e-mail address. Ignored if key is supplied directly.

  • verify (bool) – Whether to verify the server’s TLS certificate

__init__(url: str, key: Optional[str] = None, email: Optional[str] = None, password: Optional[str] = None, verify: bool = True) → None[source]

A base representation of a connection to a ToolShed instance, identified by the ToolShed URL and user credentials.

After you have created a ToolShedInstance object, access various modules via the class fields. For example, to work with repositories and get a list of all public repositories, the following should be done:

from bioblend import toolshed

ts = toolshed.ToolShedInstance(url='https://testtoolshed.g2.bx.psu.edu')

rl = ts.repositories.get_repositories()

tools = ts.tools.search_tools('fastq')
Parameters

  • url (str) – A FQDN or IP for a given instance of ToolShed. For example: https://testtoolshed.g2.bx.psu.edu . If a ToolShed instance is served under a prefix (e.g. http://127.0.0.1:8080/toolshed/), supply the entire URL including the prefix (note that the prefix must end with a slash).

  • key (str) – If required, user’s API key for the given instance of ToolShed, obtained from the user preferences.

  • email (str) – ToolShed e-mail address corresponding to the user. Ignored if key is supplied directly.

  • password (str) – Password of ToolShed account corresponding to the above e-mail address. Ignored if key is supplied directly.

  • verify (bool) – Whether to verify the server’s TLS certificate

Categories

Interaction with a Tool Shed instance categories

class bioblend.toolshed.categories.ToolShedCategoryClient(toolshed_instance: ToolShedInstance)[source]

A generic Client interface defining the common fields.

All clients must define the following field (which will be used as part of the URL composition (e.g., http://<galaxy_instance>/api/libraries): self.module = 'workflows' | 'libraries' | 'histories' | ...

get_categories(deleted: bool = False) → List[Dict[str, Any]][source]

Returns a list of dictionaries that contain descriptions of the repository categories found on the given Tool Shed instance.

Parameters

deleted (bool) – whether to show deleted categories. Requires administrator access to the Tool Shed instance.

Return type

list

Returns

A list of dictionaries containing information about repository categories present in the Tool Shed. For example:

[{'deleted': False,
  'description': 'Tools for manipulating data',
  'id': '175812cd7caaf439',
  'model_class': 'Category',
  'name': 'Text Manipulation',
  'url': '/api/categories/175812cd7caaf439'}]

New in version 0.5.2.

get_repositories(category_id: str, sort_key: typing_extensions.Literal[name, owner] = 'name', sort_order: typing_extensions.Literal[asc, desc] = 'asc') → Dict[str, Any][source]

Returns a dictionary of information for a repository category including a list of repositories belonging to the category.

Parameters

  • category_id (str) – Encoded category ID

  • sort_key (str) – key for sorting. Options are ‘name’ or ‘owner’ (default ‘name’).

  • sort_order (str) – ordering of sorted output. Options are ‘asc’ or ‘desc’ (default ‘asc’).

Return type

dict

Returns

A dict containing information about the category including a list of repository dicts. For example:

{'deleted': False,
 'description': 'Tools for constructing and analyzing 3-dimensional shapes and '
                'their properties',
 'id': '589548af7e391bcf',
 'model_class': 'Category',
 'name': 'Constructive Solid Geometry',
 'repositories': [{'create_time': '2016-08-23T18:53:23.845013',
                   'deleted': False,
                   'deprecated': False,
                   'description': 'Adds a surface field to a selected shape '
                                  'based on a given mathematical expression',
                   'homepage_url': 'https://github.com/gregvonkuster/galaxy-csg',
                   'id': 'af2ccc53697b064c',
                   'metadata': {'0:e12b55e960de': {'changeset_revision': 'e12b55e960de',
                                                   'downloadable': True,
                                                   'has_repository_dependencies': False,
                                                   'id': 'dfe022067783215f',
                                                   'includes_datatypes': False,
                                                   'includes_tool_dependencies': False,
                                                   'includes_tools': True,
                                                   'includes_tools_for_display_in_tool_panel': True,
                                                   'includes_workflows': False,
                                                   'malicious': False,
                                                   'missing_test_components': False,
                                                   'model_class': 'RepositoryMetadata',
                                                   'numeric_revision': 0,
                                                   'repository_id': 'af2ccc53697b064c'}},
                   'model_class': 'Repository',
                   'name': 'icqsol_add_surface_field_from_expression',
                   'owner': 'iuc',
                   'private': False,
                   'remote_repository_url': 'https://github.com/gregvonkuster/galaxy-csg',
                   'times_downloaded': 152,
                   'type': 'unrestricted',
                   'user_id': 'b563abc230aa8fd0'},
                  # ...
                  ],
 'repository_count': 11,
 'url': '/api/categories/589548af7e391bcf'}

gi: GalaxyClient
module: str = 'categories'
show_category(category_id: str) → Dict[str, Any][source]

Get details of a given category.

Parameters

category_id (str) – Encoded category ID

Return type

dict

Returns

details of the given category

Repositories

Interaction with a Tool Shed instance repositories

class bioblend.toolshed.repositories.ToolShedRepositoryClient(toolshed_instance: ToolShedInstance)[source]

A generic Client interface defining the common fields.

All clients must define the following field (which will be used as part of the URL composition (e.g., http://<galaxy_instance>/api/libraries): self.module = 'workflows' | 'libraries' | 'histories' | ...

create_repository(name: str, synopsis: str, description: Optional[str] = None, type: typing_extensions.Literal[unrestricted, repository_suite_definition, tool_dependency_definition] = 'unrestricted', remote_repository_url: Optional[str] = None, homepage_url: Optional[str] = None, category_ids: Optional[List[str]] = None) → Dict[str, Any][source]

Create a new repository in a Tool Shed.

Parameters

  • name (str) – Name of the repository

  • synopsis (str) – Synopsis of the repository

  • description (str) – Optional description of the repository

  • type (str) – type of the repository. One of “unrestricted”, “repository_suite_definition”, or “tool_dependency_definition”

  • remote_repository_url (str) – Remote URL (e.g. GitHub/Bitbucket repository)

  • homepage_url (str) – Upstream’s homepage for the project

  • category_ids (list) – List of encoded category IDs

Return type

dict

Returns

a dictionary containing information about the new repository. For example:

{"deleted": false,
 "deprecated": false,
 "description": "new_synopsis",
 "homepage_url": "https://github.com/galaxyproject/",
 "id": "8cf91205f2f737f4",
 "long_description": "this is some repository",
 "model_class": "Repository",
 "name": "new_repo_17",
 "owner": "qqqqqq",
 "private": false,
 "remote_repository_url": "https://github.com/galaxyproject/tools-devteam",
 "times_downloaded": 0,
 "type": "unrestricted",
 "user_id": "adb5f5c93f827949"}

get_ordered_installable_revisions(name: str, owner: str) → List[str][source]

Returns the ordered list of changeset revision hash strings that are associated with installable revisions. As in the changelog, the list is ordered oldest to newest.

Parameters

  • name (str) – the name of the repository

  • owner (str) – the owner of the repository

Return type

list

Returns

List of changeset revision hash strings from oldest to newest

get_repositories(name: Optional[str] = None, owner: Optional[str] = None) → List[Dict[str, Any]][source]

Get all repositories in a Galaxy Tool Shed, or select a subset by specifying optional arguments for filtering (e.g. a repository name).

Parameters

  • name (str) – Repository name to filter on.

  • owner (str) – Repository owner to filter on.

Return type

list

Returns

Returns a list of dictionaries containing information about repositories present in the Tool Shed. For example:

[{'category_ids': ['c1df3132f6334b0e', 'f6d7b0037d901d9b'],
  'create_time': '2020-02-09T16:24:37.098176',
  'deleted': False,
  'deprecated': False,
  'description': 'Order Contigs',
  'homepage_url': '',
  'id': '287bd69f724b99ce',
  'model_class': 'Repository',
  'name': 'best_tool_ever',
  'owner': 'billybob',
  'private': False,
  'remote_repository_url': '',
  'times_downloaded': 0,
  'type': 'unrestricted',
  'user_id': '5cefd48bc04af6d4'}]

Changed in version 0.4.1: Changed method name from get_tools to get_repositories to better align with the Tool Shed concepts.

get_repository_revision_install_info(name: str, owner: str, changeset_revision: str) → List[Dict[str, Any]][source]

Return a list of dictionaries of metadata about a certain changeset revision for a single tool.

Parameters

  • name (str) – the name of the repository

  • owner (str) – the owner of the repository

  • changeset_revision (str) – the changeset_revision of the RepositoryMetadata object associated with the repository

Return type

List of dictionaries

Returns

Returns a list of the following dictionaries:

  1. a dictionary defining the repository

  2. a dictionary defining the repository revision (RepositoryMetadata)

  3. a dictionary including the additional information required to install the repository

For example:

[{'create_time': '2020-08-20T13:17:08.818518',
  'deleted': False,
  'deprecated': False,
  'description': 'Galaxy Freebayes Bayesian genetic variant detector tool',
  'homepage_url': '',
  'id': '491b7a3fddf9366f',
  'long_description': 'Galaxy Freebayes Bayesian genetic variant detector tool originally included in the Galaxy code distribution but migrated to the tool shed.',
  'model_class': 'Repository',
  'name': 'freebayes',
  'owner': 'devteam',
  'private': False,
  'remote_repository_url': '',
  'times_downloaded': 269,
  'type': 'unrestricted',
  'url': '/api/repositories/491b7a3fddf9366f',
  'user_id': '1de29d50c3c44272'},
 {'changeset_revision': 'd291dc763c4c',
  'do_not_test': False,
  'downloadable': True,
  'has_repository_dependencies': False,
  'id': '504be8aaa652c154',
  'includes_datatypes': False,
  'includes_tool_dependencies': True,
  'includes_tools': True,
  'includes_tools_for_display_in_tool_panel': True,
  'includes_workflows': False,
  'malicious': False,
  'missing_test_components': False,
  'model_class': 'RepositoryMetadata',
  'numeric_revision': 0,
  'repository_id': '491b7a3fddf9366f',
  'url': '/api/repository_revisions/504be8aaa652c154'},
  'valid_tools': [{'add_to_tool_panel': True,
    'description': '- Bayesian genetic variant detector',
    'guid': 'testtoolshed.g2.bx.psu.edu/repos/devteam/freebayes/freebayes/0.0.3',
    'id': 'freebayes',
    'name': 'FreeBayes',
    'requirements': [{'name': 'freebayes',
      'type': 'package',
      'version': '0.9.6_9608597d12e127c847ae03aa03440ab63992fedf'},
    {'name': 'samtools', 'type': 'package', 'version': '0.1.18'}],
    'tests': [{'inputs': [['reference_source|reference_source_selector',
        'history'],
      ['options_type|options_type_selector', 'basic'],
      ['reference_source|ref_file', 'phiX.fasta'],
      ['reference_source|input_bams_0|input_bam', 'fake_phiX_reads_1.bam']],
      'name': 'Test-1',
      'outputs': [['output_vcf', 'freebayes_out_1.vcf.contains']],
      'required_files': ['fake_phiX_reads_1.bam',
      'phiX.fasta',
      'freebayes_out_1.vcf.contains']}],
    'tool_config': '/srv/toolshed/test/var/data/repos/000/repo_708/freebayes.xml',
    'tool_type': 'default',
    'version': '0.0.3',
    'version_string_cmd': None}]},
 {'freebayes': ['Galaxy Freebayes Bayesian genetic variant detector tool',
                'http://testtoolshed.g2.bx.psu.edu/repos/devteam/freebayes',
                'd291dc763c4c',
                '9',
                'devteam',
                {},
                {'freebayes/0.9.6_9608597d12e127c847ae03aa03440ab63992fedf': {'changeset_revision': 'd291dc763c4c',
                                                                              'name': 'freebayes',
                                                                              'repository_name': 'freebayes',
                                                                              'repository_owner': 'devteam',
                                                                              'type': 'package',
                                                                              'version': '0.9.6_9608597d12e127c847ae03aa03440ab63992fedf'},
                 'samtools/0.1.18': {'changeset_revision': 'd291dc763c4c',
                                     'name': 'samtools',
                                     'repository_name': 'freebayes',
                                     'repository_owner': 'devteam',
                                     'type': 'package',
                                     'version': '0.1.18'}}]}]

gi: GalaxyClient
module: str = 'repositories'
repository_revisions(downloadable: Optional[bool] = None, malicious: Optional[bool] = None, missing_test_components: Optional[bool] = None, includes_tools: Optional[bool] = None) → List[Dict[str, Any]][source]

Returns a (possibly filtered) list of dictionaries that include information about all repository revisions. The following parameters can be used to filter the list.

Parameters

  • downloadable (bool) – Can the tool be downloaded

  • malicious (bool) –

  • missing_test_components (bool) –

  • includes_tools (bool) –

Return type

List of dictionaries

Returns

Returns a (possibly filtered) list of dictionaries that include information about all repository revisions. For example:

[{'changeset_revision': '6e26c5a48e9a',
  'downloadable': True,
  'has_repository_dependencies': False,
  'id': '92250afff777a169',
  'includes_datatypes': False,
  'includes_tool_dependencies': False,
  'includes_tools': True,
  'includes_tools_for_display_in_tool_panel': True,
  'includes_workflows': False,
  'malicious': False,
  'missing_test_components': False,
  'model_class': 'RepositoryMetadata',
  'numeric_revision': None,
  'repository_id': '78f2604ff5e65707',
  'url': '/api/repository_revisions/92250afff777a169'},
 {'changeset_revision': '15a54fa11ad7',
  'downloadable': True,
  'has_repository_dependencies': False,
  'id': 'd3823c748ae2205d',
  'includes_datatypes': False,
  'includes_tool_dependencies': False,
  'includes_tools': True,
  'includes_tools_for_display_in_tool_panel': True,
  'includes_workflows': False,
  'malicious': False,
  'missing_test_components': False,
  'model_class': 'RepositoryMetadata',
  'numeric_revision': None,
  'repository_id': 'f9662009da7bfce0',
  'url': '/api/repository_revisions/d3823c748ae2205d'}]

search_repositories(q: str, page: int = 1, page_size: int = 10) → Dict[str, Any][source]

Search for repositories in a Galaxy Tool Shed.

Parameters

  • q (str) – query string for searching purposes

  • page (int) – page requested

  • page_size (int) – page size requested

Return type

dict

Returns

dictionary containing search hits as well as metadata for the search. For example:

{'hits': [{'matched_terms': [],
           'repository': {'approved': 'no',
                          'categories': 'fastq manipulation',
                          'description': 'Convert export file to fastq',
                          'full_last_updated': '2015-01-18 09:48 AM',
                          'homepage_url': '',
                          'id': 'bdfa208f0cf6504e',
                          'last_updated': 'less than a year',
                          'long_description': 'This is a simple too to convert Solexas Export files to FASTQ files.',
                          'name': 'export_to_fastq',
                          'remote_repository_url': '',
                          'repo_lineage': "['0:c9e926d9d87e', '1:38859774da87']"
                          'repo_owner_username': 'louise',
                          'times_downloaded': 164},
           'score': 4.92},
          {'matched_terms': [],
           'repository': {'approved': 'no',
                          'categories': 'fastq manipulation',
                          'description': 'Convert BAM file to fastq',
                          'full_last_updated': '2015-04-07 11:57 AM',
                          'homepage_url': '',
                          'id': '175812cd7caaf439',
                          'last_updated': 'less than a month',
                          'long_description': 'Use Picards SamToFastq to convert a BAM file to fastq. Useful for storing reads as BAM in Galaxy and converting to fastq when needed for analysis.',
                          'name': 'bam_to_fastq',
                          'remote_repository_url': '',
                          'repo_lineage': "['0:a0af255e28c1', '1:2523cb0fb84c', '2:2656247b5253']"
                          'repo_owner_username': 'brad-chapman',
                          'times_downloaded': 138},
           'score': 4.14}],
 'hostname': 'https://testtoolshed.g2.bx.psu.edu/',
 'page': '1',
 'page_size': '2',
 'total_results': '64'}

show_repository(toolShed_id: str) → Dict[str, Any][source]

Display information of a repository from Tool Shed

Parameters

toolShed_id (str) – Encoded Tool Shed ID

Return type

dict

Returns

Information about the tool. For example:

{'category_ids': ['c1df3132f6334b0e', 'f6d7b0037d901d9b'],
 'create_time': '2020-02-22T20:39:15.548491',
 'deleted': False,
 'deprecated': False,
 'description': 'Order Contigs',
 'homepage_url': '',
 'id': '287bd69f724b99ce',
 'long_description': '',
 'model_class': 'Repository',
 'name': 'best_tool_ever',
 'owner': 'billybob',
 'private': False,
 'remote_repository_url': '',
 'times_downloaded': 0,
 'type': 'unrestricted',
 'user_id': '5cefd48bc04af6d4'}

Changed in version 0.4.1: Changed method name from show_tool to show_repository to better align with the Tool Shed concepts.

show_repository_revision(metadata_id: str) → Dict[str, Any][source]

Returns a dictionary that includes information about a specified repository revision.

Parameters

metadata_id (str) – Encoded repository metadata ID

Return type

dict

Returns

Returns a dictionary that includes information about a specified repository revision. For example:

{'changeset_revision': '7602de1e7f32',
 'downloadable': True,
 'has_repository_dependencies': False,
 'id': '504be8aaa652c154',
 'includes_datatypes': False,
 'includes_tool_dependencies': False,
 'includes_tools': True,
 'includes_tools_for_display_in_tool_panel': True,
 'includes_workflows': False,
 'malicious': False,
 'missing_test_components': True,
 'model_class': 'RepositoryMetadata',
 'numeric_revision': None,
 'repository_dependencies': [],
 'repository_id': '491b7a3fddf9366f',
 'url': '/api/repository_revisions/504be8aaa652c154'}

update_repository(id: str, tar_ball_path: str, commit_message: Optional[str] = None) → Dict[str, Any][source]

Update the contents of a Tool Shed repository with specified tar ball.

Parameters

  • id (str) – Encoded repository ID

  • tar_ball_path (str) – Path to file containing tar ball to upload.

  • commit_message (str) – Commit message used for the underlying Mercurial repository backing Tool Shed repository.

Return type

dict

Returns

Returns a dictionary that includes repository content warnings. Most valid uploads will result in no such warning and an exception will be raised generally if there are problems. For example a successful upload will look like:

{'content_alert': '',
 'message': ''}

New in version 0.5.2.

update_repository_metadata(toolShed_id: str, name: Optional[str] = None, synopsis: Optional[str] = None, description: Optional[str] = None, remote_repository_url: Optional[str] = None, homepage_url: Optional[str] = None, category_ids: Optional[List[str]] = None) → Dict[str, Any][source]

Update metadata of a Tool Shed repository.

Parameters

  • name (str) – ID of the repository to update

  • name – New name of the repository

  • synopsis (str) – New synopsis of the repository

  • description (str) – New description of the repository

  • remote_repository_url (str) – New remote URL (e.g. GitHub/Bitbucket repository)

  • homepage_url (str) – New upstream homepage for the project

  • category_ids (list) – New list of encoded category IDs

Return type

dict

Returns

a dictionary containing information about the updated repository.

Tools

Interaction with a Tool Shed instance tools

class bioblend.toolshed.tools.ToolShedToolClient(toolshed_instance: ToolShedInstance)[source]

A generic Client interface defining the common fields.

All clients must define the following field (which will be used as part of the URL composition (e.g., http://<galaxy_instance>/api/libraries): self.module = 'workflows' | 'libraries' | 'histories' | ...

gi: ToolShedInstance
module: str = 'tools'
search_tools(q: str, page: int = 1, page_size: int = 10) → Dict[str, Any][source]

Search for tools in a Galaxy Tool Shed.

Parameters

  • q (str) – query string for searching purposes

  • page (int) – page requested

  • page_size (int) – page size requested

Return type

dict

Returns

dictionary containing search hits as well as metadata for the search. For example:

{'hits': [{'matched_terms': [],
           'score': 3.0,
           'tool': {'description': 'convert between various FASTQ quality formats',
                    'id': '69819b84d55f521efda001e0926e7233',
                    'name': 'FASTQ Groomer',
                    'repo_name': None,
                    'repo_owner_username': 'devteam'}},
          {'matched_terms': [],
           'score': 3.0,
           'tool': {'description': 'converts a bam file to fastq files.',
                    'id': '521e282770fd94537daff87adad2551b',
                    'name': 'Defuse BamFastq',
                    'repo_name': None,
                    'repo_owner_username': 'jjohnson'}}],
 'hostname': 'https://testtoolshed.g2.bx.psu.edu/',
 'page': '1',
 'page_size': '2',
 'total_results': '118'}