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.

cancel()[source]

Invokes the cancellation function provided on construction.

clear()[source]

Calls clear on the decorated threading.Event.

Also resets the result if one has been set.

is_set()[source]

Calls is_set on the decorated threading.Event.

set()[source]

Calls set on the decorated threading.Event.

wait(timeout=None)[source]

Calls wait on the decorated threading.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:

Event
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.

run()[source]

Call the task’s func.

The task’s func will be called with the bundling requests func

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:
  • obj (object) – an object.
  • discriminator_fields (Sequence [ str ]) – a list of discriminator fields in the order to be to be used in the id.
Returns:

computed as described above.
Return type:

Tuple [ str ]
Raises:

AttributeError – if any discriminator fields attribute does not exist.