grpc.framework.face package¶

Submodules¶

grpc.framework.face.demonstration module¶

Demonstration-suitable implementation of the face layer of RPC Framework.

class grpc.framework.face.demonstration.LinkedPair[source]¶

Bases: object

A Server and Stub that are linked to one another.

server¶: A Server.

stub¶: A Stub.

shut_down()[source]¶: Shuts down this object and releases its resources.

grpc.framework.face.demonstration.server_and_stub(default_timeout, inline_value_in_value_out_methods=None, inline_value_in_stream_out_methods=None, inline_stream_in_value_out_methods=None, inline_stream_in_stream_out_methods=None, event_value_in_value_out_methods=None, event_value_in_stream_out_methods=None, event_stream_in_value_out_methods=None, event_stream_in_stream_out_methods=None, multi_method=None)[source]¶: Creates a Server and Stub linked together for use.

grpc.framework.face.exceptions module¶

Exceptions used in the Face layer of RPC Framework.

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

Bases: grpc.framework.face.exceptions.RpcError

Indicates that an RPC has been cancelled.

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

Bases: grpc.framework.face.exceptions.RpcError

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

exception grpc.framework.face.exceptions.NetworkError[source]¶

Bases: grpc.framework.face.exceptions.RpcError

Indicates that some error occurred on the network.

exception grpc.framework.face.exceptions.NoSuchMethodError(name)[source]¶

Bases: exceptions.Exception

Raised by customer code to indicate an unrecognized RPC method name.

name¶: The unrecognized name.

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

Bases: exceptions.Exception

Common super type for all exceptions raised by the Face layer.

Only RPC Framework should instantiate and raise these exceptions.

exception grpc.framework.face.exceptions.ServicedError[source]¶

Bases: grpc.framework.face.exceptions.RpcError

Indicates that the Serviced failed in the course of an RPC.

exception grpc.framework.face.exceptions.ServicerError[source]¶

Bases: grpc.framework.face.exceptions.RpcError

Indicates that the Servicer failed in the course of servicing an RPC.

grpc.framework.face.implementations module¶

Entry points into the Face layer of RPC Framework.

grpc.framework.face.implementations.dynamic_stub(cardinalities, front, pool, prefix)[source]¶

Creates an interfaces.DynamicStub.

Parameters:

cardinalities – A dict from RPC method name to cardinality.Cardinality value identifying the cardinality of every RPC method to be supported by the created interfaces.DynamicStub.
front – A base_interfaces.Front.
pool – A futures.ThreadPoolExecutor.
prefix – A string to prepend when mapping requested attribute name to RPC method name during attribute access on the created interfaces.DynamicStub.

Returns:

An interfaces.DynamicStub that performs RPCs via the given base_interfaces.Front.

grpc.framework.face.implementations.generic_stub(front, pool)[source]¶

Creates an interfaces.GenericStub.

Parameters:	front – A base_interfaces.Front. pool – A futures.ThreadPoolExecutor.
Returns:	An interfaces.GenericStub that performs RPCs via the given base_interfaces.Front.

grpc.framework.face.implementations.servicer(pool, method_implementations, multi_method_implementation)[source]¶

Creates a base_interfaces.Servicer.

It is guaranteed that any passed interfaces.MultiMethodImplementation will only be called to service an RPC if there is no interfaces.MethodImplementation for the RPC method in the passed method_implementations dictionary.

Parameters:	pool – A thread pool. method_implementations – A dictionary from RPC method name to interfaces.MethodImplementation object to be used to service the named RPC method. multi_method_implementation – An interfaces.MultiMethodImplementation to be used to service any RPCs not serviced by the interfaces.MethodImplementations given in the method_implementations dictionary, or None.
Returns:	A base_interfaces.Servicer that services RPCs via the given implementations.

grpc.framework.face.interfaces module¶

Interfaces for the face layer of RPC Framework.

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

Bases: enum.Enum

Categories of RPC abortion.

class grpc.framework.face.interfaces.Call[source]¶

Bases: object

Invocation-side representation of an RPC.

context¶: An RpcContext affording information about the RPC.

cancel()[source]¶: Requests cancellation of the RPC.

class grpc.framework.face.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.face.interfaces.DynamicStub[source]¶

Bases: object

A stub with RPC-method-bound multi-callable attributes.

Instances of this type responsd 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 UnaryUnaryMultiCallable 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 UnaryStreamMultiCallable with which to invoke the RPC method; if the requested attribute is the name of a stream-unary RPC method, the value of the attribute will be a StreamUnaryMultiCallable with which to invoke the RPC method; and if the requested attribute is the name of a stream-stream RPC method, the value of the attribute will be a StreamStreamMultiCallable with which to invoke the RPC method.

class grpc.framework.face.interfaces.GenericStub[source]¶

Bases: object

Affords RPC methods to callers.

blocking_stream_in_value_out(name, request_iterator, timeout)[source]¶

Invokes a stream-request-unary-response RPC method.

This method blocks until either returning the response value of the RPC (in the event of RPC completion) or raising an exception (in the event of RPC abortion).

Parameters:	name – The RPC method name. request_iterator – An iterator that yields the request values of 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.

blocking_value_in_value_out(name, request, timeout)[source]¶

Invokes a unary-request-unary-response RPC method.

This method blocks until either returning the response value of the RPC (in the event of RPC completion) or raising an exception (in the event of RPC abortion).

Parameters:	name – The RPC method name. request – The request value 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.

event_stream_in_stream_out(name, response_consumer, abortion_callback, timeout)[source]¶

Event-driven invocation of a unary-request-stream-response RPC method.

Parameters:	name – The RPC method name. response_consumer – A stream.Consumer to be called to accept the response values of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A pair of a Call object for the RPC and a stream.Consumer to which the request values of the RPC should be passed.

event_stream_in_value_out(name, response_callback, abortion_callback, timeout)[source]¶

Event-driven invocation of a unary-request-unary-response RPC method.

Parameters:	name – The RPC method name. response_callback – A callback to be called to accept the response value of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A pair of a Call object for the RPC and a stream.Consumer to which the request values of the RPC should be passed.

event_value_in_stream_out(name, request, response_consumer, abortion_callback, timeout)[source]¶

Event-driven invocation of a unary-request-stream-response RPC method.

Parameters:	name – The RPC method name. request – The request value for the RPC. response_consumer – A stream.Consumer to be called to accept the response values of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A Call object for the RPC.

event_value_in_value_out(name, request, response_callback, abortion_callback, timeout)[source]¶

Event-driven invocation of a unary-request-unary-response RPC method.

Parameters:	name – The RPC method name. request – The request value for the RPC. response_callback – A callback to be called to accept the response value of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A Call object for the RPC.

future_stream_in_value_out(name, request_iterator, timeout)[source]¶

Invokes a stream-request-unary-response RPC method.

Parameters:	name – The RPC method name. request_iterator – An iterator that yields the request values of 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 will return an outcome indicating that the RPC returned the response value of the RPC. In the event of RPC abortion, the returned Future will return an outcome indicating that the RPC raised an exceptions.RpcError.

future_value_in_value_out(name, request, timeout)[source]¶

Invokes a unary-request-unary-response RPC method.

Parameters:	name – The RPC method name. request – The request value 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 will return an outcome indicating that the RPC returned the response value of the RPC. In the event of RPC abortion, the returned Future will return an outcome indicating that the RPC raised an exceptions.RpcError.

inline_stream_in_stream_out(name, request_iterator, timeout)[source]¶

Invokes a stream-request-stream-response RPC method.

Parameters:	name – The RPC method name. request_iterator – An iterator that yields the request values of the RPC. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A CancellableIterator that yields the response values of the RPC and affords RPC cancellation. Drawing response values from the returned CancellableIterator may raise exceptions.RpcError indicating abortion of the RPC.

inline_value_in_stream_out(name, request, timeout)[source]¶

Invokes a unary-request-stream-response RPC method.

Parameters:	name – The RPC method name. request – The request value for the RPC. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A CancellableIterator that yields the response values of the RPC and affords RPC cancellation. Drawing response values from the returned CancellableIterator may raise exceptions.RpcError indicating abortion of the RPC.

stream_stream_multi_callable(name)[source]¶

Creates a StreamStreamMultiCallable for a stream-stream RPC method.

Parameters:	name – The RPC method name.
Returns:	A StreamStreamMultiCallable value for the named stream-stream RPC method.

stream_unary_multi_callable(name)[source]¶

Creates a StreamUnaryMultiCallable for a stream-unary RPC method.

Parameters:	name – The RPC method name.
Returns:	A StreamUnaryMultiCallable value for the named stream-unary RPC method.

unary_stream_multi_callable(name)[source]¶

Creates a UnaryStreamMultiCallable for a unary-stream RPC method.

Parameters:	name – The RPC method name.
Returns:	A UnaryStreamMultiCallable value for the name unary-stream RPC method.

unary_unary_multi_callable(name)[source]¶

Creates a UnaryUnaryMultiCallable for a unary-unary RPC method.

Parameters:	name – The RPC method name.
Returns:	A UnaryUnaryMultiCallable value for the named unary-unary RPC method.

class grpc.framework.face.interfaces.MethodImplementation[source]¶

Bases: object

A sum type that describes an RPC method implementation.

cardinality¶: A cardinality.Cardinality value.

style¶: A style.Service value.

unary_unary_inline¶: The implementation of the RPC method as a callable value that takes a request value and an RpcContext object and returns a response value. Only non-None if cardinality is cardinality.Cardinality.UNARY_UNARY and style is style.Service.INLINE.

unary_stream_inline¶: The implementation of the RPC method as a callable value that takes a request value and an RpcContext object and returns an iterator of response values. Only non-None if cardinality is cardinality.Cardinality.UNARY_STREAM and style is style.Service.INLINE.

stream_unary_inline¶: The implementation of the RPC method as a callable value that takes an iterator of request values and an RpcContext object and returns a response value. Only non-None if cardinality is cardinality.Cardinality.STREAM_UNARY and style is style.Service.INLINE.

stream_stream_inline¶: The implementation of the RPC method as a callable value that takes an iterator of request values and an RpcContext object and returns an iterator of response values. Only non-None if cardinality is cardinality.Cardinality.STREAM_STREAM and style is style.Service.INLINE.

unary_unary_event¶: The implementation of the RPC method as a callable value that takes a request value, a response callback to which to pass the response value of the RPC, and an RpcContext. Only non-None if cardinality is cardinality.Cardinality.UNARY_UNARY and style is style.Service.EVENT.

unary_stream_event¶: The implementation of the RPC method as a callable value that takes a request value, a stream.Consumer to which to pass the the response values of the RPC, and an RpcContext. Only non-None if cardinality is cardinality.Cardinality.UNARY_STREAM and style is style.Service.EVENT.

stream_unary_event¶: The implementation of the RPC method as a callable value that takes a response callback to which to pass the response value of the RPC and an RpcContext and returns a stream.Consumer to which the request values of the RPC should be passed. Only non-None if cardinality is cardinality.Cardinality.STREAM_UNARY and style is style.Service.EVENT.

stream_stream_event¶: The implementation of the RPC method as a callable value that takes a stream.Consumer to which to pass the response values of the RPC and an RpcContext and returns a stream.Consumer to which the request values of the RPC should be passed. Only non-None if cardinality is cardinality.Cardinality.STREAM_STREAM and style is style.Service.EVENT.

class grpc.framework.face.interfaces.MultiMethodImplementation[source]¶

Bases: object

A general type able to service many RPC methods.

service(name, response_consumer, context)[source]¶

Services an RPC.

Parameters:	name – The RPC method name. response_consumer – A stream.Consumer to be called to accept the response values of the RPC. context – An RpcContext object.
Returns:	A stream.Consumer with which to accept the request values of the RPC. The consumer returned from this method may or may not be invoked to completion: in the case of RPC abortion, RPC Framework will simply stop passing values to this object. Implementations must not assume that this object will be called to completion of the request stream or even called at all.
Raises:	`abandonment.Abandoned` – May or may not be raised when the RPC has been aborted. `exceptions.NoSuchMethodError` – If this MultiMethod does not recognize the given RPC method name and is not able to service the RPC.

class grpc.framework.face.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.

Parameters:	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.face.interfaces.StreamStreamMultiCallable[source]¶

Bases: object

Affords invoking a stream-stream RPC in any call style.

__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:	A CancellableIterator that yields the response values of the RPC and affords RPC cancellation. Drawing response values from the returned CancellableIterator may raise exceptions.RpcError indicating abortion of the RPC.

event(response_consumer, abortion_callback, timeout)[source]¶

Asynchronously invokes the underlying RPC.

l Args:

response_consumer: A stream.Consumer to be called to accept the restponse

values of the RPC.

abortion_callback: A callback to be called and passed an Abortion value

in the event of RPC abortion.

timeout: A duration of time in seconds to allow for the RPC.

Returns:

A pair of a Call object for the RPC and a stream.Consumer to which the: request values of the RPC should be passed.

class grpc.framework.face.interfaces.StreamUnaryMultiCallable[source]¶

Bases: object

Affords invoking a stream-unary RPC in any call style.

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

event(response_callback, abortion_callback, timeout)[source]¶

Asynchronously invokes the underlying RPC.

Parameters:	request – The request value for the RPC. response_callback – A callback to be called to accept the restponse value of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A pair of a Call object for the RPC and a stream.Consumer to which the request values of the RPC should be passed.

future(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.face.interfaces.UnaryStreamMultiCallable[source]¶

Bases: object

Affords invoking a unary-stream RPC in any call style.

__call__(request, timeout)[source]¶

Synchronously invokes the underlying RPC.

Parameters:	request – The request value for the RPC. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A CancellableIterator that yields the response values of the RPC and affords RPC cancellation. Drawing response values from the returned CancellableIterator may raise exceptions.RpcError indicating abortion of the RPC.

event(request, response_consumer, abortion_callback, timeout)[source]¶

Asynchronously invokes the underlying RPC.

Parameters:	request – The request value for the RPC. response_consumer – A stream.Consumer to be called to accept the restponse values of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A Call object for the RPC.

class grpc.framework.face.interfaces.UnaryUnaryMultiCallable[source]¶

Bases: object

Affords invoking a unary-unary RPC in any call style.

__call__(request, timeout)[source]¶

Synchronously invokes the underlying RPC.

Parameters:	request – The request value 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.

event(request, response_callback, abortion_callback, timeout)[source]¶

Asynchronously invokes the underlying RPC.

Parameters:	request – The request value for the RPC. response_callback – A callback to be called to accept the restponse value of the RPC. abortion_callback – A callback to be called and passed an Abortion value in the event of RPC abortion. timeout – A duration of time in seconds to allow for the RPC.
Returns:	A Call object for the RPC.

future(request, timeout)[source]¶

Asynchronously invokes the underlying RPC.

Parameters:	request – The request value 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.