Transport Layer¶

The transport consists of a transport object ( RequestsTransport), but also tooling for handling retries. It is possible to either register custom retry check methods, or to override the Transport used by a client in order to customize this behavior.

Transport¶

class globus_sdk.transport.RequestsTransport(verify_ssl=None, http_timeout=None)[source]¶

The RequestsTransport handles HTTP request sending and retries.

It receives raw request information from a client class, and then performs the following steps - encode the data in a prepared request - repeatedly send the request until no retry is requested by the configured hooks - return the last response or reraise the last exception

If the maximum number of retries is reached, the final response or exception will be returned or raised.

Parameters:

verify_ssl (bool | str | pathlib.Path | None) – Explicitly enable or disable SSL verification, or configure the path to a CA certificate bundle to use for SSL verification
http_timeout (float | None) – Explicitly set an HTTP timeout value in seconds. This parameter defaults to 60s but can be set via the GLOBUS_SDK_HTTP_TIMEOUT environment variable. Any value set via this parameter takes precedence over the environment variable.

Variables:

headers (dict[str, str]) – The headers which are sent on every request. These may be augmented by the transport when sending requests.

DEFAULT_MAX_RETRIES = 5¶: default maximum number of retries

encoders: dict[str, RequestEncoder] = {'form': <globus_sdk.transport.encoders.FormRequestEncoder object>, 'json': <globus_sdk.transport.encoders.JSONRequestEncoder object>, 'text': <globus_sdk.transport.encoders.RequestEncoder object>}¶: the encoders are a mapping of encoding names to encoder objects

close()[source]¶

Closes all resources owned by the transport, primarily the underlying network session.

tune(*, verify_ssl=None, http_timeout=None)[source]¶

Temporarily adjust some of the request sending settings of the transport. This method works as a context manager, and will reset settings to their original values after it exits.

Parameters:

verify_ssl (bool | str | Path | None) – Explicitly enable or disable SSL verification, or configure the path to a CA certificate bundle to use for SSL verification
http_timeout (float | None) – Explicitly set an HTTP timeout value in seconds

Return type:

Iterator[None]

Example Usage

This can be used with any client class to temporarily set values in the context of one or more HTTP requests. To increase the HTTP request timeout from the default of 60 to 120 seconds,

>>> client = ...  # any client class
>>> with client.transport.tune(http_timeout=120):
>>>     foo = client.get_foo()

See also: RetryConfig.tune().

request(method, url, *, caller_info, query_params=None, data=None, headers=None, encoding=None, allow_redirects=True, stream=False)[source]¶

Send an HTTP request

Parameters:

url (str) – URL for the request
method (str) – HTTP request method, as an all caps string
caller_info (RequestCallerInfo) – Contextual information about the caller of the request, including the authorizer and retry configuration.
query_params (dict[str, Any] | None) – Parameters to be encoded as a query string
headers (dict[str, str] | None) – HTTP headers to add to the request
data (dict[str, Any] | list[Any] | str | bytes | None) – Data to send as the request body. May pass through encoding.
encoding (str | None) – A way to encode request data. “json”, “form”, and “text” are all valid values. Custom encodings can be used only if they are registered with the transport. By default, strings get “text” behavior and all other objects get “json”.
allow_redirects (bool) – Follow Location headers on redirect response automatically. Defaults to True
stream (bool) – Do not immediately download the response content. Defaults to False

Returns:

requests.Response object

Return type:

Response

RequestsTransport objects include an attribute, globus_client_info which provides the X-Globus-Client-Info header which is sent to Globus services. It is an instance of GlobusClientInfo:

class globus_sdk.transport.GlobusClientInfo(*, update_callback=None)[source]¶

An implementation of X-Globus-Client-Info as an object. This header encodes a mapping of multiple products to versions and potentially other information.

Values can be added to a clientinfo object via the add() method.

The object always initializes itself to start with

product=python-sdk,version=…

using the current package version information.

X-Globus-Client-Info Specification

Header Name: X-Globus-Client-Info

Header Value:

A semicolon (;) separated list of client information.
Client information is a comma-separated list of = delimited key-value pairs. Well-known values for client-information are:
- product: A unique identifier of the product.
- version: Relevant version information for the product.
Based on the above, the characters ;,= should be considered reserved and should NOT be included in client information values to ensure proper parsing.

Example Headers

X-Globus-Client-Info: product=python-sdk,version=3.32.1
X-Globus-Client-Info: product=python-sdk,version=3.32.1;product=cli,version=4.0.0a1

Note

The GlobusClientInfo object is not guaranteed to reject all invalid usages. For example, product is required to be unique per header, and users are expected to enforce this in their usage.

Parameters:: update_callback (t.Callable[[GlobusClientInfo], None] | None) – A callback function to be invoked each time the content of the GlobusClientInfo changes via add() or clear().

format()[source]¶

Format as a header value.

Return type:: str

add(value)[source]¶

Add an item to the clientinfo. The item is either already formatted as a string, or is a dict containing values to format.

Parameters:: value (str | dict[str, str]) – The element to add to the client-info. If it is a dict, it may not contain reserved characters in any keys or values. If it is a string, it cannot contain the ; separator.

clear()[source]¶

Empty the list of info strings and trigger the update callback.

Retries¶

These are the components used by the RequestsTransport to implement retry logic.

class globus_sdk.transport.RetryContext(attempt, *, caller_info, response=None, exception=None)[source]¶

The RetryContext is an object passed to retry checks in order to determine whether or not a request should be retried. The context is constructed after each request, regardless of success or failure.

If an exception was raised, the context will contain that exception object. Otherwise, the context will contain a response object. Exactly one of response or exception will be present.

Parameters:

attempt (int) – The request attempt number, starting at 0.
caller_info (RequestCallerInfo) – Contextual information about the caller, including authorizer
response (requests.Response | None) – The response on a successful request
exception (Exception | None) – The error raised when trying to send the request

class globus_sdk.transport.RetryCheckResult(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

do_retry = 1¶: yes, retry the request

do_not_retry = 2¶: no, do not retry the request

no_decision = 3¶: “I don’t know”, ask other checks for an answer

globus_sdk.transport.RetryCheck¶: The type for a retry check, a callable which takes a RetryContext and returns a RetryCheckResult. Equivalent to Callable[[globus_sdk.transport.RetryContext], globus_sdk.transport.RetryCheckResult]

class globus_sdk.transport.RetryCheckRunner(checks)[source]¶

A RetryCheckRunner is an object responsible for running retry checks over the lifetime of a request. Unlike the checks or the retry context, the runner persists between retries. It can therefore implement special logic for checks like “only try this check once”.

Its primary responsibility is to answer the question “should_retry(context)?” with a boolean.

It takes as its input a list of checks. Checks may be paired with flags to indicate their configuration options. When not paired with flags, the flags are taken to be “NONE”.

Supported flags:

RUN_ONCE: The check will run at most once for a given request. Once it has run, it is recorded as “has_run” and will not be run again on that request.

class globus_sdk.transport.RetryCheckFlags(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

NONE = 1¶: no flags (default)

RUN_ONCE = 2¶: only run this check once per request

@globus_sdk.transport.set_retry_check_flags[source]¶

A decorator for setting retry check flags on a retry check function. Usage:

>>> @set_retry_check_flags(RetryCheckFlags.RUN_ONCE)
>>> def foo(ctx): ...

Parameters:: flag (RetryCheckFlags) – The flag to set on the check
Return type:: Callable[[C], C]

Data Encoders¶

class globus_sdk.transport.RequestEncoder[source]¶

A RequestEncoder takes input parameters and outputs a requests.Requests object.

The default encoder requires that the data is text and is a no-op. It can also be referred to as the "text" encoder.

class globus_sdk.transport.JSONRequestEncoder[source]¶: This encoder prepares the data as JSON. It also ensures that content-type is set, so that APIs requiring a content-type of “application/json” are able to read the data.

class globus_sdk.transport.FormRequestEncoder[source]¶: This encoder formats data as a form-encoded body. It requires that the input data is a dict – any other datatype will result in errors.