grpc.framework.alpha package¶

Submodules¶

grpc.framework.alpha.exceptions module¶

Exceptions raised by GRPC.

Only GRPC should instantiate and raise these exceptions.

exception grpc.framework.alpha.exceptions.CancellationError[source]¶

Bases: grpc.framework.alpha.exceptions.RpcError

Indicates that an RPC has been cancelled.

exception grpc.framework.alpha.exceptions.ExpirationError[source]¶

Bases: grpc.framework.alpha.exceptions.RpcError

Indicates that an RPC has expired (“timed out”).

exception grpc.framework.alpha.exceptions.RpcError[source]¶

Bases: exceptions.Exception

Common super type for all exceptions raised by GRPC.

grpc.framework.alpha.interfaces module¶

Interfaces of GRPC.

class grpc.framework.alpha.interfaces.Abortion[source]¶

Bases: enum.Enum

Categories of RPC abortion.

class grpc.framework.alpha.interfaces.CancellableIterator[source]¶

Bases: object

Implements the Iterator protocol and affords a cancel method.

__iter__()[source]¶

Returns the self object in accordance with the Iterator protocol.

cancel()[source]¶

Requests cancellation of whatever computation underlies this iterator.

next()[source]¶

Returns a value or raises StopIteration per the Iterator protocol.

class grpc.framework.alpha.interfaces.Cardinality[source]¶

Bases: enum.Enum

Constants for the four cardinalities of RPC.

class grpc.framework.alpha.interfaces.RpcContext[source]¶

Bases: object

Provides RPC-related information and action.

add_abortion_callback(abortion_callback)[source]¶

Registers a callback to be called if the RPC is aborted. :param abortion_callback: A callable to be called and passed an Abortion value

in the event of RPC abortion.

is_active()[source]¶

Describes whether the RPC is active or has terminated.

time_remaining()[source]¶

Describes the length of allowed time remaining for the RPC. :returns: A nonnegative float indicating the length of allowed time in seconds

remaining for the RPC to complete before it is considered to have timed out.

class grpc.framework.alpha.interfaces.RpcMethodDescription[source]¶

Bases: object

A type for the common aspects of RPC method descriptions.

cardinality()[source]¶

Identifies the cardinality of this RpcMethodDescription.

Returns:	A Cardinality value identifying whether or not this RpcMethodDescription is request-unary or request-streaming and whether or not it is response-unary or response-streaming.

class grpc.framework.alpha.interfaces.RpcMethodInvocationDescription[source]¶

Bases: grpc.framework.alpha.interfaces.RpcMethodDescription

Invocation-side description of an RPC method.

deserialize_response(serialized_response)[source]¶

Deserializes a response value.

Parameters:	serialized_response – A bytestring that is the serialization of a response value appropriate for the RPC method described by this RpcMethodInvocationDescription.
Returns:	A response value corresponding to the given bytestring.

serialize_request(request)[source]¶

Serializes a request value.

Parameters:	request – A request value appropriate for the RPC method described by this RpcMethodInvocationDescription.
Returns:	The serialization of the given request value as a bytestring.

class grpc.framework.alpha.interfaces.RpcMethodServiceDescription[source]¶

Bases: grpc.framework.alpha.interfaces.RpcMethodDescription

Service-side description of an RPC method.

deserialize_request(serialized_request)[source]¶

Deserializes a request value.

Parameters:	serialized_request – A bytestring that is the serialization of a request value appropriate for the RPC method described by this RpcMethodServiceDescription.
Returns:	A request value corresponding to the given bytestring.

serialize_response(response)[source]¶

Serializes a response value.

Parameters:	response – A response value appropriate for the RPC method described by this RpcMethodServiceDescription.
Returns:	The serialization of the given response value as a bytestring.

service_stream_stream(request_iterator, context)[source]¶

Carries out this RPC.

This method may only be called if the cardinality of this RpcMethodServiceDescription is Cardinality.STREAM_STREAM.

Parameters:	request_iterator – An iterator of request values appropriate for the RPC method described by this RpcMethodServiceDescription. context – An RpcContext object for the RPC.
Yields:	Zero or more response values appropriate for the RPC method described by this RpcMethodServiceDescription.

service_stream_unary(request_iterator, context)[source]¶

Carries out this RPC.

This method may only be called if the cardinality of this RpcMethodServiceDescription is Cardinality.STREAM_UNARY.

Parameters:	request_iterator – An iterator of request values appropriate for the RPC method described by this RpcMethodServiceDescription. context – An RpcContext object for the RPC.
Returns:	A response value appropriate for the RPC method described by this RpcMethodServiceDescription.

service_unary_stream(request, context)[source]¶

Carries out this RPC.

This method may only be called if the cardinality of this RpcMethodServiceDescription is Cardinality.UNARY_STREAM.

Parameters:	request – A request value appropriate for the RPC method described by this RpcMethodServiceDescription. context – An RpcContext object for the RPC.
Yields:	Zero or more response values appropriate for the RPC method described by this RpcMethodServiceDescription.

service_unary_unary(request, context)[source]¶

Carries out this RPC.

This method may only be called if the cardinality of this RpcMethodServiceDescription is Cardinality.UNARY_UNARY.

Parameters:	request – A request value appropriate for the RPC method described by this RpcMethodServiceDescription. context – An RpcContext object for the RPC.
Returns:	A response value appropriate for the RPC method described by this RpcMethodServiceDescription.

class grpc.framework.alpha.interfaces.Server[source]¶

Bases: grpc.framework.foundation.activated.Activated

A GRPC Server.

port()[source]¶

Reports the port on which the server is serving.

This method may only be called while the server is activated.

Returns:	The port on which the server is serving.

class grpc.framework.alpha.interfaces.StreamUnarySyncAsync[source]¶

Bases: object

Affords invoking a stream-unary RPC synchronously or asynchronously. Values implementing this interface are directly callable and present an “async” method. Both calls take an iterator of request values and a numeric timeout. Direct invocation of a value of this type invokes its associated RPC and blocks until the RPC’s response is available. Calling the “async” method of a value of this type invokes its associated RPC and immediately returns a future.Future bound to the asynchronous execution of the RPC.

__call__(request_iterator, timeout)[source]¶

Synchronously invokes the underlying RPC.

Parameters:	request_iterator – An iterator that yields request values for the RPC. timeout – A duration of time in seconds to allow for the RPC.
Returns:	The response value for the RPC.
Raises:	exceptions.RpcError – Indicating that the RPC was aborted.

async(request_iterator, timeout)[source]¶

Asynchronously invokes the underlying RPC.

Parameters:	request_iterator – An iterator that yields request values for the RPC. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A future.Future representing the RPC. In the event of RPC completion, the returned Future’s result value will be the response value of the RPC. In the event of RPC abortion, the returned Future’s exception value will be an exceptions.RpcError.

class grpc.framework.alpha.interfaces.Stub[source]¶

Bases: object

A stub with callable RPC method names for attributes.

Instances of this type are context managers and only afford RPC invocation when used in context.

Instances of this type, when used in context, respond to attribute access as follows: if the requested attribute is the name of a unary-unary RPC method, the value of the attribute will be a UnaryUnarySyncAsync with which to invoke the RPC method. If the requested attribute is the name of a unary-stream RPC method, the value of the attribute will be a callable taking a request object and a timeout parameter and returning a CancellableIterator that yields the response values of the RPC. If the requested attribute is the name of a stream-unary RPC method, the value of the attribute will be a StreamUnarySyncAsync with which to invoke the RPC method. If the requested attribute is the name of a stream-stream RPC method, the value of the attribute will be a callable taking an iterator of request objects and a timeout and returning a CancellableIterator that yields the response values of the RPC.

In all cases indication of abortion is indicated by raising of exceptions.RpcError, exceptions.CancellationError, and exceptions.ExpirationError.

class grpc.framework.alpha.interfaces.UnaryUnarySyncAsync[source]¶

Bases: object

Affords invoking a unary-unary RPC synchronously or asynchronously. Values implementing this interface are directly callable and present an “async” method. Both calls take a request value and a numeric timeout. Direct invocation of a value of this type invokes its associated RPC and blocks until the RPC’s response is available. Calling the “async” method of a value of this type invokes its associated RPC and immediately returns a future.Future bound to the asynchronous execution of the RPC.

__call__(request, timeout)[source]¶

Synchronously invokes the underlying RPC. :param request: The request value for the RPC. :param timeout: A duration of time in seconds to allow for the RPC.

Returns:	The response value for the RPC.
Raises:	exceptions.RpcError – Indicating that the RPC was aborted.

async(request, timeout)[source]¶

Asynchronously invokes the underlying RPC. :param request: The request value for the RPC. :param timeout: A duration of time in seconds to allow for the RPC.

Returns:	A future.Future representing the RPC. In the event of RPC completion, the returned Future’s result value will be the response value of the RPC. In the event of RPC abortion, the returned Future’s exception value will be an exceptions.RpcError.

grpc.framework.alpha.utilities module¶

Utilities for use with GRPC.

grpc.framework.alpha.utilities.stream_stream_invocation_description(request_serializer, response_deserializer)[source]¶

Creates an interfaces.RpcMethodInvocationDescription for an RPC method.

Parameters:	request_serializer – A callable that when called on a request value returns a bytestring corresponding to that value. response_deserializer – A callable that when called on a bytestring returns the response value corresponding to that bytestring.
Returns:	An interfaces.RpcMethodInvocationDescription constructed from the given arguments representing a streaming-request/streaming-response RPC method.

grpc.framework.alpha.utilities.stream_stream_service_description(behavior, request_deserializer, response_serializer)[source]¶

Creates an interfaces.RpcMethodServiceDescription for the given behavior.

Parameters:

behavior – A callable that implements a stream-stream RPC method that accepts an iterator of zero or more requests and an interfaces.RpcContext and returns an iterator of zero or more responses. request_deserializer – A callable that when called on a bytestring returns the request value corresponding to that bytestring. response_serializer – A callable that when called on a response value returns the bytestring corresponding to that value.

Returns:

An interfaces.RpcMethodServiceDescription constructed from the given arguments representing a streaming-request/streaming-response RPC method.

grpc.framework.alpha.utilities.stream_unary_invocation_description(request_serializer, response_deserializer)[source]¶

Creates an interfaces.RpcMethodInvocationDescription for an RPC method.

Parameters:	request_serializer – A callable that when called on a request value returns a bytestring corresponding to that value. response_deserializer – A callable that when called on a bytestring returns the response value corresponding to that bytestring.
Returns:	An interfaces.RpcMethodInvocationDescription constructed from the given arguments representing a streaming-request/unary-response RPC method.

grpc.framework.alpha.utilities.stream_unary_service_description(behavior, request_deserializer, response_serializer)[source]¶

Creates an interfaces.RpcMethodServiceDescription for the given behavior.

Parameters:

behavior – A callable that implements a stream-unary RPC method that accepts an iterator of zero or more requests and an interfaces.RpcContext and returns a single response. request_deserializer – A callable that when called on a bytestring returns the request value corresponding to that bytestring. response_serializer – A callable that when called on a response value returns the bytestring corresponding to that value.

Returns:

An interfaces.RpcMethodServiceDescription constructed from the given arguments representing a streaming-request/unary-response RPC method.

grpc.framework.alpha.utilities.unary_stream_invocation_description(request_serializer, response_deserializer)[source]¶

Creates an interfaces.RpcMethodInvocationDescription for an RPC method.

Parameters:	request_serializer – A callable that when called on a request value returns a bytestring corresponding to that value. response_deserializer – A callable that when called on a bytestring returns the response value corresponding to that bytestring.
Returns:	An interfaces.RpcMethodInvocationDescription constructed from the given arguments representing a unary-request/streaming-response RPC method.

grpc.framework.alpha.utilities.unary_stream_service_description(behavior, request_deserializer, response_serializer)[source]¶

Creates an interfaces.RpcMethodServiceDescription for the given behavior.

Parameters:

behavior – A callable that implements a unary-stream RPC method that accepts a single request and an interfaces.RpcContext and returns an iterator of zero or more responses. request_deserializer – A callable that when called on a bytestring returns the request value corresponding to that bytestring. response_serializer – A callable that when called on a response value returns the bytestring corresponding to that value.

Returns:

An interfaces.RpcMethodServiceDescription constructed from the given arguments representing a unary-request/streaming-response RPC method.

grpc.framework.alpha.utilities.unary_unary_invocation_description(request_serializer, response_deserializer)[source]¶

Creates an interfaces.RpcMethodInvocationDescription for an RPC method.

Parameters:	request_serializer – A callable that when called on a request value returns a bytestring corresponding to that value. response_deserializer – A callable that when called on a bytestring returns the response value corresponding to that bytestring.
Returns:	An interfaces.RpcMethodInvocationDescription constructed from the given arguments representing a unary-request/unary-response RPC method.

grpc.framework.alpha.utilities.unary_unary_service_description(behavior, request_deserializer, response_serializer)[source]¶

Creates an interfaces.RpcMethodServiceDescription for the given behavior.

Parameters:

behavior – A callable that implements a unary-unary RPC method that accepts a single request and an interfaces.RpcContext and returns a single response. request_deserializer – A callable that when called on a bytestring returns the request value corresponding to that bytestring. response_serializer – A callable that when called on a response value returns the bytestring corresponding to that value.

Returns:

An interfaces.RpcMethodServiceDescription constructed from the given arguments representing a unary-request/unary-response RPC method.

Module contents¶