API documentation for interacting with the Galaxy Toolshed

ToolShedInstance

class bioblend.toolshed.ToolShedInstance(url, key=None, email=None, password=None, verify=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, key=None, email=None, password=None, verify=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

Categories

Interaction with a Tool Shed instance categories

class bioblend.toolshed.categories.ToolShedCategoryClient(toolshed_instance)[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=False)[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

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.

show_category(category_id)[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)[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, synopsis, description=None, type='unrestricted', remote_repository_url=None, homepage_url=None, category_ids=None)[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, owner)[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()[source]

Get a list of all the repositories in a Galaxy Tool Shed.

Return type

list

Returns

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

[{'category_ids': ['c1df3132f6334b0e', 'f6d7b0037d901d9b'],
  'deleted': False,
  'deprecated': False,
  'description': 'Order Contigs',
  'homepage_url': '',
  'id': '287bd69f724b99ce',
  'name': 'best_tool_ever',
  'owner': 'billybob',
  'private': False,
  'remote_repository_url': '',
  'times_downloaded': 0,
  'type': 'unrestricted',
  'url': '/api/repositories/287bd69f724b99ce',
  '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, owner, changeset_revision)[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:

[{'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.',
  '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,
  'repository_id': '491b7a3fddf9366f',
  'url': '/api/repository_revisions/504be8aaa652c154'},
 {'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'}}]}]

repository_revisions(downloadable=None, malicious=None, tools_functionally_correct=None, missing_test_components=None, do_not_test=None, includes_tools=None, test_install_error=None, skip_tool_test=None)[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) –

  • tools_functionally_correct (bool) –

  • missing_test_components (bool) –

  • do_not_test (bool) –

  • includes_tools (bool) –

  • test_install_error (bool) –

  • skip_tool_test (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',
  'do_not_test': False,
  '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,
  'repository_id': '78f2604ff5e65707',
  'test_install_error': False,
  'time_last_tested': None,
  'tools_functionally_correct': False,
  'url': '/api/repository_revisions/92250afff777a169'},
 {'changeset_revision': '15a54fa11ad7',
  'do_not_test': False,
  '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,
  'repository_id': 'f9662009da7bfce0',
  'test_install_error': False,
  'time_last_tested': None,
  'tools_functionally_correct': False,
  'url': '/api/repository_revisions/d3823c748ae2205d'}]

search_repositories(q, page=1, page_size=10)[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',
                          '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_owner_username': 'louise',
                          'times_downloaded': 164},
           'score': 4.92},
          {'matched_terms': [],
           'repository': {'approved': 'no',
                          '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_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)[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'],
 'deleted': False,
 'deprecated': False,
 'description': 'Order Contigs',
 'homepage_url': '',
 'id': '287bd69f724b99ce',
 'long_description': '',
 'name': 'best_tool_ever',
 'owner': 'billybob',
 'private': False,
 'remote_repository_url': '',
 'times_downloaded': 0,
 'type': 'unrestricted',
 'url': '/api/repositories/287bd69f724b99ce',
 '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)[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',
 'do_not_test': False,
 '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,
 'repository_id': '491b7a3fddf9366f',
 'test_install_error': False,
 'time_last_tested': None,
 'tool_test_results': {'missing_test_components': []},
 'tools_functionally_correct': False,
 'url': '/api/repository_revisions/504be8aaa652c154'}

update_repository(id, tar_ball_path, commit_message=None)[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.

Tools

Interaction with a Tool Shed instance tools

class bioblend.toolshed.tools.ToolShedToolClient(toolshed_instance)[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' | ...

search_tools(q, page=1, page_size=10)[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'}