Skip to main content

GA4GH TRS Client

Project description

TRS-cli

License Build_status Docs Coverage GitHub_tag PyPI_release

Client for implementations of the Global Alliance for Genomics and Health (GA4GH) Tool Registry Service API schema, including support for additional endpoints defined in ELIXIR Cloud & AAI's generic TRS-Filer TRS implementation.

Table of Contents

Usage

To use the client import it as follows in your Python code after installation:

from trs_cli import TRSClient

Configure client class

It is possible to configure the TRSClient class with the .config() class method. Currently there is only a single configuration parameter available, the debug flag. Setting it to True (default: False) will have the exception handler print tracebacks for every exception encountered.

Example:

from trs_cli import TRSClient

TRSClient.config(debug=True)

Note that as a class method, the .config() method will affect all client instances.

Create client instance

Via TRS hostname

A client instance can be created by specifying the domain name of a TRS instance, including the URL schema:

from trs_cli import TRSClient

client = TRSClient(uri="https://my-trs.app")
# Client instantiated for URL: https://my-trs.app:443/ga4gh/trs/v2

Fully spec-compliant TRS implementations will always be available at https URLs, served at port 443 and at the base path ga4gh/trs/v2. However, to allow the client to be used against development versions of TRS implementations, http URLs are supported as well (default port 80), and the port and base path at which the API endpoints are served can be overridden with the port and base_path arguments:

from trs_cli import TRSClient

client = TRSClient(
    uri="http://my-trs.app",
    port=8080,
    base_path="my/api/route",
)
# Client instantiated for URL: http://my-trs.app:8080/my/api/route

Via TRS URI

Clients can also be created by passing a hostname-based TRS URI:

from trs_cli import TRSClient

client = TRSClient(uri="trs://my-trs.app/SOME_TOOL")
# Client instantiated for URL: https://my-trs.app:443/ga4gh/trs/v1

NOTE: Only the hostname part of the TRS URI is evaluated, not the tool ID.

Port and base path can be overridden as described above. In addition, the client constructor also defines the use_http flag, which instantiates a client for an http URL when a TRS URI is passed. The flag has no effect when a TRS hostname URL is provided instead of a TRS URI:

from trs_cli import TRSClient

client = TRSClient(
    uri="trs://my-trs.app/SOME_TOOL",
    use_http=True,
)
# Client instantiated for URL: http://my-trs.app:443/ga4gh/trs/v1

Access methods

NOTES:

  • All endpoint access methods require a client instance.
  • For accessing endpoints that require authorization, see the dedicated section.
  • Responses that do not return the tool ID as a single string return Pydantic models instead. If dictionaries are preferred instead, they can be obtained with response.dict(). See the Pydantic export documentation for further details.
  • See the API documentation for further details on each access method.

Endpoints as specified in the TRS API

Access methods for each Tool Registry Service API endpoint are available:

Method Endpoint Description
.get_tool_classes() GET ​/toolClasses List all tool types
.get_tools() GET ​/tools List all tools
.get_tool() GET ​/tools​/{id} List one specific tool, acts as an anchor for self references
.get_versions() GET ​/tools​/{id}​/versions List versions of a tool
.get_version() GET ​/tools​/{id}​/versions​/{version_id} List one specific tool version, acts as an anchor for self references
.get_containerfiles() GET ​/tools​/{id}​/versions​/{version_id}​/containerfile Get the container specification(s) for the specified image.
.get_descriptor() GET ​/tools​/{id}​/versions​/{version_id}​/{type}​/descriptor Get the tool descriptor for the specified tool
.get_descriptor_by_path() GET ​/tools​/{id}​/versions​/{version_id}​/{type}​/descriptor​/{relative_path} Get additional tool descriptor files relative to the main file
.get_files() GET ​/tools​/{id}​/versions​/{version_id}​/{type}​/files Get a list of objects that contain the relative path and file type
.get_tests() GET ​/tools​/{id}​/versions​/{version_id}​/{type}​/tests Get a list of test JSONs
.get_service_info() GET ​/service-info Show information about this service. It is assumed that removing this endpoint from a URL will result in a valid URL to query against

TRS-Filer-specific endpoints

In addition to TRS API endpoints, the TRSClient class also provides access methods for additional endpoints implemented in TRS-Filer:

Method Endpoint Description
.post_tool_class() POST ​/toolClasses Create a tool class
.put_tool_class() PUT ​/toolClasses​/{id} Create or update a tool class
.delete_tool_class() DELETE ​/toolClasses​/{id} Delete a tool class
.post_tool() POST ​/tools Add a tool
.put_tool() PUT ​/tools​/{id} Add or update a tool
.delete_tool() DELETE ​/tools​/{id} Delete a tool
.post_version() POST ​/tools​/{id}​/versions Add a tool version
.put_version() PUT ​/tools​/{id}​/versions​/{version_id} Add or update a tool version
.delete_version() DELETE ​/tools​/{id}​/versions​/{version_id} Delete a tool version
.post_service_info() POST ​/service-info Register service info

Convenience methods

Finally, TRS-cli tries to provide convenience methods for common operations that involve multiple API calls. Currently there is one such method defined:

Method Description
.retrieve_files() Retrieve all files associated with a given tool version and descriptor type. Useful for downloading workflows.

Authorization

Authorization bearer tokens can be provided either during client instantiation or when calling an endpoint access method. The bearer token is sent along as an Authorization header with every request sent from the instantiated client instance.

NOTE: Whenever a token is specified when calling an API endpoint, the token variable of that particular client instance is overridden. Thus, subsequent calls from that client will all carry the new token value, unless overridden again.

The following example illustrates this behavior:

from trs_cli import TRSClient

# No token passed during client instantiation
client = TRSClient(uri="https://my-trs.app")
# Value of client.token: None

# Token passed during client instantiation
client_2 = TRSClient(
    uri="https://my-trs.app",
    token="MyT0k3n",
)
# Value of client_2.token: MyT0k3n

API documentation

Automatically built API documentation is available.

Installation

You can install TRS-cli in one of two ways:

Via package manager

pip install trs_cli

# Or for the latest development version:
pip install git+https://github.com/elixir-cloud-aai/TRS-cli.git#egg=trs_cli

Manual installation

git clone https://github.com/elixir-cloud-aai/TRS-cli.git
cd TRS-cli
python setup.py install

Contributing

This project is a community effort and lives off your contributions, be it in the form of bug reports, feature requests, discussions, or fixes and other code changes. Please refer to our organization's contributing guidelines if you are interested to contribute. Please mind the code of conduct for all interactions with the community.

Versioning

The project adopts the semantic versioning scheme for versioning. Currently the service is in beta stage, so the API may change without further notice.

License

This project is covered by the Apache License 2.0 also shipped with this repository.

Contact

The project is a collaborative effort under the umbrella of ELIXIR Cloud & AAI. Follow the link to get in touch with us via chat or email. Please mention the name of this service for any inquiry, proposal, question etc.

logo_banner

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

trs_cli-0.6.0.tar.gz (25.5 kB view hashes)

Uploaded Source

Built Distribution

trs_cli-0.6.0-py3-none-any.whl (22.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page