google.gax¶
Google API Extensions
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. |
-
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: -
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:
-
-
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, unlesspage_token
isINITIAL_PAGE
. - kwargs – Arbitrary keyword arguments to be passed to the API call.
-
-
class
ResourceIterator
(page_iterator)[source]¶ An iterator over resources of the page iterator.
Constructor.
Parameters: page_iterator (PageIterator) – the base iterator of getting pages.
-
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)
-