google.gax

Google API Extensions

Functions

retryable(a_func, retry_options, **kwargs) Creates a function equivalent to a_func, but that retries on certain exceptions.

Classes

BackoffSettings Parameters to the exponential backoff algorithm for retrying.
BundleDescriptor Describes the structure of bundled call.
BundleOptions Holds values used to configure bundling.
CallOptions([timeout, retry, page_token, ...]) Encapsulates the overridable settings for a particular API call.
PageDescriptor Describes the structure of a page-streaming call.
PageIterator(api_call, page_descriptor, ...) An iterator over the pages of a page streaming API call.
ResourceIterator(page_iterator) An iterator over resources of the page iterator.
RetryOptions Per-call configurable settings for retrying upon transient failure.
StatusCode Mirrors grpc_status_code in the gRPC Core.

Exceptions

GaxError(msg[, cause]) Common base class for exceptions raised by GAX.
RpcError Raised by the gRPC library to indicate non-OK-status RPC termination.
class BackoffSettings[source]

Parameters to the exponential backoff algorithm for retrying.

initial_retry_delay_millis

the initial delay time, in milliseconds, between the completion of the first failed request and the initiation of the first retrying request.

retry_delay_multiplier

the multiplier by which to increase the delay time between the completion of failed requests, and the initiation of the subsequent retrying request.

max_retry_delay_millis

the maximum delay time, in milliseconds, between requests. When this value is reached, retry_delay_multiplier will no longer be used to increase delay time.

initial_rpc_timeout_millis

the initial timeout parameter to the request.

rpc_timeout_multiplier

the multiplier by which to increase the timeout parameter between failed requests.

max_rpc_timeout_millis

the maximum timeout parameter, in milliseconds, for a request. When this value is reached, rpc_timeout_multiplier will no longer be used to increase the timeout.

total_timeout_millis

the total time, in milliseconds, starting from when the initial request is sent, after which an error will be returned, regardless of the retrying attempts made meanwhile.

Create new instance of BackoffSettings(initial_retry_delay_millis, retry_delay_multiplier, max_retry_delay_millis, initial_rpc_timeout_millis, rpc_timeout_multiplier, max_rpc_timeout_millis, total_timeout_millis)

class BundleDescriptor[source]

Describes the structure of bundled call.

request_discriminator_fields may include ‘.’ as a separator, which is used to indicate object traversal. This allows fields in nested objects to be used to determine what requests to bundle.

bundled_field

the repeated field in the request message that will have its elements aggregated by bundling

request_discriminator_fields

a list of fields in the target request message class that are used to determine which messages should be bundled together.

subresponse_field

an optional field, when present it indicates the field in the response message that should be used to demultiplex the response into multiple response messages.

class BundleOptions[source]

Holds values used to configure bundling.

The xxx_threshold attributes are used to configure when the bundled request should be made.

element_count_threshold

the bundled request will be sent once the count of outstanding elements in the repeated field reaches this value.

element_count_limit

represents a hard limit on the number of elements in the repeated field of the bundle; if adding a request to a bundle would exceed this value, the bundle is sent and the new request is added to a fresh bundle. It is invalid for a single request to exceed this limit.

request_byte_threshold

the bundled request will be sent once the count of bytes in the request reaches this value. Note that this value is pessimistically approximated by summing the bytesizes of the elements in the repeated field, and therefore may be an under-approximation.

request_byte_limit

represents a hard limit on the size of the bundled request; if adding a request to a bundle would exceed this value, the bundle is sent and the new request is added to a fresh bundle. It is invalid for a single request to exceed this limit. Note that this value is pessimistically approximated by summing the bytesizes of the elements in the repeated field, with a buffer applied to correspond to the resulting under-approximation.

delay_threshold

the bundled request will be sent this amount of time after the first element in the bundle was added to it.

Invokes the base constructor with default values.

The default values are zero for all attributes and it’s necessary to specify at least one valid threshold value during construction.

Parameters:
  • element_count_threshold (int) – the bundled request will be sent once the count of outstanding elements in the repeated field reaches this value.
  • element_count_limit (int) – represents a hard limit on the number of elements in the repeated field of the bundle; if adding a request to a bundle would exceed this value, the bundle is sent and the new request is added to a fresh bundle. It is invalid for a single request to exceed this limit.
  • request_byte_threshold (int) – the bundled request will be sent once the count of bytes in the request reaches this value. Note that this value is pessimistically approximated by summing the bytesizes of the elements in the repeated field, with a buffer applied to compensate for the corresponding under-approximation.
  • request_byte_limit (int) – represents a hard limit on the size of the bundled request; if adding a request to a bundle would exceed this value, the bundle is sent and the new request is added to a fresh bundle. It is invalid for a single request to exceed this limit. Note that this value is pessimistically approximated by summing the bytesizes of the elements in the repeated field, with a buffer applied to correspond to the resulting under-approximation.
  • delay_threshold (int) – the bundled request will be sent this amount of time after the first element in the bundle was added to it.
Returns:

the constructed object.

Return type:

BundleOptions

static __new__(element_count_threshold=0, element_count_limit=0, request_byte_threshold=0, request_byte_limit=0, delay_threshold=0)[source]

Invokes the base constructor with default values.

The default values are zero for all attributes and it’s necessary to specify at least one valid threshold value during construction.

Parameters:
  • element_count_threshold (int) – the bundled request will be sent once the count of outstanding elements in the repeated field reaches this value.
  • element_count_limit (int) – represents a hard limit on the number of elements in the repeated field of the bundle; if adding a request to a bundle would exceed this value, the bundle is sent and the new request is added to a fresh bundle. It is invalid for a single request to exceed this limit.
  • request_byte_threshold (int) – the bundled request will be sent once the count of bytes in the request reaches this value. Note that this value is pessimistically approximated by summing the bytesizes of the elements in the repeated field, with a buffer applied to compensate for the corresponding under-approximation.
  • request_byte_limit (int) – represents a hard limit on the size of the bundled request; if adding a request to a bundle would exceed this value, the bundle is sent and the new request is added to a fresh bundle. It is invalid for a single request to exceed this limit. Note that this value is pessimistically approximated by summing the bytesizes of the elements in the repeated field, with a buffer applied to correspond to the resulting under-approximation.
  • delay_threshold (int) – the bundled request will be sent this amount of time after the first element in the bundle was added to it.
Returns:

the constructed object.

Return type:

BundleOptions

class CallOptions(timeout=<object object>, retry=<object object>, page_token=<object object>, is_bundling=False, **kwargs)[source]

Encapsulates the overridable settings for a particular API call.

CallOptions is an optional arg for all GAX API calls. It is used to configure the settings of a specific API call.

When provided, its values override the GAX service defaults for that particular call.

Example

>>> # change an api call's timeout
>>> o1 = CallOptions(timeout=30)  # make the timeout 30 seconds
>>>
>>> # set page streaming to be per-page on a call where it is
>>> # normally per-resource
>>> o2 = CallOptions(page_token=INITIAL_PAGE)
>>>
>>> # disable retrying on an api call that normally retries
>>> o3 = CallOptions(retry=None)
>>>
>>> # enable bundling on a call that supports it
>>> o4 = CallOptions(is_bundling=True)
Parameters:
  • timeout (int) – The client-side timeout for non-retrying API calls.
  • retry (RetryOptions) – determines whether and how to retry on transient errors. When set to None, the call will not retry.
  • page_token (str) – If set and the call is configured for page streaming, page streaming is performed per-page, starting with this page_token. Use INITIAL_PAGE for the first request. If unset and the call is configured for page streaming, page streaming is performed per-resource.
  • is_bundling (bool) – If set and the call is configured for bundling, bundling is performed. Bundling is always disabled by default.
  • kwargs – Additional arguments passed through to the API call.
Raises:

ValueError – if incompatible options are specified.

INITIAL_PAGE = <object object>

A placeholder for the page token passed into an initial paginated request.

OPTION_INHERIT = <object object>

Global constant.

If a CallOptions field is set to OPTION_INHERIT, the call to which that CallOptions belongs will attempt to inherit that field from its default settings.

class PageDescriptor[source]

Describes the structure of a page-streaming call.

Create new instance of PageDescriptor(request_page_token_field, response_page_token_field, resource_field)

class PageIterator(api_call, page_descriptor, page_token, request, **kwargs)[source]

An iterator over the pages of a page streaming API call.

Provides access to the individual pages of the call, as well as the page token.

response

The full response message for the call most recently made, or None if a call has not yet been made.

page_token

The page token to be passed in the request for the next call to be made.

Parameters:
  • api_call (Callable [ req, resp ]) – an API call that is page streaming.
  • page_descriptor (PageDescriptor) – indicates the structure of page streaming to be performed.
  • page_token (str) – The page token to be passed to API call request. If no page token has yet been acquired, this field should be set to INITIAL_PAGE.
  • request (object) – The request to be passed to the API call. The page token field of the request is overwritten by the page_token passed to the constructor, unless page_token is INITIAL_PAGE.
  • kwargs – Arbitrary keyword arguments to be passed to the API call.
__next__()[source]

Retrieves the next page.

next()[source]

For Python 2.7 compatibility; see __next__.

class ResourceIterator(page_iterator)[source]

An iterator over resources of the page iterator.

Constructor.

Parameters:page_iterator (PageIterator) – the base iterator of getting pages.
__next__()[source]

Retrieves the next resource.

next()[source]

For Python 2.7 compatibility; see __next__.

class RetryOptions[source]

Per-call configurable settings for retrying upon transient failure.

retry_codes

list[string] – a list of Google API canonical error codes upon which a retry should be attempted.

backoff_settings

BackoffSettings – configures the retry exponential backoff algorithm.

Create new instance of RetryOptions(retry_codes, backoff_settings)