API documentation for interacting with Galaxy — BioBlend 0.2.3-dev documentation

### Navigation

- index
- modules |
- next |
- previous |
- BioBlend 0.2.3-dev documentation »

# API documentation for interacting with Galaxy

## GalaxyInstance

class `bioblend.galaxy.` `GalaxyInstance`(url, key)

  A base representation of an instance of Galaxy, identified by a URL and a user’s API key.

  After you have created an `GalaxyInstance` object, access various modules via the class fields (see the source for the most up-to-date list): `libraries`, `histories`, `workflows`, `datasets`, and `users` are the minimum set supported. For example, to work with histories, and get a list of all the user’s histories, the following should be done:

      from bioblend import galaxy

      gi = galaxy.GalaxyInstance(url='http://127.0.0.1:8000', key='your_api_key')

      hl = gi.histories.get_histories()
      print "List of histories:", hl

  Parameters: | url (string) – A FQDN or IP for a given instance of Galaxy. For example: http://127.0.0.1:8080 key (string) – User’s API key for the given instance of Galaxy, obtained from the user preferences.

  `__init__`(url, key)

    A base representation of an instance of Galaxy, identified by a URL and a user’s API key.

    After you have created an `GalaxyInstance` object, access various modules via the class fields (see the source for the most up-to-date list): `libraries`, `histories`, `workflows`, `datasets`, and `users` are the minimum set supported. For example, to work with histories, and get a list of all the user’s histories, the following should be done:

        from bioblend import galaxy

        gi = galaxy.GalaxyInstance(url='http://127.0.0.1:8000', key='your_api_key')

        hl = gi.histories.get_histories()
        print "List of histories:", hl

    Parameters: | url (string) – A FQDN or IP for a given instance of Galaxy. For example: http://127.0.0.1:8080 key (string) – User’s API key for the given instance of Galaxy, obtained from the user preferences.

  `make_delete_request`(url, payload=None, params=None)

    Make a DELETE request using the provided `url` and the optional arguments. The `payload` must be a dict that can be converted into a JSON object (via `simplejson.dumps`)

    If the `params` are not provided, use `default_params` class field. If params are provided and the provided dict does not have `key` key, the default `self.key` value will be included in what’s passed to the server via the request.

  `make_get_request`(url, params=None)

    Make a GET request using the provided url.

    If the `params` are not provided, use `default_params` class field. If params are provided and the provided dict does not have `key` key, the default `self.key` value will be included in what’s passed to the server via the request.

  `make_post_request`(url, payload, params=None, files_attached=False)

    Make a POST request using the provided `url` and `payload`. The `payload` must be a dict that contains the request values. The payload dict may contain file handles (in which case the files_attached flag must be set to true).

    If the `params` are not provided, use `default_params` class field. If params are provided and the provided dict does not have `key` key, the default `self.key` value will be included in what’s passed to the server via the request.

    The return value will contain the response body as a JSON object.

## Libraries

Contains possible interactions with the Galaxy Data Libraries

class `bioblend.galaxy.libraries.` `LibraryClient`(galaxy_instance)
  `create_folder`(library_id, folder_name, description=None, base_folder_id=None)

    Create a folder in the given library and the base folder. If `base_folder_id` is not provided, the new folder will be created in the root folder.

  `create_library`(name, description=None, synopsis=None)

    Create a data library with the properties defined in the arguments. Return a list of JSON dicts, looking like so:

        [{"id": "f740ab636b360a70",
          "name": "Library from bioblend",
          "url": "/api/libraries/f740ab636b360a70"}]

  `get_libraries`(library_id=None, name=None, deleted=False)

    Get all the libraries or filter for specific one(s) via the provided name or ID. Provide only one argument: `name` or `library_id`.

    If `name` is set and multiple names match the given name, all the libraries matching the argument will be returned.

    Return a list of JSON formatted dicts each containing basic information about a library.

  `show_library`(library_id, contents=False)

    Get information about a library.

    If want to get contents of the library (rather than just the library details), set `contents` to `True`.

    Return a list of JSON formatted dicts containing library details.

  `upload_file_contents`(library_id, pasted_content, folder_id=None, file_type='auto', dbkey='?')

    Upload pasted_contents to a data library as a new file. If `folder_id` is not specified, the file will be placed in the root folder.

  `upload_file_from_local_path`(library_id, file_local_path, folder_id=None, file_type='auto', dbkey='?')

    Read local file contents from file_local_path and upload data to a library. If `folder_id` is not specified, the file will be placed in the root folder.

  `upload_file_from_server`(library_id, server_dir, folder_id=None, file_type='auto', dbkey='?', link_data_only=None, roles='')

    Upload a file to a library from a path on the server where Galaxy is running. If `folder_id` is not provided, the file will be placed in the root folder.

    Note that for this method to work, the Galaxy instance you’re connecting to must have the configuration option `library_import_dir` set in `universe_wsgi.ini`. The value of that configuration option should be a base directory from where more specific directories can be specified as part of the `server_dir` argument. All and only the files (ie, no folders) specified by the `server_dir` argument will be uploaded to the data library.

  `upload_file_from_url`(library_id, file_url, folder_id=None, file_type='auto', dbkey='?')

    Upload a file to a library from a URL. If `folder_id` is not specified, the file will be uploaded to the root folder.

  `upload_from_galaxy_filesystem`(library_id, filesystem_paths, folder_id=None, file_type='auto', dbkey='?', link_data_only=None, roles='')

    Upload a file from filesystem paths already present on the Galaxy server.

    Provides API access for the ‘Upload files from filesystem paths’ approach.

    `link_data_only` – whether to copy data into Galaxy. Setting to ‘link_to_files’
      symlinks data instead of copying

## Histories

Contains possible interactions with the Galaxy Histories

class `bioblend.galaxy.histories.` `HistoryClient`(galaxy_instance)
  `create_history`(name=None)

    Create a new history, optionally setting the `name`.

  `delete_history`(history_id, purge=False)

    Delete a history.

    If `purge` is set to `True`, also purge the history. Note that for the purge option to work, `allow_user_dataset_purge` option must be set in the Galaxy’s configuration file `universe_wsgi.ini`

  `download_dataset`(history_id, dataset_id, file_path=None, use_default_filename=True, to_ext=None)
  `get_current_history`()

    Returns the current user’s most recently used history object (not deleted)

  `get_histories`(history_id=None, name=None, deleted=False)

    Get all histories or filter the specific one(s) via the provided `name` or `history_id`. Provide only one argument, `name` or `history_id`, but not both.

    If `deleted` is set to `True`, return histories that have been deleted.

    Return a list of history element dicts. If more than one history matches the given `name`, return the list of all the histories with the given name.

  `get_status`(history_id)

    Returns the state of this history as a dictionary, with the following keys. ‘state’ = This is the current state of the history, such as ok, error, new etc. ‘state_details’ = Contains individual statistics for various dataset states. ‘percent_complete’ = The overall number of datasets processed to completion.

  `show_dataset`(history_id, dataset_id)

    Get details about a given history dataset. The required `history_id` can be obtained from the datasets’s history content details.

  `show_history`(history_id, contents=False)

    Get details of a given history. By default, just get the history meta information. If `contents` is set to `True`, get the complete list of datasets in the given history.

  `undelete_history`(history_id)

    Undelete a history

  `upload_dataset_from_library`(history_id, lib_dataset_id)

    Upload a dataset into the history from a library. Requires the library dataset ID, which can be obtained from the library contents.

## Workflows

Contains possible interactions with the Galaxy Workflows

class `bioblend.galaxy.workflows.` `WorkflowClient`(galaxy_instance)
  `export_workflow_json`(workflow_id)

    Exports a workflow in json format

    Parameters: | workflow_id (string) – Encoded workflow ID

  `export_workflow_to_local_path`(workflow_id, file_local_path, use_default_filename=True)

    Exports a workflow in json format to a given local path.

    Parameters: | workflow_id (string) – Encoded workflow ID file_local_path (string) – Local path to which the exported file will be saved. (Should not contain filename if use_default_name=True) use_default_name (boolean) – If the use_default_name parameter is True, the exported file will be saved as file_local_path/Galaxy-Workflow-%s.ga, where %s is the workflow name. If use_default_name is False, file_local_path is assumed to contain the full file path including filename.

  `get_workflows`()

    Get a list of all workflows

    Return type: | list
    Returns: | A list of workflow dicts. For example:
        [{u'id': u'92c56938c2f9b315',
          u'name': u'Simple',
          u'url': u'/api/workflows/92c56938c2f9b315'}]

  `import_workflow_from_local_path`(file_local_path)

    Imports a new workflow given the path to a file containing a previously exported workflow.

  `import_workflow_json`(workflow_json)

    Imports a new workflow given a json representation of a previously exported workflow.

  `run_workflow`(workflow_id, dataset_map, history_id=None, history_name=None, import_inputs_to_history=False)

    Run the workflow identified by `workflow_id`

    Parameters: | workflow_id (string) – Encoded workflow ID dataset_map (string or dict) – A mapping of workflow inputs to datasets. The datasets source can be a LibraryDatasetDatasetAssociation (`ldda`), LibraryDataset (`ld`), or HistoryDatasetAssociation (`hda`). The map must be in the following format: `{'<input>': {'id': <encoded dataset ID>, 'src': '[ldda, ld, hda]'}}` (eg, `{'23': {'id': '29beef4fadeed09f', 'src': 'ld'}}`) history_id (string) – The encoded history ID where to store the workflow output. `history_id` OR `history_name` should be provided but not both! history_name (string) – Create a new history with the given name to store the workflow output. `history_id` OR `history_name` should be provided but not both! import_inputs_to_history (bool) – If `True`, used workflow inputs will be imported into the history. If `False`, only workflow outputs will be visible in the given history.
    Return type: | dict
    Returns: | A dict containing the history ID where the outputs are placed as well as output dataset IDs. For example:
        {u'history': u'64177123325c9cfd',
         u'outputs': [u'aa4d3084af404259']}

  `show_workflow`(workflow_id)

    Display information needed to run a workflow

    Parameters: | workflow_id (string) – Encoded workflow ID
    Return type: | list
    Returns: | A description of the workflow and its inputs as a JSON object. For example:
        {u'id': u'92c56938c2f9b315',
         u'inputs': {u'23': {u'label': u'Input Dataset', u'value': u''}},
         u'name': u'Simple',
         u'url': u'/api/workflows/92c56938c2f9b315'}

## Datasets

Contains possible interactions with the Galaxy Datasets

class `bioblend.galaxy.datasets.` `DatasetClient`(galaxy_instance)
  `download_dataset`(dataset_id, file_path=None, use_default_filename=True, wait_for_completion=False, maxwait=12000)

    Downloads the dataset identified by ‘id’.

    Parameters: | dataset_id (string) – Encoded Dataset ID file_path (string) – If the file_path argument is provided, the dataset will be streamed to disk at that path (Should not contain filename if use_default_name=True). If the file_path argument is not provided, the dataset content is loaded into memory and returned by the method (Memory consumption may be heavy as the entire file will be in memory). use_default_name (boolean) – If the use_default_name parameter is True, the exported file will be saved as file_local_path/%s, where %s is the dataset name. If use_default_name is False, file_local_path is assumed to contain the full file path including filename. wait_for_completion (boolean) – If wait_for_completion is True, this call will block till the dataset is ready. If the dataset state becomes invalid, a DatasetStateException will be thrown. maxwait (float) – Time (in seconds) to wait for dataset to complete. If the dataset state is not complete within this time, a DatasetTimeoutException will be thrown.
    Return type: | dict
    Returns: | If a file_path argument is not provided, returns a dict containing the file_content. Otherwise returns nothing.

  `show_dataset`(dataset_id, deleted=False)

    Display information about and/or content of a dataset. This can be a history or a library dataset.

exception `bioblend.galaxy.datasets.` `DatasetStateException`(value)

exception `bioblend.galaxy.datasets.` `DatasetTimeoutException`(value)

## Users

Contains possible interaction dealing with Galaxy users.

These methods must be executed by a registered Galaxy admin user.

class `bioblend.galaxy.users.` `UserClient`(galaxy_instance)
  `create_user`(user_email)

    Create a new Galaxy user.

    Note

    For this method to work, the Galaxy instance must have `allow_user_creation` and `use_remote_user` options set to `True` in the `universe_wsgi.ini` configuration file. Also note that setting `use_remote_user` will require an upstream authentication proxy server; however, if you do not have one, access to Galaxy via a browser will not be possible.

  `get_current_user`()

    Returns the user id associated with this Galaxy connection

  `get_users`(deleted=False)

    Get a list of all registered users. If `deleted` is set to `True`, get a list of deleted users.

    Return type: | list
    Returns: | A list of dicts with user details. For example:
        [{u'email': u'a_user@example.com',
          u'id': u'dda47097d9189f15',
          u'url': u'/api/users/dda47097d9189f15'}]

  `show_user`(user_id, deleted=False)

    Display information about a user. If `deleted` is set to `True`, display information about a deleted user.

### Navigation

- index
- modules |
- next |
- previous |
- BioBlend 0.2.3-dev documentation »