Skip to content

Python API reference

The classes, methods and properties of the ga4gh_sdk module, generated from its type stubs (ga4gh_sdk.pyi). The Python bindings guide explains how to install and use them.

ga4gh_sdk

Python clients for GA4GH TES, WES, DRS, TRS and Service Info APIs.

Build a Configuration with the service's API root, then a client for its API: TES (or AsyncTES for asyncio), WES, DRS (and DrsResolver for drs:// URIs) or TRS. ServiceInfo reads any service's service info, and Transport sends requests to further endpoints. The clients return typed result objects that keep the server's full JSON, including fields that the SDK's models don't know.

All classes except the enums can be subclassed. Synchronous network methods release the GIL while they wait. Failed requests and responses that don't fit the API's models raise RuntimeError; invalid arguments raise ValueError before a request is sent.

Example
from ga4gh_sdk import Configuration, TES

tes = TES(Configuration("http://localhost:8000/ga4gh/tes/v1"))
task = tes.create({"executors": [{"image": "alpine", "command": ["echo", "hi"]}]})
print(task.wait(timeout=600))

ServiceType

A built-in section of the configuration file, for Configuration.from_file().

Other sections are named by a str.

TES instance-attribute

TES: ServiceType

The TES section, for TES and AsyncTES.

DRS instance-attribute

DRS: ServiceType

The DRS section, for DRS.

TRS instance-attribute

TRS: ServiceType

The TRS section, for TRS.

AAI instance-attribute

AAI: ServiceType

The AAI section (authentication and authorization infrastructure).

WES instance-attribute

WES: ServiceType

The WES section, for WES.

REGISTRY instance-attribute

REGISTRY: ServiceType

The REGISTRY section (Service Registry).

Configuration

Configuration(base_path: str)

The API root and settings for connecting to a GA4GH service.

from_file() reads a section of ~/.ga4gh-cli/config.json, named by a ServiceType or by a str; in a file with profiles it reads the default profile. get_extra() returns the section's other keys. set_timeouts() and get_timeouts() set and give the time limits of requests in seconds; clients and transports read them when they are built. set_token_provider() sets a callable that gives a bearer token for each request.

Set one source of credentials before building a client: Basic credentials, an OAuth or a generic bearer token, or a token provider. Clients and Transport take the settings when they are built, so later changes don't affect them.

Builds a configuration for the service at base_path.

Parameters:

Name Type Description Default
base_path str

The API root, including the service's path prefix, such as "https://example.org/ga4gh/tes/v1".

required

Raises:

Type Description
ValueError

base_path is not a valid URL.

set_base_path

set_base_path(base_path: str) -> None

Replaces the API root.

Parameters:

Name Type Description Default
base_path str

The new API root, including the service's path prefix.

required

Raises:

Type Description
ValueError

base_path is not a valid URL.

get_base_path

get_base_path() -> str

Gives the API root.

Returns:

Type Description
str

The API root as a URL string.

set_basic_auth

set_basic_auth(
    username: str, password: str | None = None
) -> None

Sets one Basic credential for clients built from this configuration.

Parameters:

Name Type Description Default
username str

The user name.

required
password str | None

The password, if any.

None

set_oauth_access_token

set_oauth_access_token(token: str) -> None

Sets one OAuth bearer token for clients built from this configuration.

Parameters:

Name Type Description Default
token str

The access token, without the Bearer prefix.

required

set_bearer_access_token

set_bearer_access_token(token: str) -> None

Sets one generic bearer token for clients built from this configuration.

Parameters:

Name Type Description Default
token str

The token, without the Bearer prefix.

required

clear_auth

clear_auth() -> None

Removes every credential source, the token provider included.

get_extra

get_extra() -> _JSONObject

Gives the keys of the configuration file section that the SDK doesn't use.

The values are as they are in the file, so don't log them if they can hold credentials.

Returns:

Type Description
_JSONObject

A new dict of the section's other keys; empty if the configuration

_JSONObject

wasn't read from a file.

set_timeouts

set_timeouts(
    *,
    connect: float | None = None,
    request: float | None = None,
    discovery: float | None = None,
    submission: float | None = None,
) -> None

Sets time limits of requests, in seconds.

Limits that aren't given stay as they are; if one value is invalid, none changes. Clients and Transport read the limits when they are built, so set them first.

Parameters:

Name Type Description Default
connect float | None

Opening each connection (default 10).

None
request float | None

Each request that the other limits don't apply to (default 60).

None
discovery float | None

The service check when a client is built, and TRS.service_info() (default 10).

None
submission float | None

TES.create(), AsyncTES.create() and WES.run(), uploads included (default 300).

None

Raises:

Type Description
ValueError

A limit is not a valid number of seconds.

get_timeouts

get_timeouts() -> dict[str, float]

Gives the time limits of requests.

Returns:

Type Description
dict[str, float]

The limits in seconds, by name: connect, request, discovery and

dict[str, float]

submission.

set_token_provider

set_token_provider(
    provider: Callable[[str], str | tuple[str, float]]
    | None,
    *,
    audience: str | None = None,
) -> None

Gets a bearer token from provider for each request, in place of a static one.

Clients and Transport take the provider when they are built. After 401 Unauthorized, the SDK drops a reused token and asks the provider again; a GET request is sent once more, submissions never. If the provider raises or returns something else, the call raises RuntimeError and its request isn't sent. Set the provider after from_file(), which replaces all settings.

Parameters:

Name Type Description Default
provider Callable[[str], str | tuple[str, float]] | None

Called as provider(audience); returns the token as a str, or a (str, float) tuple with the seconds for which the SDK may reuse it. None removes the provider.

required
audience str | None

The value passed to provider; by default, the API root.

None

Raises:

Type Description
TypeError

provider is not callable.

ValueError

audience is given without a provider.

from_file

from_file(service_type: ServiceType | str) -> None

Reads a section of ~/.ga4gh-cli/config.json.

It replaces all settings, including a token provider. In a file with profiles, the section comes from its default profile. A section can name an environment variable for its token with oauth_access_token_env or bearer_access_token_env.

Parameters:

Name Type Description Default
service_type ServiceType | str

A ServiceType, or the name of any other section.

required

Raises:

Type Description
FileNotFoundError

The file doesn't exist.

ValueError

The section is missing, the file is malformed or a named environment variable is unset.

ServiceInfo

ServiceInfo(py_config: Configuration)

Reads a service's service info.

Builds a reader for the service of py_config; sends no request.

Parameters:

Name Type Description Default
py_config Configuration

The service's configuration.

required

get_service_info

get_service_info() -> str

Reads the service info.

Returns:

Type Description
str

The service info as formatted text ("Service: ..."), not as a typed model.

Raises:

Type Description
RuntimeError

The request failed, for example because of conflicting credentials, or the response is not a service info.

DrsObject

A DRS object's metadata, as returned by the server.

Keeps the object's full JSON, including fields that the DRS models don't know. Nested values, such as access_methods, come as dicts and lists.

id property

id: str

The object's ID.

name property

name: str | None

The object's name, such as a file name.

self_uri property

self_uri: str

The object's drs:// URI.

size property

size: int

The object's size in bytes; for a bundle, the sum of its contents.

created_time property

created_time: str

When the object was created, as an RFC 3339 timestamp.

updated_time property

updated_time: str | None

When the object was last updated, as an RFC 3339 timestamp.

version property

version: str | None

The object's version, as the server names it.

mime_type property

mime_type: str | None

The object's media type, such as "application/json".

checksums property

checksums: list[_JSONObject] | None

The object's checksums, as dicts with type and checksum.

access_methods property

access_methods: list[_JSONObject] | None

The ways to fetch the object's bytes, as dicts with type and access_id or access_url; None for a bundle.

contents property

contents: list[_JSONObject] | None

For a bundle, the objects that it contains, as dicts.

description property

description: str | None

A description of the object.

aliases property

aliases: list[str] | None

Other names of the object.

json

json() -> str

Gives the object as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the object as a new dict, as received.

AccessURL

An access URL of a DRS object.

The URL and headers may hold credentials, such as a signature or a bearer token, so repr() doesn't show them; don't log them either.

url property

url: str

The URL to fetch the object's bytes from.

headers property

headers: list[str] | None

The headers to send with a request to url, as "Name: value" strings.

json

json() -> str

Gives the access URL as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the access URL as a new dict, as received.

BulkAccessURL

An access URL from DRS.get_bulk_access_urls(), with the IDs it belongs to.

Like AccessURL, repr() doesn't show the URL or headers.

drs_object_id property

drs_object_id: str | None

The ID of the object that the URL belongs to.

drs_access_id property

drs_access_id: str | None

The access ID that the URL belongs to.

url property

url: str

The URL to fetch the object's bytes from.

headers property

headers: list[str] | None

The headers to send with a request to url, as "Name: value" strings.

json

json() -> str

Gives the entry as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the entry as a new dict, as received.

PendingResolution

The server is still preparing an answer: ask again after retry_after seconds.

api_root and endpoint say what to ask for; they hold no credentials.

api_root property

api_root: str

The API root of the service, without credentials, query or fragment.

endpoint property

endpoint: str

The endpoint to ask again; for a bulk call, call the bulk method again.

retry_after property

retry_after: int

The seconds to wait before asking again (at least 1).

to_dict

to_dict() -> _JSONObject

Gives api_root, endpoint and retry_after as a new dict.

BulkPolicy

BulkPolicy(
    chunk_size: int = 100,
    advertised_limit: int | None = None,
    concurrency: int = 4,
    max_requests: int = 1000,
    max_split_depth: int = 8,
    max_attempts: int = 1,
    initial_delay: float = 0.2,
    max_delay: float = 10.0,
)

Limits of the bulk calls of DRS.

Negative counts and negative or non-finite delays raise ValueError when the policy is built; the other limits are checked when a call starts.

Builds a policy.

Negative counts and negative or non-finite delays raise ValueError here; other invalid values, such as a chunk_size of 0, raise it when a bulk call starts.

Parameters:

Name Type Description Default
chunk_size int

The most IDs per request.

100
advertised_limit int | None

The service's most IDs per request, if known; it lowers chunk_size.

None
concurrency int

The most requests at the same time.

4
max_requests int

The most requests in one call, retries and splits included.

1000
max_split_depth int

How often a request that the server rejects as too large (413) is halved.

8
max_attempts int

The most attempts per request, for network errors, 429 and 503.

1
initial_delay float

The delay before the first retry, in seconds; it doubles up to max_delay.

0.2
max_delay float

The longest delay between retries, in seconds.

10.0

with_service_info

with_service_info(
    service_info: Mapping[str, Any] | str,
) -> BulkPolicy

Gives a copy that also keeps to the service's maxBulkRequestLength.

Parameters:

Name Type Description Default
service_info Mapping[str, Any] | str

The service info, as a dict or JSON text, for example json.loads(drs.transport.get("service-info")).

required

Returns:

Type Description
BulkPolicy

A new policy, with the same limits if the service info has no

BulkPolicy

maxBulkRequestLength.

Raises:

Type Description
ValueError

service_info isn't JSON, or its maxBulkRequestLength is invalid.

chunk_size property

chunk_size: int

The most IDs per request.

advertised_limit property

advertised_limit: int | None

The service's most IDs per request, if known; it lowers chunk_size.

concurrency property

concurrency: int

The most requests at the same time.

max_requests property

max_requests: int

The most requests in one call, retries and splits included.

max_split_depth property

max_split_depth: int

How often a request that the server rejects as too large (413) is halved.

max_attempts property

max_attempts: int

The most attempts per request, for network errors, 429 and 503.

initial_delay property

initial_delay: float

The delay before the first retry, in seconds; it doubles up to max_delay.

max_delay property

max_delay: float

The longest delay between retries, in seconds.

BulkOutcome

Bases: Generic[_Resolved]

The outcome for one requested ID (or ID pair) of a bulk call.

repr() shows counts only, as resolved access URLs and error texts may hold credentials.

object_id property

object_id: str

The requested object ID.

access_id property

access_id: str | None

The access ID of the pair, for get_bulk_access_urls(); else None.

resolved property

resolved: list[_Resolved]

The results that the server returned for the ID; one, if all went well.

failure_codes property

failure_codes: list[int]

The HTTP status codes that the server gave for the ID, such as 404.

pending property

pending: PendingResolution | None

The pending state, if the server is still preparing the answer.

errors property

errors: list[str]

What went wrong otherwise, such as a missing or duplicate answer.

is_success property

is_success: bool

Whether the server returned exactly one result and nothing else for the ID.

BulkReport

Bases: Generic[_Resolved]

The outcomes, unattributed problems, and observed reply shapes of a bulk call.

outcomes property

outcomes: list[BulkOutcome[_Resolved]]

One outcome per distinct requested ID (or ID pair), sorted by ID.

diagnostics property

diagnostics: list[str]

Problems with the server's answers that belong to no ID.

dialects property

dialects: list[str]

Reply shapes seen across the call: standard and, for objects, gen3.

DRS

DRS(config: Configuration)

A DRS client (DRS 1.4) for object metadata and access URLs.

It reads metadata and access URLs, one at a time or in bulk, and never downloads object bytes. IDs are sent as one URL path segment each. Subclass it to add endpoints, using self.transport.

Builds a client and checks the service.

Parameters:

Name Type Description Default
config Configuration

The service's configuration.

required

Raises:

Type Description
RuntimeError

The service isn't reachable or isn't a DRS.

config property

config: Configuration

The client's configuration.

transport property

transport: Transport

A transport with the client's configuration, for further endpoints.

get_object

get_object(object_id: str) -> DrsObject

Gets an object's metadata.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required

Returns:

Type Description
DrsObject

The object.

Raises:

Type Description
ValueError

object_id is empty, . or ...

RuntimeError

The request failed, the response doesn't fit the DRS models, or the server is still preparing the object; use get_object_once() or resolve_object() for that case.

get_object_raw

get_object_raw(object_id: str) -> _JSONObject

Gets an object's complete JSON, without checking it against the DRS models.

This also accepts provider extensions such as created_time: null.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required

Returns:

Type Description
_JSONObject

The object's JSON as a dict.

Raises:

Type Description
ValueError

object_id is empty, . or ...

RuntimeError

The request failed or the server is still preparing the object.

get_object_once

get_object_once(
    object_id: str,
) -> DrsObject | PendingResolution

Asks once for an object; a pending answer (202 Accepted) is not an error.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required

Returns:

Type Description
DrsObject | PendingResolution

The object, or a PendingResolution if the server is still preparing it.

Raises:

Type Description
ValueError

object_id is empty, . or ...

RuntimeError

The request failed or the response doesn't fit the DRS models.

resolve_object

resolve_object(
    object_id: str,
    timeout: float = 60.0,
    max_attempts: int = 5,
) -> DrsObject

Gets an object, waiting as the server asks while it prepares the object.

The wait blocks without the GIL; Ctrl-C takes effect after it returns.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required
timeout float

The most seconds for all requests and waits.

60.0
max_attempts int

The most requests.

5

Returns:

Type Description
DrsObject

The object.

Raises:

Type Description
ValueError

object_id, timeout or max_attempts is invalid.

RuntimeError

A request failed, or the object wasn't ready within timeout seconds or max_attempts requests.

get_access_url

get_access_url(object_id: str, access_id: str) -> AccessURL

Gets an access URL of an object.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required
access_id str

The access_id of one of the object's access_methods.

required

Returns:

Type Description
AccessURL

The access URL.

Raises:

Type Description
ValueError

An ID is empty, . or ...

RuntimeError

The request failed, the response doesn't fit the DRS models, or the server is still preparing the URL; use get_access_url_once() or resolve_access_url() for that case.

get_access_url_raw

get_access_url_raw(
    object_id: str, access_id: str
) -> _JSONObject

Gets an access URL's complete JSON, without checking it against the DRS models.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required
access_id str

The access_id of one of the object's access_methods.

required

Returns:

Type Description
_JSONObject

The access URL's JSON as a dict.

Raises:

Type Description
ValueError

An ID is empty, . or ...

RuntimeError

The request failed or the server is still preparing the URL.

get_access_url_once

get_access_url_once(
    object_id: str, access_id: str
) -> AccessURL | PendingResolution

Asks once for an access URL; a pending answer is not an error.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required
access_id str

The access_id of one of the object's access_methods.

required

Returns:

Type Description
AccessURL | PendingResolution

The access URL, or a PendingResolution if the server is still preparing it.

Raises:

Type Description
ValueError

An ID is empty, . or ...

RuntimeError

The request failed or the response doesn't fit the DRS models.

resolve_access_url

resolve_access_url(
    object_id: str,
    access_id: str,
    timeout: float = 60.0,
    max_attempts: int = 5,
) -> AccessURL

Gets an access URL, waiting as the server asks while it prepares the URL.

Parameters:

Name Type Description Default
object_id str

The object's ID.

required
access_id str

The access_id of one of the object's access_methods.

required
timeout float

The most seconds for all requests and waits.

60.0
max_attempts int

The most requests.

5

Returns:

Type Description
AccessURL

The access URL.

Raises:

Type Description
ValueError

An ID, timeout or max_attempts is invalid.

RuntimeError

A request failed, or the URL wasn't ready within timeout seconds or max_attempts requests.

get_bulk_objects

get_bulk_objects(
    ids: Iterable[str],
    passports: Iterable[str] | None = None,
    policy: BulkPolicy | None = None,
    timeout: float = 60.0,
) -> BulkReport[DrsObject]

Gets the metadata of several objects with POST objects.

Failures of single IDs and of requests are reported in the outcomes, not raised.

Parameters:

Name Type Description Default
ids Iterable[str]

The object IDs; repeated IDs are asked for once.

required
passports Iterable[str] | None

GA4GH Passport tokens to send in the request body.

None
policy BulkPolicy | None

Limits of the call; by default BulkPolicy().

None
timeout float

The most seconds for the whole call.

60.0

Returns:

Type Description
BulkReport[DrsObject]

A report with one outcome per distinct ID, holding DrsObjects.

Raises:

Type Description
ValueError

An ID, the policy or timeout is invalid. An invalid policy is rejected even without IDs.

get_bulk_objects_raw

get_bulk_objects_raw(
    ids: Iterable[str],
    passports: Iterable[str] | None = None,
    policy: BulkPolicy | None = None,
    timeout: float = 60.0,
) -> BulkReport[_JSONObject]

Like get_bulk_objects(), but each result is the complete JSON dict.

Use it for objects that don't fit the DRS models, such as Gen3 objects with created_time: null.

Parameters:

Name Type Description Default
ids Iterable[str]

The object IDs; repeated IDs are asked for once.

required
passports Iterable[str] | None

GA4GH Passport tokens to send in the request body.

None
policy BulkPolicy | None

Limits of the call; by default BulkPolicy().

None
timeout float

The most seconds for the whole call.

60.0

Returns:

Type Description
BulkReport[_JSONObject]

A report with one outcome per distinct ID, holding dicts.

Raises:

Type Description
ValueError

An ID, the policy or timeout is invalid.

get_bulk_access_urls

get_bulk_access_urls(
    pairs: Mapping[str, str] | Iterable[tuple[str, str]],
    passports: Iterable[str] | None = None,
    policy: BulkPolicy | None = None,
    timeout: float = 60.0,
) -> BulkReport[BulkAccessURL]

Gets access URLs of several objects with POST objects/access.

Failures of single pairs and of requests are reported in the outcomes, not raised.

Parameters:

Name Type Description Default
pairs Mapping[str, str] | Iterable[tuple[str, str]]

Object IDs mapped to access IDs, or (object_id, access_id) pairs; one access ID per object per call.

required
passports Iterable[str] | None

GA4GH Passport tokens to send in the request body.

None
policy BulkPolicy | None

Limits of the call; by default BulkPolicy().

None
timeout float

The most seconds for the whole call.

60.0

Returns:

Type Description
BulkReport[BulkAccessURL]

A report with one outcome per distinct pair, holding BulkAccessURLs.

Raises:

Type Description
ValueError

A pair, the policy or timeout is invalid.

get_bulk_access_urls_raw

get_bulk_access_urls_raw(
    pairs: Mapping[str, str] | Iterable[tuple[str, str]],
    passports: Iterable[str] | None = None,
    policy: BulkPolicy | None = None,
    timeout: float = 60.0,
) -> BulkReport[_JSONObject]

Like get_bulk_access_urls(), but each result is the complete JSON dict.

Parameters:

Name Type Description Default
pairs Mapping[str, str] | Iterable[tuple[str, str]]

Object IDs mapped to access IDs, or (object_id, access_id) pairs; one access ID per object per call.

required
passports Iterable[str] | None

GA4GH Passport tokens to send in the request body.

None
policy BulkPolicy | None

Limits of the call; by default BulkPolicy().

None
timeout float

The most seconds for the whole call.

60.0

Returns:

Type Description
BulkReport[_JSONObject]

A report with one outcome per distinct pair, holding dicts.

Raises:

Type Description
ValueError

A pair, the policy or timeout is invalid.

DrsUri

DrsUri(uri: str)

A hostname-based DRS URI, such as drs://drs.example.org/object-id.

Parses a DRS URI.

Parameters:

Name Type Description Default
uri str

The URI, drs://<host>/<object-id>. The host is a name or an IPv4 address, without a port. IPv6 literals are unsupported.

required

Raises:

Type Description
ValueError

The URI is malformed, has a port or an IPv6 literal, or is a compact identifier (drs://prefix:accession), which is not supported.

authority property

authority: str

The normalized host: lowercase, punycode, or dotted decimal IPv4.

object_id property

object_id: str

The object ID, decoded.

default_api_root

default_api_root() -> str

Gives the API root that the URI implies, https://<authority>/ga4gh/drs/v1.

AccessPlan

How to fetch a DRS object's bytes: an access method, its URL and its headers.

The URL and headers may hold credentials, so repr() shows only the URL's origin.

object_id property

object_id: str

The ID of the object.

method property

method: str

The type of the access method, such as "https" or "s3".

region property

region: str | None

The region of the access method, such as "us-east-1".

url property

url: str

The URL to fetch the object's bytes from.

headers property

headers: list[tuple[str, str]]

(name, value) pairs, unlike the "Name: value" strings of AccessURL.

DrsResolver

DrsResolver()

Turns hostname-based DRS URIs into AccessPlans.

By default, a URI's host is asked anonymously at https://<host>/ga4gh/drs/v1. with_service() maps a host to a Transport with its own API root and settings; settings are never sent to other hosts. It never downloads object bytes.

Builds a resolver that knows no services yet.

with_service

with_service(authority: str, transport: Transport) -> Self

Asks the DRS service of transport for URIs with host authority.

Add services before sharing the resolver between threads.

Parameters:

Name Type Description Default
authority str

The host of the URIs, without a port.

required
transport Transport

A transport with the service's API root and settings.

required

Returns:

Type Description
Self

The resolver itself, for chaining.

Raises:

Type Description
ValueError

authority is not a valid host, has a port or is an IPv6 literal.

RuntimeError

Another thread is planning access with the resolver.

access_plan_once

access_plan_once(
    uri: str,
    protocols: Sequence[str] | None = None,
    regions: Sequence[str] | None = None,
    method_index: int | None = None,
    timeout: float = 60.0,
) -> AccessPlan | PendingResolution

Asks once for the object of uri and, if needed, its access URL.

Parameters:

Name Type Description Default
uri str

A hostname-based DRS URI.

required
protocols Sequence[str] | None

The access method types to choose from, such as ["https", "s3"], in order of preference.

None
regions Sequence[str] | None

The regions to choose from, in order of preference.

None
method_index int | None

The index of the access method to use, instead of choosing.

None
timeout float

The most seconds for all requests.

60.0

Returns:

Type Description
AccessPlan | PendingResolution

The plan, or a PendingResolution if the server is still preparing an answer.

Raises:

Type Description
ValueError

The URI or an argument is invalid.

RuntimeError

A request failed or the object has no usable access method.

access_plan

access_plan(
    uri: str,
    protocols: Sequence[str] | None = None,
    regions: Sequence[str] | None = None,
    method_index: int | None = None,
    timeout: float = 60.0,
    max_attempts: int = 5,
) -> AccessPlan

Plans access to the object of uri, waiting while the server prepares answers.

Reads the object, picks an available access method and reads its access URL if the method has none.

Parameters:

Name Type Description Default
uri str

A hostname-based DRS URI.

required
protocols Sequence[str] | None

The access method types to choose from, in order of preference.

None
regions Sequence[str] | None

The regions to choose from, in order of preference.

None
method_index int | None

The index of the access method to use, instead of choosing.

None
timeout float

The most seconds for all requests and waits.

60.0
max_attempts int

The most requests for each answer.

5

Returns:

Type Description
AccessPlan

The plan.

Raises:

Type Description
ValueError

The URI or an argument is invalid.

RuntimeError

A request failed, an answer wasn't ready in time, or the object has no usable access method.

Transport

Transport(py_config: Configuration)

Sends requests below the configured API root and returns response bodies as text.

Subclass it to add helpers for further endpoints. In all methods, endpoint is relative to the API root, such as tasks/123; encode IDs that you put into it, for example with urllib.parse.quote(task_id, safe=""). params holds query parameters, as a mapping or a JSON object string: values are strings, numbers, booleans or lists of these, a list repeats the parameter, and None or an empty list leaves it out.

Builds a transport with the API root and settings of py_config.

Conflicting credentials raise RuntimeError on the first request.

Parameters:

Name Type Description Default
py_config Configuration

The service's configuration.

required

get

get(endpoint: str, params: _Params | None = None) -> str

Sends a GET request.

Parameters:

Name Type Description Default
endpoint str

The path below the API root.

required
params _Params | None

Query parameters.

None

Returns:

Type Description
str

The response body.

Raises:

Type Description
ValueError

params holds an unsupported value.

RuntimeError

The request failed or the server answered with an error status.

post

post(
    endpoint: str,
    data: Any = None,
    params: _Params | None = None,
) -> str

Sends a POST request with a JSON body.

Parameters:

Name Type Description Default
endpoint str

The path below the API root.

required
data Any

Any object that json.dumps accepts; a str is taken as JSON text, so pass json.dumps(text) to send a JSON string.

None
params _Params | None

Query parameters.

None

Returns:

Type Description
str

The response body.

Raises:

Type Description
ValueError

data or params is invalid.

RuntimeError

The request failed or the server answered with an error status.

put

put(
    endpoint: str, data: Any, params: _Params | None = None
) -> str

Sends a PUT request with a JSON body.

Parameters:

Name Type Description Default
endpoint str

The path below the API root.

required
data Any

Any object that json.dumps accepts; a str is taken as JSON text.

required
params _Params | None

Query parameters.

None

Returns:

Type Description
str

The response body.

Raises:

Type Description
ValueError

data or params is invalid.

RuntimeError

The request failed or the server answered with an error status.

delete

delete(endpoint: str, params: _Params | None = None) -> str

Sends a DELETE request.

Parameters:

Name Type Description Default
endpoint str

The path below the API root.

required
params _Params | None

Query parameters.

None

Returns:

Type Description
str

The response body.

Raises:

Type Description
ValueError

params holds an unsupported value.

RuntimeError

The request failed or the server answered with an error status.

post_multipart

post_multipart(
    endpoint: str,
    fields: list[tuple[str, str]] | None = None,
    files: list[
        tuple[str, str, bytes] | tuple[str, str, bytes, str]
    ]
    | None = None,
    params: _Params | None = None,
) -> str

Sends a multipart/form-data POST request.

Names may repeat, as for WES workflow_attachment. To start a WES run, use WES.run() instead.

Parameters:

Name Type Description Default
endpoint str

The path below the API root.

required
fields list[tuple[str, str]] | None

(name, value) text parts.

None
files list[tuple[str, str, bytes] | tuple[str, str, bytes, str]] | None

(name, filename, content) or (name, filename, content, content_type) file parts, with content as bytes.

None
params _Params | None

Query parameters.

None

Returns:

Type Description
str

The response body.

Raises:

Type Description
TypeError

An argument has the wrong type, such as a dict for fields.

ValueError

A value is invalid.

RuntimeError

The request failed or the server answered with an error status.

ToolVersion

A tool version, as returned by a TRS, with its JSON.

json() and to_dict() return the version as JSON, including fields that the TRS models don't know.

id property

id: str

The version's ID.

url property

url: str

The version's URL in the registry.

name property

name: str | None

The version's name, such as a tag; some registries take it as its ID.

author property

author: list[str] | None

The version's authors.

description property

description: str | None

The version's description (TRS 2.0.2), if it is a string.

is_production property

is_production: bool | None

Whether the version is meant for production use.

images property

images: list[_JSONObject] | None

The container images of the version, as dicts.

descriptor_type property

descriptor_type: list[str] | None

The descriptor types of the version, such as ["CWL"].

descriptor_type_version property

descriptor_type_version: dict[str, list[str]] | None

The language versions of the descriptors, by descriptor type.

containerfile property

containerfile: bool | None

Whether the version has container files, such as a Dockerfile.

meta_version property

meta_version: str | None

The version of the version's metadata in the registry.

verified property

verified: bool | None

Whether the version is verified.

verified_source property

verified_source: list[str] | None

Who verified the version.

signed property

signed: bool | None

Whether the version is signed.

included_apps property

included_apps: list[str] | None

Tools that the version includes, as TRS URIs or URLs.

json

json() -> str

Gives the version as JSON text.

to_dict

to_dict() -> _JSONObject

Gives the version as a new dict.

Tool

A tool with its versions, as returned by a TRS, with its JSON.

json() and to_dict() return the tool as JSON, including fields that the TRS models don't know.

id property

id: str

The tool's ID.

url property

url: str

The tool's URL in the registry.

aliases property

aliases: list[str] | None

Other IDs of the tool, such as DOIs.

organization property

organization: str

The organization that publishes the tool.

name property

name: str | None

The tool's name.

toolclass property

toolclass: _JSONObject | None

The tool class as a dict, such as {"id": "1", "name": "Workflow"}.

description property

description: str | None

The tool's description.

meta_version property

meta_version: str | None

The version of the tool's metadata in the registry.

has_checker property

has_checker: bool | None

Whether the tool has a checker tool.

checker_url property

checker_url: str | None

The URL of the tool's checker tool.

versions property

versions: list[ToolVersion]

The tool's versions.

json

json() -> str

Gives the tool as JSON text.

to_dict

to_dict() -> _JSONObject

Gives the tool as a new dict.

FileWrapper

A descriptor, test or container file: its content, or a url to fetch it from.

For PLAIN_* descriptor types, only content is set. repr() shows the length of content, not the content.

content property

content: str | None

The file's content.

url property

url: str | None

The URL to fetch the file from.

checksum property

checksum: list[_JSONObject] | None

The file's checksums, as dicts with type and checksum.

image_type property

image_type: str | None

The image or descriptor type of the file, such as "Docker" or "CWL".

json

json() -> str

Gives the file as JSON text.

to_dict

to_dict() -> _JSONObject

Gives the file as a new dict.

ToolFile

A file of a tool version, from TRS.list_files().

path property

path: str | None

The file's path, relative to the primary descriptor.

file_type property

file_type: str | None

The file type, such as "PRIMARY_DESCRIPTOR", as the server sent it.

checksum property

checksum: _JSONObject | None

The file's checksum, as a dict with type and checksum.

json

json() -> str

Gives the file as JSON text.

to_dict

to_dict() -> _JSONObject

Gives the file as a new dict.

ToolPage

One page of tools from TRS.list_tools() or TRS.next_tools_page().

The paging properties hold the TRS paging headers, as strs, or None if the server didn't send them; a repeated header gives its first value. len(page) is the number of tools.

tools property

tools: list[Tool]

The tools of the page.

next_page property

next_page: str | None

The URL of the next page (next_page header); None on the last page.

last_page property

last_page: str | None

The URL of the last page (last_page header).

self_link: str | None

The URL of this page (self_link header).

current_offset property

current_offset: str | None

The offset of this page (current_offset header), as the server sent it.

current_limit property

current_limit: str | None

The page size (current_limit header), as the server sent it.

headers

headers() -> dict[str, str]

All response headers by lowercase name; repeated ones joined with ", ".

They can hold cookies, so don't log them.

__len__

__len__() -> int

Gives the number of tools on the page.

TRS

TRS(
    config: Configuration,
    *,
    api_version: str = "auto",
    tag_filter: str = "auto",
    discovery: bool = True,
)

A TRS client (TRS 2.0.1 and 2.0.2).

api_version is "auto", "strict", "2.0.1" or "2.0.2"; tag_filter is "auto", "enabled" or "disabled". discovery=False skips the service info and needs an explicit api_version.

IDs, version IDs and relative paths are sent unchanged, as one percent-encoded URL path segment each, so IDs such as Dockstore's #workflow/github.com/org/repo work. Empty values, . and .. raise ValueError before a request. Failed requests, such as for a missing tool (404), and responses that don't fit the TRS models raise RuntimeError.

Builds a client; reads the service info unless discovery is False.

Parameters:

Name Type Description Default
config Configuration

The service's configuration.

required
api_version str

The TRS version to read responses with: "auto" (the declared version, else 2.0.1), "strict" (only a declared version that the SDK supports), "2.0.1" or "2.0.2".

'auto'
tag_filter str

Whether the server supports the tags filter of list_tools(), beyond what its TRS version says: "auto", "enabled" or "disabled".

'auto'
discovery bool

Whether to read the service info; False needs api_version "2.0.1" or "2.0.2" and doesn't check that the service is a TRS.

True

Raises:

Type Description
ValueError

An option is invalid.

RuntimeError

The service isn't reachable or isn't a TRS, or, with "strict", declares no supported version.

config property

config: Configuration

The client's configuration.

transport property

transport: Transport

A transport with the client's configuration, for further endpoints.

api_version property

api_version: str

The TRS version that responses are read with: "2.0.1" or "2.0.2".

declared_version property

declared_version: str | None

The TRS version that the service info declares, or None without discovery.

version_source property

version_source: str

Where api_version comes from: "declared", "caller" or "baseline".

"baseline" means that the service declared an unknown version, or none, and is read as 2.0.1 without a check that this works.

tag_filter property

tag_filter: str

Whether list_tools(tags=...) may be sent.

It may if this is "specified" (TRS 2.0.2) or "caller_enabled", and may not if it is "not_specified", "caller_disabled" or "unknown".

discovered_service_info property

discovered_service_info: _JSONObject | None

The service info read when the client was built, or None without discovery.

service_info

service_info() -> _JSONObject

Reads the service info again.

Returns:

Type Description
_JSONObject

The service info as a dict.

Raises:

Type Description
RuntimeError

The request failed.

list_tool_classes

list_tool_classes() -> list[_JSONObject]

Lists the registry's tool classes.

Returns:

Type Description
list[_JSONObject]

The tool classes as dicts, such as {"id": "1", "name": "Workflow"}.

Raises:

Type Description
RuntimeError

The request failed.

list_tools

list_tools(
    *,
    id: str | None = None,
    alias: str | None = None,
    tool_class: str | None = None,
    descriptor_type: str | None = None,
    registry: str | None = None,
    organization: str | None = None,
    name: str | None = None,
    toolname: str | None = None,
    description: str | None = None,
    author: str | None = None,
    checker: bool | None = None,
    tags: Sequence[str] | None = None,
    offset: str | None = None,
    limit: int | None = None,
) -> ToolPage

Lists tools, one page at a time; unset filters are not sent.

Requested filters are never dropped silently.

Parameters:

Name Type Description Default
id str | None

A tool ID.

None
alias str | None

An alias of a tool.

None
tool_class str | None

A tool class name, such as "Workflow".

None
descriptor_type str | None

A descriptor type, such as "CWL".

None
registry str | None

The image registry of the tools' containers.

None
organization str | None

The publishing organization.

None
name str | None

The image name.

None
toolname str | None

The tool's name.

None
description str | None

Text in the tool's description.

None
author str | None

An author.

None
checker bool | None

Whether to list checker tools.

None
tags Sequence[str] | None

Tags that the tools have (TRS 2.0.2); sent as one comma-separated value.

None
offset str | None

Where the page starts, as the server's paging gives it.

None
limit int | None

The most tools on the page, between 1 and 2147483647.

None

Returns:

Type Description
ToolPage

The first or requested page.

Raises:

Type Description
ValueError

limit is out of range, descriptor_type is empty, . or .., a tag is empty or contains a comma, or tags is given while tag_filter doesn't allow it.

RuntimeError

The request failed.

next_tools_page

next_tools_page(next_page: str) -> ToolPage

Gets the page at ToolPage.next_page.

Only URLs of the tools endpoint of the client's API root are followed, so credentials never go to another server.

Parameters:

Name Type Description Default
next_page str

The next_page URL of the previous page.

required

Returns:

Type Description
ToolPage

The next page.

Raises:

Type Description
ValueError

next_page is empty.

RuntimeError

The URL is not at the client's tools endpoint (before a request), or the request failed.

get_tool

get_tool(id: str) -> Tool

Gets a tool, with its versions.

Parameters:

Name Type Description Default
id str

The tool's ID.

required

Returns:

Type Description
Tool

The tool.

Raises:

Type Description
ValueError

id is empty, . or ...

RuntimeError

The request failed, for example because the tool doesn't exist.

list_versions

list_versions(id: str) -> list[ToolVersion]

Lists the versions of a tool.

Parameters:

Name Type Description Default
id str

The tool's ID.

required

Returns:

Type Description
list[ToolVersion]

The versions.

Raises:

Type Description
ValueError

id is empty, . or ...

RuntimeError

The request failed.

get_version

get_version(id: str, version_id: str) -> ToolVersion

Gets one version of a tool.

Parameters:

Name Type Description Default
id str

The tool's ID.

required
version_id str

The version's ID; some registries, such as Dockstore, take its name.

required

Returns:

Type Description
ToolVersion

The version.

Raises:

Type Description
ValueError

An ID is empty, . or ...

RuntimeError

The request failed.

get_descriptor

get_descriptor(
    id: str,
    version_id: str,
    descriptor_type: str,
    relative_path: str | None = None,
) -> FileWrapper

Gets the primary descriptor, or the file at relative_path below it.

Parameters:

Name Type Description Default
id str

The tool's ID.

required
version_id str

The version's ID.

required
descriptor_type str

A TRS descriptor type, such as "CWL", "WDL", "NFL", "GALAXY" or "SMK"; or "PLAIN_CWL" and so on for the bare file, which comes as a FileWrapper with only content. Types are sent as given.

required
relative_path str | None

The path of another file, relative to the primary descriptor.

None

Returns:

Type Description
FileWrapper

The file.

Raises:

Type Description
ValueError

An ID, descriptor_type or relative_path is empty, . or ...

RuntimeError

The request failed.

list_tests

list_tests(
    id: str, version_id: str, descriptor_type: str
) -> list[FileWrapper]

Lists the test parameter files of a tool version.

Parameters:

Name Type Description Default
id str

The tool's ID.

required
version_id str

The version's ID.

required
descriptor_type str

A descriptor type, such as "CWL"; for a PLAIN_ type, a bare test file comes as one FileWrapper with only content.

required

Returns:

Type Description
list[FileWrapper]

The test files.

Raises:

Type Description
ValueError

An ID or descriptor_type is empty, . or ...

RuntimeError

The request failed.

list_files

list_files(
    id: str, version_id: str, descriptor_type: str
) -> list[ToolFile]

Lists the files of a tool version, with their paths and file types.

Parameters:

Name Type Description Default
id str

The tool's ID.

required
version_id str

The version's ID.

required
descriptor_type str

A descriptor type without PLAIN_, such as "CWL".

required

Returns:

Type Description
list[ToolFile]

The files.

Raises:

Type Description
ValueError

An ID or descriptor_type is empty, . or ...

RuntimeError

The request failed.

get_files_zip

get_files_zip(
    id: str,
    version_id: str,
    descriptor_type: str,
    limit: int | None = None,
) -> bytes

Downloads the version's files as one ZIP archive of at most limit bytes.

The archive is read into memory; it isn't extracted or checked further.

Parameters:

Name Type Description Default
id str

The tool's ID.

required
version_id str

The version's ID.

required
descriptor_type str

A descriptor type without PLAIN_, such as "CWL".

required
limit int | None

The most bytes to read; None means 64 MiB (67108864 bytes).

None

Returns:

Type Description
bytes

The archive.

Raises:

Type Description
ValueError

An ID or descriptor_type is empty, . or .., or limit is below 1.

RuntimeError

The request failed, the archive is larger than limit, or the response isn't a ZIP archive.

get_containerfiles

get_containerfiles(
    id: str, version_id: str
) -> list[FileWrapper]

Gets the container specifications, such as Dockerfiles, of a tool version.

Parameters:

Name Type Description Default
id str

The tool's ID.

required
version_id str

The version's ID.

required

Returns:

Type Description
list[FileWrapper]

The container files.

Raises:

Type Description
ValueError

An ID is empty, . or ...

RuntimeError

The request failed.

WesState

Bases: str, Enum

The state of a WES run. Members are strings equal to the state's name.

str(), f-strings and json.dumps() give the state's name; WesState("RUNNING") looks a state up by name.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'UNKNOWN'

The state is unknown, or one that WES 1.1 doesn't define.

QUEUED class-attribute instance-attribute

QUEUED = 'QUEUED'

The run is queued.

INITIALIZING class-attribute instance-attribute

INITIALIZING = 'INITIALIZING'

The run is being prepared.

RUNNING class-attribute instance-attribute

RUNNING = 'RUNNING'

The run is running.

PAUSED class-attribute instance-attribute

PAUSED = 'PAUSED'

The run is paused.

COMPLETE class-attribute instance-attribute

COMPLETE = 'COMPLETE'

The run has completed.

EXECUTOR_ERROR class-attribute instance-attribute

EXECUTOR_ERROR = 'EXECUTOR_ERROR'

The run failed because a task failed.

SYSTEM_ERROR class-attribute instance-attribute

SYSTEM_ERROR = 'SYSTEM_ERROR'

The run failed because of a system error.

CANCELED class-attribute instance-attribute

CANCELED = 'CANCELED'

The run was canceled.

CANCELING class-attribute instance-attribute

CANCELING = 'CANCELING'

The run is being canceled.

PREEMPTED class-attribute instance-attribute

PREEMPTED = 'PREEMPTED'

The run was preempted.

__str__

__str__() -> str

Gives the state's name.

__format__

__format__(format_spec: str) -> str

Formats the state's name, as str.__format__ does.

Parameters:

Name Type Description Default
format_spec str

The format specification, such as ">10".

required

Returns:

Type Description
str

The formatted name.

RunRequest

RunRequest(request: RunRequest | Mapping[str, Any] | str)

A WES run request: a workflow to run, with its parameters.

Keeps the request's full JSON, including fields that the WES models don't know. WES.run() sends those fields as further form parts: strings as they are, other values as JSON. Requests can be pickled and copied.

Builds a request and checks it against the WES models.

Parameters:

Name Type Description Default
request RunRequest | Mapping[str, Any] | str

A RunRequest, a dict (or other JSON-serialisable mapping), or JSON text. Unlike for WES.run(), a str is JSON, not a path.

required

Raises:

Type Description
ValueError

The request doesn't fit the WES models.

from_dict classmethod

from_dict(request: Mapping[str, Any]) -> Self

Builds a request from a dict, as cls(request).

Parameters:

Name Type Description Default
request Mapping[str, Any]

The request's JSON as a mapping.

required

Returns:

Type Description
Self

The request.

Raises:

Type Description
ValueError

The request doesn't fit the WES models.

from_json classmethod

from_json(text: str) -> Self

Builds a request from JSON text.

Parameters:

Name Type Description Default
text str

The request as a JSON object.

required

Returns:

Type Description
Self

The request.

Raises:

Type Description
ValueError

text isn't JSON, or the request doesn't fit the WES models.

from_file classmethod

from_file(path: str | PathLike[str]) -> Self

Reads a request from a JSON file.

Parameters:

Name Type Description Default
path str | PathLike[str]

The file's path.

required

Returns:

Type Description
Self

The request.

Raises:

Type Description
OSError

The file can't be read, for example FileNotFoundError.

ValueError

The file isn't JSON, or the request doesn't fit the WES models.

workflow_type property

workflow_type: str

The workflow language, such as "CWL".

workflow_type_version property

workflow_type_version: str

The version of the workflow language, such as "v1.2".

workflow_url property

workflow_url: str

The workflow's URL, or the filename of an attachment.

workflow_params property

workflow_params: _JSONObject | None

The workflow's input parameters.

tags property

tags: dict[str, str] | None

Key-value tags of the run.

workflow_engine property

workflow_engine: str | None

The workflow engine to use.

workflow_engine_version property

workflow_engine_version: str | None

The version of the workflow engine.

workflow_engine_parameters property

workflow_engine_parameters: dict[str, str] | None

Parameters for the workflow engine.

json

json() -> str

Gives the request as JSON text, as given or received.

to_dict

to_dict() -> _JSONObject

Gives the request as a new dict, as given or received.

RunLog

A run's details, with its request, state, logs and outputs, as returned by the server.

Keeps the run's full JSON, including fields that the WES models don't know.

run_id property

run_id: str | None

The run's ID.

request property

request: RunRequest | None

The run's request, or None if it is missing or doesn't fit the WES models.

state property

state: WesState

The run's state; UNKNOWN if it has none or one that WES 1.1 doesn't define.

run_log property

run_log: _JSONObject | None

The log of the workflow engine, such as its command, times and exit code.

task_logs_url property

task_logs_url: str | None

The URL of the run's task list (WES 1.1).

task_logs property

task_logs: list[_JSONObject] | None

The run's task logs, as dicts; WES 1.1 lists them with Run.tasks().

outputs property

outputs: Any

The run's outputs, as JSON values.

json

json() -> str

Gives the run as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the run as a new dict, as received.

RunSummary

A run in the list of WES.list().

run_id property

run_id: str

The run's ID.

state property

state: WesState

The run's state; UNKNOWN if it has none or one that WES 1.1 doesn't define.

start_time property

start_time: str | None

When the run started, as an RFC 3339 timestamp.

end_time property

end_time: str | None

When the run ended, as an RFC 3339 timestamp.

tags property

tags: dict[str, str] | None

Key-value tags of the run.

json

json() -> str

Gives the run as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the run as a new dict, as received.

RunListResponse

One page of runs from WES.list().

runs property

runs: list[RunSummary]

The runs of the page.

next_page_token property

next_page_token: str | None

The token of the next page, for WES.list(page_token=...).

json

json() -> str

Gives the response as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the response as a new dict, as received.

TaskLog

A task of a run, from Run.tasks() or Run.task() (WES 1.1).

id property

id: str

The task's ID.

name property

name: str

The task's name.

cmd property

cmd: list[str] | None

The command that the task ran.

start_time property

start_time: str | None

When the task started, as an RFC 3339 timestamp.

end_time property

end_time: str | None

When the task ended, as an RFC 3339 timestamp.

stdout property

stdout: str | None

The URL of the task's standard output.

stderr property

stderr: str | None

The URL of the task's standard error.

exit_code property

exit_code: int | None

The task's exit code.

system_logs property

system_logs: list[str] | None

System messages about the task, such as errors.

tes_uri property

tes_uri: str | None

The URI of the task in a TES, if it ran on one.

json

json() -> str

Gives the task as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the task as a new dict, as received.

TaskListResponse

One page of tasks from Run.tasks().

task_logs property

task_logs: list[TaskLog]

The tasks of the page.

next_page_token property

next_page_token: str | None

The token of the next page, for Run.tasks(page_token=...).

json

json() -> str

Gives the response as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the response as a new dict, as received.

Run

Run(id: str, transport: Transport)

A WES run on the server, addressed by its ID.

Addresses an existing run; sends no request.

Parameters:

Name Type Description Default
id str

The run's ID.

required
transport Transport

A transport with the WES service's configuration, such as wes.transport.

required

Raises:

Type Description
ValueError

id is empty.

id property

id: str

The run's ID.

transport property

transport: Transport

A transport with the run's configuration, for further endpoints.

status

status() -> WesState

Gets the run's current state.

Returns:

Type Description
WesState

The state.

Raises:

Type Description
RuntimeError

The request failed.

cancel

cancel() -> None

Asks the server to cancel the run.

Raises:

Type Description
RuntimeError

The request failed.

log

log() -> RunLog

Gets the run's details, with its request, state, logs and outputs.

Returns:

Type Description
RunLog

The run's details.

Raises:

Type Description
RuntimeError

The request failed or the response doesn't fit the WES models.

tasks

tasks(
    page_size: int | None = None,
    page_token: str | None = None,
) -> TaskListResponse

Lists the run's tasks, one page at a time (WES 1.1).

Parameters:

Name Type Description Default
page_size int | None

The most tasks on the page.

None
page_token str | None

The next_page_token of the previous page.

None

Returns:

Type Description
TaskListResponse

The page.

Raises:

Type Description
RuntimeError

The request failed or the response doesn't fit the WES models.

task

task(task_id: str) -> TaskLog

Gets one of the run's tasks (WES 1.1).

Parameters:

Name Type Description Default
task_id str

The task's ID.

required

Returns:

Type Description
TaskLog

The task.

Raises:

Type Description
ValueError

task_id is empty, . or ...

RuntimeError

The request failed or the response doesn't fit the WES models.

WES

WES(config: Configuration)

A WES client (WES 1.1). Subclass it to add endpoints, using self.transport.

Builds a client and checks the service.

Parameters:

Name Type Description Default
config Configuration

The service's configuration.

required

Raises:

Type Description
RuntimeError

The service isn't reachable or isn't a WES.

config property

config: Configuration

The client's configuration.

transport property

transport: Transport

A transport with the client's configuration, for further endpoints.

run

run(
    request: RunRequest
    | Mapping[str, Any]
    | str
    | PathLike[str],
    attachments: _Attachments | None = None,
) -> Run

Starts a workflow run.

workflow_type, workflow_type_version, workflow_url and workflow_params are required. Request fields that the WES models don't know are sent as further form parts. The upload and the answer must finish within the submission time limit. If starting fails after submission, the server may have started the run; don't retry automatically.

Parameters:

Name Type Description Default
request RunRequest | Mapping[str, Any] | str | PathLike[str]

A RunRequest, a dict (or other mapping), or the path of a JSON file as str or os.PathLike. A str is always a path; pass JSON text as RunRequest.from_json(text).

required
attachments _Attachments | None

Filenames (relative paths with /, such as tools/echo.cwl) mapped to contents as bytes or to file paths (os.PathLike), which are streamed; or a list of (filename, content) pairs.

None

Returns:

Type Description
Run

The run.

Raises:

Type Description
ValueError

The request or an attachment name is invalid, a str starts with { (after whitespace), or the request has a workflow_attachment field (pass files with attachments).

OSError

A request or attachment file can't be read.

RuntimeError

The request failed or the response doesn't fit the WES models.

list

list(
    page_size: int | None = None,
    page_token: str | None = None,
) -> RunListResponse

Lists runs, one page at a time.

A bare array of runs, as WES 0.2.0 servers send it, becomes a page without a token.

Parameters:

Name Type Description Default
page_size int | None

The most runs on the page.

None
page_token str | None

The next_page_token of the previous page.

None

Returns:

Type Description
RunListResponse

The page.

Raises:

Type Description
RuntimeError

The request failed or the response doesn't fit the WES models.

get

get(id: str) -> RunLog

Gets a run's details, like Run(id, wes.transport).log().

Parameters:

Name Type Description Default
id str

The run's ID.

required

Returns:

Type Description
RunLog

The run's details.

Raises:

Type Description
ValueError

id is empty, . or ...

RuntimeError

The request failed or the response doesn't fit the WES models.

TesState

Bases: str, Enum

The state of a TES task. Members are strings equal to the state's name.

str(), f-strings and json.dumps() give the state's name; TesState("RUNNING") looks a state up by name.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'UNKNOWN'

The state is unknown, or one that TES 1.1 doesn't define.

QUEUED class-attribute instance-attribute

QUEUED = 'QUEUED'

The task is queued.

INITIALIZING class-attribute instance-attribute

INITIALIZING = 'INITIALIZING'

The task is being prepared, for example its inputs downloaded.

RUNNING class-attribute instance-attribute

RUNNING = 'RUNNING'

The task is running.

PAUSED class-attribute instance-attribute

PAUSED = 'PAUSED'

The task is paused.

COMPLETE class-attribute instance-attribute

COMPLETE = 'COMPLETE'

The task has completed.

EXECUTOR_ERROR class-attribute instance-attribute

EXECUTOR_ERROR = 'EXECUTOR_ERROR'

The task failed because an executor failed.

SYSTEM_ERROR class-attribute instance-attribute

SYSTEM_ERROR = 'SYSTEM_ERROR'

The task failed because of a system error.

CANCELED class-attribute instance-attribute

CANCELED = 'CANCELED'

The task was canceled.

PREEMPTED class-attribute instance-attribute

PREEMPTED = 'PREEMPTED'

The task was preempted.

CANCELING class-attribute instance-attribute

CANCELING = 'CANCELING'

The task is being canceled.

__str__

__str__() -> str

Gives the state's name.

__format__

__format__(format_spec: str) -> str

Formats the state's name, as str.__format__ does.

Parameters:

Name Type Description Default
format_spec str

The format specification, such as ">10".

required

Returns:

Type Description
str

The formatted name.

TesTask

TesTask(task: TesTask | Mapping[str, Any] | str)

A TES task: one to create, or one as returned by the server.

Keeps the task's full JSON, including fields that the TES models don't know. Missing fields are None. Nested values, such as executors, come as dicts and lists. Tasks can be pickled and copied.

Builds a task and checks it against the TES models.

Parameters:

Name Type Description Default
task TesTask | Mapping[str, Any] | str

A TesTask, a dict (or other JSON-serialisable mapping), or JSON text. Unlike for TES.create(), a str is JSON, not a path.

required

Raises:

Type Description
ValueError

The task doesn't fit the TES models.

from_dict classmethod

from_dict(task: Mapping[str, Any]) -> Self

Builds a task from a dict, as cls(task).

Parameters:

Name Type Description Default
task Mapping[str, Any]

The task's JSON as a mapping.

required

Returns:

Type Description
Self

The task.

Raises:

Type Description
ValueError

The task doesn't fit the TES models.

from_json classmethod

from_json(text: str) -> Self

Builds a task from JSON text.

Parameters:

Name Type Description Default
text str

The task as a JSON object.

required

Returns:

Type Description
Self

The task.

Raises:

Type Description
ValueError

text isn't JSON, or the task doesn't fit the TES models.

from_file classmethod

from_file(path: str | PathLike[str]) -> Self

Reads a task from a JSON file.

Parameters:

Name Type Description Default
path str | PathLike[str]

The file's path.

required

Returns:

Type Description
Self

The task.

Raises:

Type Description
OSError

The file can't be read, for example FileNotFoundError.

ValueError

The file isn't JSON, or the task doesn't fit the TES models.

id property

id: str | None

The task's ID; None for a task that isn't created yet.

state property

state: TesState

The task's state; UNKNOWN if it has none or one that TES 1.1 doesn't define.

status property

status: TesState

Same as state.

name property

name: str | None

The task's name.

description property

description: str | None

The task's description.

creation_time property

creation_time: str | None

When the task was created, as an RFC 3339 timestamp.

inputs property

inputs: list[_JSONObject] | None

The files to put into the task's containers.

outputs property

outputs: list[_JSONObject] | None

The files to keep from the task's containers.

resources property

resources: _JSONObject | None

The resources that the task asks for, such as CPU cores and RAM.

executors property

executors: list[_JSONObject] | None

The commands to run, in order, each with its container image.

volumes property

volumes: list[str] | None

Paths that the executors share.

tags property

tags: dict[str, str] | None

Key-value tags of the task.

logs property

logs: list[_JSONObject] | None

The task's logs, one per attempt (in the BASIC and FULL views).

json

json() -> str

Gives the task as JSON text, as given or received; keys may come in another order.

to_dict

to_dict() -> _JSONObject

Gives the task as a new dict, as given or received.

PyTesTask module-attribute

PyTesTask = TesTask

Previous name of TesTask.

Task

Task(id: str, transport: Transport)

A TES task on the server, addressed by its ID.

Addresses an existing task; sends no request.

Parameters:

Name Type Description Default
id str

The task's ID.

required
transport Transport

A transport with the TES service's configuration, such as tes.transport.

required

id property

id: str

The task's ID.

transport property

transport: Transport

A transport with the task's configuration, for further endpoints.

status

status() -> TesState

Gets the task's current state.

Returns:

Type Description
TesState

The state.

Raises:

Type Description
RuntimeError

The request failed or the response has no state.

cancel

cancel() -> None

Asks the server to cancel the task.

Raises:

Type Description
RuntimeError

The request failed.

wait

wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 1.0,
    max_interval: float | None = None,
    view: None = None,
) -> TesState
wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 1.0,
    max_interval: float | None = None,
    view: str,
) -> TesTask
wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 1.0,
    max_interval: float | None = None,
    view: str | None = None,
) -> TesState | TesTask

Waits until the task ends; gives its final state, or the task in view.

A task ends in COMPLETE, EXECUTOR_ERROR, SYSTEM_ERROR, CANCELED or PREEMPTED. Polls ask for the minimal view and start poll_interval seconds apart; the interval doubles after each poll. The wait releases the GIL; in the main thread, Ctrl-C stops it with KeyboardInterrupt. Nothing here cancels the task: call cancel() for that.

Parameters:

Name Type Description Default
timeout float | None

The most seconds for the whole wait; None waits as long as it takes.

None
poll_interval float

The seconds between the first polls.

1.0
max_interval float | None

The longest interval between polls; by default 10 seconds, or poll_interval if that's longer.

None
view str | None

"MINIMAL", "BASIC" or "FULL", in any case, to get the ended task in that view instead of its state.

None

Returns:

Type Description
TesState | TesTask

The final state, or the ended task in view.

Raises:

Type Description
WaitTimeoutError

The time ran out; the task goes on running.

RuntimeError

A poll failed; polls are not retried.

ValueError

An argument is invalid, such as a negative timeout, a poll_interval of 0 or a max_interval below poll_interval.

Example
try:
    state = task.wait(timeout=3600)
except WaitTimeoutError as error:
    print(error.id, "still", error.last_state)

WaitTimeoutError

Bases: TimeoutError

Raised when Task.wait() or AsyncTask.wait() runs out of time.

id is the task's ID, and last_state its last polled state as a TesState, or None if no poll succeeded. The wait doesn't cancel the task, which may still be running (if the time ran out while getting an ended task in a view, last_state is its final state). Both are None on an error raised by other code.

id instance-attribute

id: str | None

The task's ID; None on an error raised by other code.

last_state instance-attribute

last_state: TesState | None

The task's last polled state, or None if no poll succeeded.

ListTasksParams

ListTasksParams(
    name_prefix: str | None = None,
    state: TesState | str | None = None,
    tag_key: list[str] | None = None,
    tag_value: list[str] | None = None,
    page_size: int | None = None,
    page_token: str | None = None,
    view: str | None = None,
)

Filters and paging for TES.list().

Builds the filters; unset ones are not sent.

Parameters:

Name Type Description Default
name_prefix str | None

The start of the tasks' names.

None
state TesState | str | None

A TesState, or a TES state name in any case.

None
tag_key list[str] | None

Tag keys that the tasks have.

None
tag_value list[str] | None

Values of the tags in tag_key, paired by position.

None
page_size int | None

The most tasks on the page.

None
page_token str | None

The next_page_token of the previous page.

None
view str | None

"MINIMAL", "BASIC" or "FULL", in any case.

None

Raises:

Type Description
ValueError

state or view is not a TES state or view.

name_prefix property

name_prefix: str | None

The start of the tasks' names.

state property

state: TesState | None

The state filter.

tag_key property

tag_key: list[str] | None

Tag keys that the tasks have.

tag_value property

tag_value: list[str] | None

Values of the tags in tag_key, paired by position.

page_size property

page_size: int | None

The most tasks on the page.

page_token property

page_token: str | None

The token of the page to get.

view property

view: str | None

The view of the tasks, in uppercase.

ListTasksResponse

One page of tasks from TES.list().

tasks property

tasks: list[TesTask]

The tasks of the page.

next_page_token property

next_page_token: str | None

The token of the next page, for ListTasksParams(page_token=...).

json

json() -> str

Gives the response as JSON text, as received.

to_dict

to_dict() -> _JSONObject

Gives the response as a new dict, as received.

TES

TES(config: Configuration)

A TES client. Subclass it to add endpoints, using self.transport.

Builds a client and checks the service.

Parameters:

Name Type Description Default
config Configuration

The service's configuration.

required

Raises:

Type Description
RuntimeError

The service isn't reachable or isn't a TES.

config property

config: Configuration

The client's configuration.

transport property

transport: Transport

A transport with the client's configuration, for further endpoints.

create

create(
    task: TesTask | Mapping[str, Any] | str | PathLike[str],
) -> Task

Creates a task.

The task's JSON is sent as given, including fields that the TES models don't know. If creation fails after submission, the server may have created the task; don't retry automatically.

Parameters:

Name Type Description Default
task TesTask | Mapping[str, Any] | str | PathLike[str]

A TesTask, a dict (or other mapping), or the path of a JSON file as str or os.PathLike. A str is always a path; pass JSON text as TesTask.from_json(text).

required

Returns:

Type Description
Task

The created task.

Raises:

Type Description
ValueError

The task is invalid, or a str starts with {.

OSError

The task file can't be read, for example FileNotFoundError.

RuntimeError

The request failed or the response doesn't fit the TES models.

get

get(view: str, id: str) -> TesTask

Gets a task.

Parameters:

Name Type Description Default
view str

"MINIMAL", "BASIC" or "FULL", in any case.

required
id str

The task's ID.

required

Returns:

Type Description
TesTask

The task in that view.

Raises:

Type Description
ValueError

view is not a TES view.

RuntimeError

The request failed or the response doesn't fit the TES models.

list

list(
    params: ListTasksParams | None = None,
) -> ListTasksResponse

Lists tasks, one page at a time.

Parameters:

Name Type Description Default
params ListTasksParams | None

Filters and paging; by default, the first page of all tasks.

None

Returns:

Type Description
ListTasksResponse

The page.

Raises:

Type Description
RuntimeError

The request failed or the response doesn't fit the TES models.

AsyncTES

AsyncTES(config: Configuration)

A TES client for asyncio: create, get and list return awaitables.

The methods return asyncio.Futures of the running event loop, so they must be called from it. AsyncTES(config) doesn't contact the server; await AsyncTES.connect(config) first checks that config points at a TES service; otherwise the first call does. Invalid arguments raise when a method is called; failed requests raise RuntimeError when awaited. Cancelling an awaitable drops its request.

Builds a client; sends no request.

Parameters:

Name Type Description Default
config Configuration

The service's configuration.

required

connect classmethod

connect(
    config: Configuration, *args: Any, **kwargs: Any
) -> asyncio.Future[Self]

Builds cls(config, *args, **kwargs); gives it once it has checked the service.

Parameters:

Name Type Description Default
config Configuration

The service's configuration.

required
*args Any

Further arguments of a subclass's constructor.

()
**kwargs Any

Further keyword arguments of a subclass's constructor.

{}

Returns:

Type Description
Future[Self]

A future of the client; it raises RuntimeError if the service isn't

Future[Self]

reachable or isn't a TES.

config property

config: Configuration

The client's configuration.

transport property

transport: Transport

A transport with the client's configuration; its methods are synchronous.

create

create(
    task: TesTask | Mapping[str, Any] | str | PathLike[str],
) -> asyncio.Future[AsyncTask]

Creates a task; takes the same task as TES.create().

Parameters:

Name Type Description Default
task TesTask | Mapping[str, Any] | str | PathLike[str]

A TesTask, a dict (or other mapping), or the path of a JSON file.

required

Returns:

Type Description
Future[AsyncTask]

A future of the created task.

Raises:

Type Description
ValueError

The task is invalid.

OSError

The task file can't be read.

get

get(view: str, id: str) -> asyncio.Future[TesTask]

Gets a task.

Parameters:

Name Type Description Default
view str

"MINIMAL", "BASIC" or "FULL", in any case.

required
id str

The task's ID.

required

Returns:

Type Description
Future[TesTask]

A future of the task in that view.

Raises:

Type Description
ValueError

view is not a TES view.

list

list(
    params: ListTasksParams | None = None,
) -> asyncio.Future[ListTasksResponse]

Lists tasks, one page at a time.

Parameters:

Name Type Description Default
params ListTasksParams | None

Filters and paging; by default, the first page of all tasks.

None

Returns:

Type Description
Future[ListTasksResponse]

A future of the page.

AsyncTask

AsyncTask(id: str, transport: Transport)

A TES task on the server, addressed by its ID, for asyncio.

Addresses an existing task; sends no request.

Parameters:

Name Type Description Default
id str

The task's ID.

required
transport Transport

A transport with the TES service's configuration.

required

id property

id: str

The task's ID.

transport property

transport: Transport

A transport with the task's configuration, for further endpoints.

status

status() -> asyncio.Future[TesState]

Gets the task's current state.

Returns:

Type Description
Future[TesState]

A future of the state; it raises RuntimeError if the request fails.

cancel

cancel() -> asyncio.Future[None]

Asks the server to cancel the task.

Returns:

Type Description
Future[None]

A future of None; it raises RuntimeError if the request fails.

wait

wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 1.0,
    max_interval: float | None = None,
    view: None = None,
) -> asyncio.Future[TesState]
wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 1.0,
    max_interval: float | None = None,
    view: str,
) -> asyncio.Future[TesTask]
wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 1.0,
    max_interval: float | None = None,
    view: str | None = None,
) -> asyncio.Future[TesState] | asyncio.Future[TesTask]

Waits until the task ends, like Task.wait().

Cancelling the awaiting coroutine stops polling; it doesn't cancel the task. Between polls, the wait holds no call thread, so sleeping waits do not delay other async calls.

Parameters:

Name Type Description Default
timeout float | None

The most seconds for the whole wait; None waits as long as it takes.

None
poll_interval float

The seconds between the first polls.

1.0
max_interval float | None

The longest interval between polls; by default 10 seconds, or poll_interval if that's longer.

None
view str | None

"MINIMAL", "BASIC" or "FULL", to get the ended task in that view.

None

Returns:

Type Description
Future[TesState] | Future[TesTask]

A future of the final state, or of the ended task in view. It raises

Future[TesState] | Future[TesTask]

WaitTimeoutError when the time runs out and RuntimeError if a poll fails.

Raises:

Type Description
ValueError

An argument is invalid, when the method is called.