google.gax.bundling¶
Provides behavior that supports request bundling.
compute_bundle_id()
is used generate ids linking API requests to the
appropriate bundles.
Event
is the result of scheduling a bundled api call. It is a
decorated threading.Event
; its wait
and is_set
methods
are used wait for the bundle request to complete or determine if it has
been completed respectively.
Task
manages the sending of all the requests in a specific bundle.
Executor
has a schedule
method that is used add bundled api calls
to a new or existing Task
.
Functions
compute_bundle_id (obj, discriminator_fields) |
Computes a bundle id from the discriminator fields of obj. |
Classes
Event () |
Wraps a threading.Event, adding, canceller and result attributes. |
Executor (options) |
Organizes bundling for an api service that requires it. |
Task (api_call, bundle_id, bundled_field, …) |
Coordinates the execution of a single bundle. |
-
class
Event
[source]¶ Wraps a threading.Event, adding, canceller and result attributes.
Constructor.
-
clear
()[source]¶ Calls
clear
on the decoratedthreading.Event
.Also resets the result if one has been set.
-
is_set
()[source]¶ Calls
is_set
on the decoratedthreading.Event
.
-
set
()[source]¶ Calls
set
on the decoratedthreading.Event
.
-
wait
(timeout=None)[source]¶ Calls
wait
on the decoratedthreading.Event
.
-
-
class
Executor
(options)[source]¶ Organizes bundling for an api service that requires it.
Constructor.
Parameters: options (gax.BundleOptions) – configures strategy this instance uses when executing bundled functions. -
schedule
(api_call, bundle_id, bundle_desc, bundling_request, kwargs=None)[source]¶ Schedules bundle_desc of bundling_request as part of bundle_id.
The returned value an
Event
that- has a
result
attribute that will eventually be set to the result the api call - will be used to wait for the response
- holds the canceller function for canceling this part of the bundle
Parameters: - api_call (callable[[object], object]) – the scheduled API call.
- bundle_id (str) – identifies the bundle on which the API call should be made.
- bundle_desc (gax.BundleDescriptor) – describes the structure of the bundled call.
- bundling_request (object) – the request instance to use in the API call.
- kwargs (dict) – optional, the keyword arguments passed to the API call.
Returns: the scheduled event.
Return type: - has a
-
-
TIMER_FACTORY
¶ A class with an interface similar to threading.Timer.
Defaults to threading.Timer. This makes it easy to plug-in alternate timer implementations.
alias of
Timer
-
class
Task
(api_call, bundle_id, bundled_field, bundling_request, kwargs, subresponse_field=None)[source]¶ Coordinates the execution of a single bundle.
Parameters: - api_call (
Callable
[Sequence
[object
] ,object
]) – the func that is this tasks’s API call. - bundle_id (
Tuple
[str
]) – the id of this bundle. - bundled_field (str) – the field used to create the bundled request.
- bundling_request (object) – the request to pass as the arg to api_call.
- kwargs (dict) – keyword arguments passed to api_call.
- subresponse_field (str) – optional field used to demultiplex responses.
-
element_count
¶ The number of bundled elements in the repeated field.
-
extend
(elts)[source]¶ Adds elts to the tasks.
Parameters: elts (Sequence) – a iterable of elements that can be appended to the task’s bundle_field. Returns: an event that can be used to wait on the response. Return type: Event
-
request_bytesize
¶ The size of in bytes of the bundled field elements.
- api_call (
-
compute_bundle_id
(obj, discriminator_fields)[source]¶ Computes a bundle id from the discriminator fields of obj.
discriminator_fields may include ‘.’ as a separator, which is used to indicate object traversal. This is meant to allow fields in the computed bundle_id.
the id is a tuple computed by going through the discriminator fields in order and obtaining the str(value) object field (or nested object field)
if any discriminator field cannot be found, ValueError is raised.
Parameters: Returns: computed as described above.
Return type: Raises: AttributeError
– if any discriminator fields attribute does not exist.