@ -32,11 +32,24 @@
import abc import abc
import enum import enum
# exceptions, abandonment, and future are referenced from specification in this # cardinality, style, exceptions, abandonment, future, and stream are
# module. # referenced from specification in this module.
from grpc . framework . common import cardinality # pylint: disable=unused-import
from grpc . framework . common import style # pylint: disable=unused-import
from grpc . framework . face import exceptions # pylint: disable=unused-import from grpc . framework . face import exceptions # pylint: disable=unused-import
from grpc . framework . foundation import abandonment # pylint: disable=unused-import from grpc . framework . foundation import abandonment # pylint: disable=unused-import
from grpc . framework . foundation import future # pylint: disable=unused-import from grpc . framework . foundation import future # pylint: disable=unused-import
from grpc . framework . foundation import stream # pylint: disable=unused-import
@enum . unique
class Abortion ( enum . Enum ) :
""" Categories of RPC abortion. """
CANCELLED = ' cancelled '
EXPIRED = ' expired '
NETWORK_FAILURE = ' network failure '
SERVICED_FAILURE = ' serviced failure '
SERVICER_FAILURE = ' servicer failure '
class CancellableIterator ( object ) : class CancellableIterator ( object ) :
@ -59,69 +72,61 @@ class CancellableIterator(object):
raise NotImplementedError ( ) raise NotImplementedError ( )
class UnaryUnarySyncAsync ( object ) : class RpcContext ( object ) :
""" Affords invoking a unary-unary RPC synchronously or asynchronously. """ Provides RPC-related information and action. """
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 .
"""
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def __call__ ( self , request , timeout ) : def is_active ( self ) :
""" Synchronously invokes the underlying RPC. """ Describes whether the RPC is active or has terminated. """
raise NotImplementedError ( )
Args : @abc . abstractmethod
request : The request value for the RPC . def time_remaining ( self ) :
timeout : A duration of time in seconds to allow for the RPC . """ Describes the length of allowed time remaining for the RPC .
Returns : Returns :
The response value for the RPC . A nonnegative float indicating the length of allowed time in seconds
remaining for the RPC to complete before it is considered to have timed
Raises : out .
exceptions . RpcError : Indicating that the RPC was aborted .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
@abc . abstractmethod @abc . abstractmethod
def async ( self , request , timeout ) : def add_abortion_callback ( self , abortion_callback ) :
""" Asynchronously invokes the underlying RPC . """ Registers a callback to be called if the RPC is aborted .
Args : Args :
request : The request value for the RPC . abortion_callback : A callable to be called and passed an Abortion value
timeout : A duration of time in seconds to allow for the RPC . in the event of RPC abortion .
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 .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class StreamUnarySyncAsync ( object ) : class Call ( object ) :
""" Affords invoking a stream-unary RPC synchronously or asynchronously . """ Invocation-side representation of an RPC.
Values implementing this interface are directly callable and present an Attributes :
" async " method . Both calls take an iterator of request values and a numeric context : An RpcContext affording information about the RPC .
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 .
""" """
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def __call__ ( self , request_iterator , timeout ) : def cancel ( self ) :
""" Requests cancellation of the RPC. """
raise NotImplementedError ( )
class UnaryUnaryMultiCallable ( object ) :
""" Affords invoking a unary-unary RPC in any call style. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def __call__ ( self , request , timeout ) :
""" Synchronously invokes the underlying RPC. """ Synchronously invokes the underlying RPC.
Args : Args :
request_iterator : An iterator that yields request values for the RPC . request : The request value for the RPC .
timeout : A duration of time in seconds to allow for the RPC . timeout : A duration of time in seconds to allow for the RPC .
Returns : Returns :
@ -133,11 +138,11 @@ class StreamUnarySyncAsync(object):
raise NotImplementedError ( ) raise NotImplementedError ( )
@abc . abstractmethod @abc . abstractmethod
def async ( self , request , timeout ) : def future ( self , request , timeout ) :
""" Asynchronously invokes the underlying RPC. """ Asynchronously invokes the underlying RPC.
Args : Args :
request_iterator : An iterator that yields request values for the RPC . request : The request value for the RPC .
timeout : A duration of time in seconds to allow for the RPC . timeout : A duration of time in seconds to allow for the RPC .
Returns : Returns :
@ -148,248 +153,204 @@ class StreamUnarySyncAsync(object):
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
@enum . unique
class Abortion ( enum . Enum ) :
""" Categories of RPC abortion. """
CANCELLED = ' cancelled '
EXPIRED = ' expired '
NETWORK_FAILURE = ' network failure '
SERVICED_FAILURE = ' serviced failure '
SERVICER_FAILURE = ' servicer failure '
class RpcContext ( object ) :
""" Provides RPC-related information and action. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def is_active ( self ) :
""" Describes whether the RPC is active or has terminated. """
raise NotImplementedError ( )
@abc . abstractmethod
def time_remaining ( self ) :
""" 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 .
"""
raise NotImplementedError ( )
@abc . abstractmethod @abc . abstractmethod
def add_abortion_callback ( self , abortion_callback ) : def event ( self , request , response_callback , abortion_callback , timeout ) :
""" Registers a callback to be called if the RPC is aborted . """ Asynchronously invokes the underlying RPC.
Args : Args :
abortion_callback : A callable to be called and passed an Abortion value 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 . 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 .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class InlineValueInValueOutMethod ( object ) : class UnaryStreamMultiCallable ( object ) :
""" A type for inline unary-request-unary-response RPC methods . """ """ Affords invoking a unary-stream RPC in any call style. """
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def service ( self , request , contex t) : def __call__ ( self , request , timeout ) :
""" Services an RPC that accepts one value and produces one value . """ Synchronously invokes the underlying RPC.
Args : Args :
request : The single request value for the RPC . request : The request value for the RPC .
context : An RpcContext object . timeout : A duration of time in seconds to allow for the RPC .
Returns : Returns :
The single response value for the RPC . A CancellableIterator that yields the response values of the RPC and
affords RPC cancellation . Drawing response values from the returned
Raises : CancellableIterator may raise exceptions . RpcError indicating abortion
abandonment . Abandoned : If no response is necessary because the RPC has of the RPC .
been aborted .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class InlineValueInStreamOutMethod ( object ) :
""" A type for inline unary-request-stream-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def s er vic e( self , request , contex t) : def event ( self , request , response_consumer , abortion_callback , timeout ) :
""" Services an RPC that accepts one value and produces a stream of values . """ Asynchronously invokes the underlying RPC.
Args : Args :
request : The single request value for the RPC . request : The request value for the RPC .
context : An RpcContext object . response_consumer : A stream . Consumer to be called to accept the restponse
values of the RPC .
Yields : abortion_callback : A callback to be called and passed an Abortion value
The values that comprise the response stream of the RPC . in the event of RPC abortion .
timeout : A duration of time in seconds to allow for the RPC .
Raises : Returns :
abandonment . Abandoned : If completing the response stream is not necessary A Call object for the RPC .
because the RPC has been aborted .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class InlineStreamInValueOutMethod ( object ) : class StreamUnaryMultiCallable ( object ) :
""" A type for inline stream-request-unary-response RPC methods . """ """ Affords invoking a stream-unary RPC in any call style . """
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def service ( self , request_iterator , contex t) : def __call__ ( self , request_iterator , timeou t) :
""" Services an RPC that accepts a stream of values and produces one value . """ Synchronously invokes the underlying RPC .
Args : Args :
request_iterator : An iterator that yields the request values of the RPC . request_iterator : An iterator that yields request values for the RPC .
Drawing values from this iterator may also raise exceptions . RpcError to timeout : A duration of time in seconds to allow for the RPC .
indicate abortion of the RPC .
context : An RpcContext object .
Yield s: Returns :
The values that comprise the response stream of the RPC . The response value for the RPC .
Raises : Raises :
abandonment . Abandoned : If no response is necessary because the RPC has exceptions . RpcError : Indicating that the RPC was aborted .
been aborted .
exceptions . RpcError : Implementations of this method must not deliberately
raise exceptions . RpcError but may allow such errors raised by the
request_iterator passed to them to propagate through their bodies
uncaught .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class InlineStreamInStreamOutMethod ( object ) :
""" A type for inline stream-request-stream-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def servic e( self , request_iterator , contex t) : def future ( self , request_iterator , timeout ) :
""" Services an RPC that accepts and produces streams of values . """ Asynchronously invokes the underlying RPC.
Args : Args :
request_iterator : An iterator that yields the request values of the RPC . request_iterator : An iterator that yields request values for the RPC .
Drawing values from this iterator may also raise exceptions . RpcError to timeout : A duration of time in seconds to allow for the RPC .
indicate abortion of the RPC .
context : An RpcContext object .
Yields :
The values that comprise the response stream of the RPC .
Raises : Returns :
abandonment . Abandoned : If completing the response stream is not necessary A future . Future representing the RPC . In the event of RPC completion , the
because the RPC has been aborted . returned Future ' s result value will be the response value of the RPC.
exceptions . RpcError : Implementations of this method must not deliberately In the event of RPC abortion , the returned Future ' s exception value
raise exceptions . RpcError but may allow such errors raised by the will be an exceptions . RpcError .
request_iterator passed to them to propagate through their bodies
uncaught .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class EventValueInValueOutMethod ( object ) :
""" A type for event-driven unary-request-unary-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def s er vic e( self , request , response_callback , contex t ) : def event ( self , response_callback , abortion_callback , timeout ) :
""" Services an RPC that accepts one value and produces one value . """ Asynchronously invokes the underlying RPC.
Args : Args :
request : The single request value for the RPC . request : The request value for the RPC .
response_callback : A callback to be called to accept the response value of response_callback : A callback to be called to accept the restponse value
the RPC . of the RPC .
context : An RpcContext object . 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 .
Raises : Return s :
abandonment . Abandoned : May or may not be raised when the RPC has been A pair of a Call object for the RPC and a stream . Consumer to which the
abort ed. request values of the RPC should be pass ed.
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class EventValueInStreamOutMethod ( object ) : class StreamStreamMultiCallable ( object ) :
""" A type for event-driven unary-request-stream-response RPC methods . """ """ Affords invoking a stream-stream RPC in any call style . """
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def service ( self , request , response_consumer , contex t) : def __call__ ( self , request_iterator , timeou t ) :
""" Services an RPC that accepts one value and produces a stream of values . """ Synchronously invokes the underlying RPC .
Args : Args :
request : The single request value for the RPC . request_iterator : An iterator that yields request values for the RPC .
response_consumer : A stream . Consumer to be called to accept the response timeout : A duration of time in seconds to allow for the RPC .
values of the RPC .
context : An RpcContext object .
Raises : Returns :
abandonment . Abandoned : May or may not be raised when the RPC has been A CancellableIterator that yields the response values of the RPC and
aborted . affords RPC cancellation . Drawing response values from the returned
CancellableIterator may raise exceptions . RpcError indicating abortion
of the RPC .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class EventStreamInValueOutMethod ( object ) :
""" A type for event-driven stream-request-unary-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod @abc . abstractmethod
def s er vic e( self , response_callback , contex t) : def event ( self , response_consumer , abortion_callback , timeout ) :
""" Services an RPC that accepts a stream of values and produces one value . """ Asynchronously invokes the underlying RPC.
Args : l Args :
response_callback : A callback to be called to accept the response value of response_consumer : A stream . Consumer to be called to accept the restponse
the RPC . values of the RPC .
context : An RpcContext object . 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 : Returns :
A stream . Consumer with which to accept the request values of the RPC . The A pair of a Call object for the RPC and a stream . Consumer to which the
consumer returned from this method may or may not be invoked to request values of the RPC should be passed .
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 .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
class EventStreamInStreamOutMethod ( object ) : class MethodImplementation ( object ) :
""" A type for event-driven stream-request-stream-response RPC methods. """ """ A sum type that describes an RPC method implementation.
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def service ( self , response_consumer , context ) :
""" Services an RPC that accepts and produces streams of values.
Args :
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 : Attributes :
abandonment . Abandoned : May or may not be raised when the RPC has been cardinality : A cardinality . Cardinality value .
aborted . 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 .
""" """
raise NotImplementedError ( ) __metaclass__ = abc . ABCMeta
class MultiMethod ( object ) : class MultiMethodImplementation ( object ) :
""" A general type able to service many RPC methods. """ """ A general type able to service many RPC methods. """
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@ -420,26 +381,7 @@ class MultiMethod(object):
raise NotImplementedError ( ) raise NotImplementedError ( )
class Server ( object ) : class GenericStub ( object ) :
""" Specification of a running server that services RPCs. """
__metaclass__ = abc . ABCMeta
class Call ( object ) :
""" Invocation-side representation of an RPC.
Attributes :
context : An RpcContext affording information about the RPC .
"""
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def cancel ( self ) :
""" Requests cancellation of the RPC. """
raise NotImplementedError ( )
class Stub ( object ) :
""" Affords RPC methods to callers. """ """ Affords RPC methods to callers. """
__metaclass__ = abc . ABCMeta __metaclass__ = abc . ABCMeta
@ -632,25 +574,67 @@ class Stub(object):
raise NotImplementedError ( ) raise NotImplementedError ( )
@abc . abstractmethod @abc . abstractmethod
def unary_unary_sync_async ( self , name ) : def unary_unary_multi_callable ( self , name ) :
""" Creates a UnaryUnarySyncAsync valu e for a unary-unary RPC method. """ Creates a UnaryUnaryMultiCallabl e for a unary-unary RPC method.
Args : Args :
name : The RPC method name . name : The RPC method name .
Returns : Returns :
A UnaryUnarySyncAsync value for the named unary - unary RPC method . A UnaryUnaryMultiCallable value for the named unary - unary RPC method .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
@abc . abstractmethod @abc . abstractmethod
def stream_unary_sync_async ( self , name ) : def unary_stream_multi_callable ( self , name ) :
""" Creates a StreamUnarySyncAsync value for a stream-unary RPC method. """ Creates a UnaryStreamMultiCallable for a unary-stream RPC method.
Args : Args :
name : The RPC method name . name : The RPC method name .
Returns : Returns :
A StreamUnarySyncAsync value for the named stream - unary RPC method . A UnaryStreamMultiCallable value for the name unary - stream RPC method .
""" """
raise NotImplementedError ( ) raise NotImplementedError ( )
@abc . abstractmethod
def stream_unary_multi_callable ( self , name ) :
""" Creates a StreamUnaryMultiCallable for a stream-unary RPC method.
Args :
name : The RPC method name .
Returns :
A StreamUnaryMultiCallable value for the named stream - unary RPC method .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def stream_stream_multi_callable ( self , name ) :
""" Creates a StreamStreamMultiCallable for a stream-stream RPC method.
Args :
name : The RPC method name .
Returns :
A StreamStreamMultiCallable value for the named stream - stream RPC method .
"""
raise NotImplementedError ( )
class DynamicStub ( 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 .
"""
__metaclass__ = abc . ABCMeta
Nathaniel Manista
10 years ago