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
ServiceType
¶
A built-in section of the configuration file, for Configuration.from_file().
Other sections are named by a str.
AAI
instance-attribute
¶
The AAI section (authentication and authorization infrastructure).
Configuration
¶
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
|
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
set_base_path
¶
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
|
|
get_base_path
¶
Gives the API root.
Returns:
| Type | Description |
|---|---|
str
|
The API root as a URL string. |
set_basic_auth
¶
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
¶
Sets one OAuth bearer token for clients built from this configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token
|
str
|
The access token, without the |
required |
set_bearer_access_token
¶
Sets one generic bearer token for clients built from this configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token
|
str
|
The token, without the |
required |
get_extra
¶
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 |
_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
|
None
|
submission
|
float | None
|
|
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
A limit is not a valid number of seconds. |
get_timeouts
¶
Gives the time limits of requests.
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
The limits in seconds, by name: |
dict[str, float]
|
|
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 |
required |
audience
|
str | None
|
The value passed to |
None
|
Raises:
| Type | Description |
|---|---|
TypeError
|
|
ValueError
|
|
from_file
¶
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 |
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
¶
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
¶
Reads the service info.
Returns:
| Type | Description |
|---|---|
str
|
The service info as formatted text ( |
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.
updated_time
property
¶
When the object was last updated, as an RFC 3339 timestamp.
checksums
property
¶
The object's checksums, as dicts with type and checksum.
access_methods
property
¶
The ways to fetch the object's bytes, as dicts with type and access_id or
access_url; None for a bundle.
contents
property
¶
For a bundle, the objects that it contains, as dicts.
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.
headers
property
¶
The headers to send with a request to url, as "Name: value" strings.
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.
headers
property
¶
The headers to send with a request to url, as "Name: value" strings.
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.
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
|
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
|
0.2
|
max_delay
|
float
|
The longest delay between retries, in seconds. |
10.0
|
with_service_info
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
BulkPolicy
|
A new policy, with the same limits if the service info has no |
BulkPolicy
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
|
advertised_limit
property
¶
The service's most IDs per request, if known; it lowers chunk_size.
max_requests
property
¶
The most requests in one call, retries and splits included.
max_split_depth
property
¶
How often a request that the server rejects as too large (413) is halved.
max_attempts
property
¶
The most attempts per request, for network errors, 429 and 503.
initial_delay
property
¶
The delay before the first retry, in seconds; it doubles up to max_delay.
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.
access_id
property
¶
The access ID of the pair, for get_bulk_access_urls(); else None.
resolved
property
¶
The results that the server returned for the ID; one, if all went well.
failure_codes
property
¶
The HTTP status codes that the server gave for the ID, such as 404.
pending
property
¶
The pending state, if the server is still preparing the answer.
errors
property
¶
What went wrong otherwise, such as a missing or duplicate answer.
is_success
property
¶
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.
DRS
¶
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. |
transport
property
¶
A transport with the client's configuration, for further endpoints.
get_object
¶
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
|
|
RuntimeError
|
The request failed, the response doesn't fit the DRS models, or
the server is still preparing the object; use |
get_object_raw
¶
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
The request failed or the server is still preparing the object. |
get_object_once
¶
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
The request failed or the response doesn't fit the DRS models. |
resolve_object
¶
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
|
|
RuntimeError
|
A request failed, or the object wasn't ready within |
get_access_url
¶
Gets an access URL of an object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
object_id
|
str
|
The object's ID. |
required |
access_id
|
str
|
The |
required |
Returns:
| Type | Description |
|---|---|
AccessURL
|
The access URL. |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID is empty, |
RuntimeError
|
The request failed, the response doesn't fit the DRS models, or
the server is still preparing the URL; use |
get_access_url_raw
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
_JSONObject
|
The access URL's JSON as a |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID is empty, |
RuntimeError
|
The request failed or the server is still preparing the URL. |
get_access_url_once
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
AccessURL | PendingResolution
|
The access URL, or a |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID is empty, |
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 |
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, |
RuntimeError
|
A request failed, or the URL wasn't ready within |
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 |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID, the policy or |
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 |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID, the policy or |
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 |
required |
passports
|
Iterable[str] | None
|
GA4GH Passport tokens to send in the request body. |
None
|
policy
|
BulkPolicy | None
|
Limits of the call; by default |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
A pair, the policy or |
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 |
required |
passports
|
Iterable[str] | None
|
GA4GH Passport tokens to send in the request body. |
None
|
policy
|
BulkPolicy | None
|
Limits of the call; by default |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
A pair, the policy or |
DrsUri
¶
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, |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
The URI is malformed, has a port or an IPv6 literal,
or is a compact identifier ( |
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.
headers
property
¶
(name, value) pairs, unlike the "Name: value" strings of AccessURL.
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
¶
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
|
|
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 |
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 |
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
¶
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
¶
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
|
|
RuntimeError
|
The request failed or the server answered with an error status. |
post
¶
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 |
None
|
params
|
_Params | None
|
Query parameters. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The response body. |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
The request failed or the server answered with an error status. |
put
¶
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 |
required |
params
|
_Params | None
|
Query parameters. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The response body. |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
The request failed or the server answered with an error status. |
delete
¶
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
|
|
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
|
|
None
|
files
|
list[tuple[str, str, bytes] | tuple[str, str, bytes, str]] | None
|
|
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 |
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.
name
property
¶
The version's name, such as a tag; some registries take it as its ID.
description
property
¶
The version's description (TRS 2.0.2), if it is a string.
is_production
property
¶
Whether the version is meant for production use.
descriptor_type
property
¶
The descriptor types of the version, such as ["CWL"].
descriptor_type_version
property
¶
The language versions of the descriptors, by descriptor type.
containerfile
property
¶
Whether the version has container files, such as a Dockerfile.
meta_version
property
¶
The version of the version's metadata in the registry.
included_apps
property
¶
Tools that the version includes, as TRS URIs or URLs.
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.
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.
ToolFile
¶
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.
next_page
property
¶
The URL of the next page (next_page header); None on the last page.
current_offset
property
¶
The offset of this page (current_offset header), as the server sent it.
current_limit
property
¶
The page size (current_limit header), as the server sent it.
headers
¶
All response headers by lowercase name; repeated ones joined with ", ".
They can hold cookies, so don't log them.
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'
|
tag_filter
|
str
|
Whether the server supports the |
'auto'
|
discovery
|
bool
|
Whether to read the service info; |
True
|
Raises:
| Type | Description |
|---|---|
ValueError
|
An option is invalid. |
RuntimeError
|
The service isn't reachable or isn't a TRS, or, with |
transport
property
¶
A transport with the client's configuration, for further endpoints.
api_version
property
¶
The TRS version that responses are read with: "2.0.1" or "2.0.2".
declared_version
property
¶
The TRS version that the service info declares, or None without discovery.
version_source
property
¶
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
¶
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
¶
The service info read when the client was built, or None without discovery.
service_info
¶
Reads the service info again.
Returns:
| Type | Description |
|---|---|
_JSONObject
|
The service info as a |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
The request failed. |
list_tool_classes
¶
Lists the registry's tool classes.
Returns:
| Type | Description |
|---|---|
list[_JSONObject]
|
The tool classes as |
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 |
None
|
descriptor_type
|
str | None
|
A descriptor type, such as |
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
|
|
RuntimeError
|
The request failed. |
next_tools_page
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
ToolPage
|
The next page. |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
The URL is not at the client's tools endpoint (before a request), or the request failed. |
get_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
|
|
RuntimeError
|
The request failed, for example because the tool doesn't exist. |
list_versions
¶
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
|
|
RuntimeError
|
The request failed. |
get_version
¶
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, |
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 |
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, |
RuntimeError
|
The request failed. |
list_tests
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
list[FileWrapper]
|
The test files. |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID or |
RuntimeError
|
The request failed. |
list_files
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
list[ToolFile]
|
The files. |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID or |
RuntimeError
|
The request failed. |
get_files_zip
¶
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 |
required |
limit
|
int | None
|
The most bytes to read; |
None
|
Returns:
| Type | Description |
|---|---|
bytes
|
The archive. |
Raises:
| Type | Description |
|---|---|
ValueError
|
An ID or |
RuntimeError
|
The request failed, the archive is larger than |
get_containerfiles
¶
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, |
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
¶
The state is unknown, or one that WES 1.1 doesn't define.
INITIALIZING
class-attribute
instance-attribute
¶
The run is being prepared.
EXECUTOR_ERROR
class-attribute
instance-attribute
¶
The run failed because a task failed.
SYSTEM_ERROR
class-attribute
instance-attribute
¶
The run failed because of a system error.
__format__
¶
Formats the state's name, as str.__format__ does.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
format_spec
|
str
|
The format specification, such as |
required |
Returns:
| Type | Description |
|---|---|
str
|
The formatted name. |
RunRequest
¶
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 |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
The request doesn't fit the WES models. |
from_dict
classmethod
¶
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
¶
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
|
|
from_file
classmethod
¶
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 |
ValueError
|
The file isn't JSON, or the request doesn't fit the WES models. |
workflow_type_version
property
¶
The version of the workflow language, such as "v1.2".
workflow_engine_version
property
¶
The version of the workflow engine.
workflow_engine_parameters
property
¶
Parameters for the workflow engine.
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.
request
property
¶
The run's request, or None if it is missing or doesn't fit the WES models.
state
property
¶
The run's state; UNKNOWN if it has none or one that WES 1.1 doesn't define.
run_log
property
¶
The log of the workflow engine, such as its command, times and exit code.
task_logs
property
¶
The run's task logs, as dicts; WES 1.1 lists them with Run.tasks().
RunSummary
¶
A run in the list of WES.list().
state
property
¶
The run's state; UNKNOWN if it has none or one that WES 1.1 doesn't define.
RunListResponse
¶
One page of runs from WES.list().
next_page_token
property
¶
The token of the next page, for WES.list(page_token=...).
TaskLog
¶
A task of a run, from Run.tasks() or Run.task() (WES 1.1).
system_logs
property
¶
System messages about the task, such as errors.
TaskListResponse
¶
One page of tasks from Run.tasks().
next_page_token
property
¶
The token of the next page, for Run.tasks(page_token=...).
Run
¶
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
|
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
transport
property
¶
A transport with the run's configuration, for further endpoints.
status
¶
Gets the run's current state.
Returns:
| Type | Description |
|---|---|
WesState
|
The state. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
The request failed. |
cancel
¶
Asks the server to cancel the run.
Raises:
| Type | Description |
|---|---|
RuntimeError
|
The request failed. |
log
¶
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
¶
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 |
None
|
Returns:
| Type | Description |
|---|---|
TaskListResponse
|
The page. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
The request failed or the response doesn't fit the WES models. |
task
¶
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
|
|
RuntimeError
|
The request failed or the response doesn't fit the WES models. |
WES
¶
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. |
transport
property
¶
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 |
required |
attachments
|
_Attachments | None
|
Filenames (relative paths with |
None
|
Returns:
| Type | Description |
|---|---|
Run
|
The run. |
Raises:
| Type | Description |
|---|---|
ValueError
|
The request or an attachment name is invalid, a |
OSError
|
A request or attachment file can't be read. |
RuntimeError
|
The request failed or the response doesn't fit the WES models. |
list
¶
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 |
None
|
Returns:
| Type | Description |
|---|---|
RunListResponse
|
The page. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
The request failed or the response doesn't fit the WES models. |
get
¶
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
|
|
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
¶
The state is unknown, or one that TES 1.1 doesn't define.
INITIALIZING
class-attribute
instance-attribute
¶
The task is being prepared, for example its inputs downloaded.
EXECUTOR_ERROR
class-attribute
instance-attribute
¶
The task failed because an executor failed.
SYSTEM_ERROR
class-attribute
instance-attribute
¶
The task failed because of a system error.
__format__
¶
Formats the state's name, as str.__format__ does.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
format_spec
|
str
|
The format specification, such as |
required |
Returns:
| Type | Description |
|---|---|
str
|
The formatted name. |
TesTask
¶
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 |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
The task doesn't fit the TES models. |
from_dict
classmethod
¶
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
¶
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
|
|
from_file
classmethod
¶
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 |
ValueError
|
The file isn't JSON, or the task doesn't fit the TES models. |
state
property
¶
The task's state; UNKNOWN if it has none or one that TES 1.1 doesn't define.
creation_time
property
¶
When the task was created, as an RFC 3339 timestamp.
resources
property
¶
The resources that the task asks for, such as CPU cores and RAM.
executors
property
¶
The commands to run, in order, each with its container image.
logs
property
¶
The task's logs, one per attempt (in the BASIC and FULL views).
json
¶
Gives the task as JSON text, as given or received; keys may come in another order.
Task
¶
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
|
required |
transport
property
¶
A transport with the task's configuration, for further endpoints.
status
¶
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
¶
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: 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
|
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
|
None
|
view
|
str | None
|
|
None
|
Returns:
| Type | Description |
|---|---|
TesState | TesTask
|
The final state, or the ended task in |
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 |
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.
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 |
None
|
tag_key
|
list[str] | None
|
Tag keys that the tasks have. |
None
|
tag_value
|
list[str] | None
|
Values of the tags in |
None
|
page_size
|
int | None
|
The most tasks on the page. |
None
|
page_token
|
str | None
|
The |
None
|
view
|
str | None
|
|
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
|
ListTasksResponse
¶
One page of tasks from TES.list().
next_page_token
property
¶
The token of the next page, for ListTasksParams(page_token=...).
TES
¶
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. |
transport
property
¶
A transport with the client's configuration, for further endpoints.
create
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
Task
|
The created task. |
Raises:
| Type | Description |
|---|---|
ValueError
|
The task is invalid, or a |
OSError
|
The task file can't be read, for example |
RuntimeError
|
The request failed or the response doesn't fit the TES models. |
get
¶
Gets a task.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
view
|
str
|
|
required |
id
|
str
|
The task's ID. |
required |
Returns:
| Type | Description |
|---|---|
TesTask
|
The task in that view. |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
The request failed or the response doesn't fit the TES models. |
list
¶
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
¶
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
¶
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 |
Future[Self]
|
reachable or isn't a TES. |
transport
property
¶
A transport with the client's configuration; its methods are synchronous.
create
¶
Creates a task; takes the same task as TES.create().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
task
|
TesTask | Mapping[str, Any] | str | PathLike[str]
|
A |
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
¶
Gets a task.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
view
|
str
|
|
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
|
|
list
¶
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
¶
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 |
transport
property
¶
A transport with the task's configuration, for further endpoints.
status
¶
Gets the task's current state.
Returns:
| Type | Description |
|---|---|
Future[TesState]
|
A future of the state; it raises |
cancel
¶
Asks the server to cancel the task.
Returns:
| Type | Description |
|---|---|
Future[None]
|
A future of |
wait
¶
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
|
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
|
None
|
view
|
str | None
|
|
None
|
Returns:
| Type | Description |
|---|---|
Future[TesState] | Future[TesTask]
|
A future of the final state, or of the ended task in |
Future[TesState] | Future[TesTask]
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
An argument is invalid, when the method is called. |