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: Optional[bool] = None, http_timeout: Optional[float] = None, retry_backoff: Callable[[globus_sdk.transport.retry.RetryContext], float] = <function _exponential_backoff>, retry_checks: Optional[List[Callable[[globus_sdk.transport.retry.RetryContext], globus_sdk.transport.retry.RetryCheckResult]]] = None, max_sleep: int = 10, max_retries: Optional[int] = 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 - return the last response or reraise the last exception

Retry checks are registered as hooks on the Transport. Additional hooks can be passed to the constructor via retry_checks. Or hooks can be added to an existing transport via a decorator.

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

Parameters
  • verify_ssl (bool, optional) – Explicitly enable or disable SSL verification. This parameter defaults to True, but can be set via the GLOBUS_SDK_VERIFY_SSL environment variable. Any non-None setting via this parameter takes precedence over the environment variable.

  • http_timeout (int, optional) – 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.

  • retry_backoff (callable, optional) – A function which determines how long to sleep between calls based on the RetryContext. Defaults to exponential backoff with jitter based on the context attempt number.

  • retry_checks (list of callable, optional) – A list of initial retry checks. Any hooks registered, including the default hooks, will run after these checks.

  • max_sleep (int, optional) – The maximum sleep time between retries (in seconds). If the computed sleep time or the backoff requested by a retry check exceeds this value, this amount of time will be used instead

  • max_retries (int, optional) – The maximum number of retries allowed by this transport

request(method: str, url: str, query_params: Optional[Dict[str, Any]] = None, data: Optional[dict] = None, headers: Optional[dict] = None, encoding: Optional[str] = None, authorizer: Optional[globus_sdk.authorizers.base.GlobusAuthorizer] = None) requests.models.Response[source]

Send an HTTP request

Parameters
  • url – URL for the request

  • method (str) – HTTP request method, as an all caps string

  • query_params (dict, optional) – Parameters to be encoded as a query string

  • headers (dict) – HTTP headers to add to the request

  • data (dict or str) – Data to send as the request body. May pass through encoding.

  • encoding (str) – 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”.

Returns

requests.Response object

Retries

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

class globus_sdk.transport.RetryContext(attempt: int, *, authorizer: Optional[globus_sdk.authorizers.base.GlobusAuthorizer] = None, response: Optional[requests.models.Response] = None, exception: Optional[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.

  • response (requests.Response) – The response on a successful request

  • exception (Exception) – The error raised when trying to send the request

  • authorizer (GlobusAuthorizer) – The authorizer object from the client making the request

class globus_sdk.transport.RetryCheckResult(value)[source]

An enumeration.

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: List[Callable[[globus_sdk.transport.retry.RetryContext], globus_sdk.transport.retry.RetryCheckResult]])[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)[source]

An enumeration.

NONE = 1

no flags (default)

RUN_ONCE = 2

only run this check once per request

@globus_sdk.transport.set_retry_check_flags(flag: globus_sdk.transport.retry.RetryCheckFlags) Callable[[Callable], Callable][source]

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

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

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.