@ -32,11 +32,24 @@
import abc
import enum
# exceptions, abandonment, and future are referenced from specification in this
# module.
# cardinality, style, exceptions, abandonment, future, and stream are
# 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 . foundation import abandonment # 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 ) :
@ -59,69 +72,61 @@ class CancellableIterator(object):
raise NotImplementedError ( )
class UnaryUnarySyncAsync ( 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 .
"""
class RpcContext ( object ) :
""" Provides RPC-related information and action. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def __call__ ( self , request , timeout ) :
""" Synchronously invokes the underlying RPC.
def is_active ( self ) :
""" Describes whether the RPC is active or has terminated. """
raise NotImplementedError ( )
Args :
request : The request value for the RPC .
timeout : A duration of time in seconds to allow for the RPC .
@abc . abstractmethod
def time_remaining ( self ) :
""" Describes the length of allowed time remaining for the RPC .
Returns :
The response value for the RPC .
Raises :
exceptions . RpcError : Indicating that the RPC was aborted .
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
def async ( self , request , timeout ) :
""" Asynchronously invokes the underlying RPC .
def add_abortion_callback ( self , abortion_callback ) :
""" Registers a callback to be called if the RPC is aborted .
Args :
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 .
abortion_callback : A callable to be called and passed an Abortion value
in the event of RPC abortion .
"""
raise NotImplementedError ( )
class StreamUnarySyncAsync ( object ) :
""" Affords invoking a stream-unary RPC synchronously or asynchronously .
class Call ( object ) :
""" Invocation-side representation of an RPC.
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 .
Attributes :
context : An RpcContext affording information about the RPC .
"""
__metaclass__ = abc . ABCMeta
@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.
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 .
Returns :
@ -133,11 +138,11 @@ class StreamUnarySyncAsync(object):
raise NotImplementedError ( )
@abc . abstractmethod
def async ( self , request , timeout ) :
def future ( self , request , timeout ) :
""" Asynchronously invokes the underlying RPC.
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 .
Returns :
@ -148,248 +153,204 @@ class StreamUnarySyncAsync(object):
"""
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
def add_abortion_callback ( self , abortion_callback ) :
""" Registers a callback to be called if the RPC is aborted .
def event ( self , request , response_callback , abortion_callback , timeout ) :
""" Asynchronously invokes the underlying RPC.
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 .
"""
raise NotImplementedError ( )
class InlineValueInValueOutMethod ( object ) :
""" A type for inline unary-request-unary-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def service ( self , request , context ) :
""" Services an RPC that accepts one value and produces one value.
Args :
request : The single request value for the RPC .
context : An RpcContext object .
timeout : A duration of time in seconds to allow for the RPC .
Returns :
The single response value for the RPC .
Raises :
abandonment . Abandoned : If no response is necessary because the RPC has
been aborted .
A Call object for the RPC .
"""
raise NotImplementedError ( )
class InlineValueInStreamOutMethod ( object ) :
""" A type for inline unary-request-stream-response RPC methods . """
class UnaryStreamMultiCallable ( object ) :
""" Affords invoking a unary-stream RPC in any call style. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def service ( self , request , contex t) :
""" Services an RPC that accepts one value and produces a stream of values .
def __call__ ( self , request , timeout ) :
""" Synchronously invokes the underlying RPC.
Args :
request : The single request value for the RPC .
context : An RpcContext object .
Yields :
The values that comprise the response stream of the RPC .
request : The request value for the RPC .
timeout : A duration of time in seconds to allow for the RPC .
Raises :
abandonment . Abandoned : If completing the response stream is not necessary
because the RPC has been aborted .
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 .
"""
raise NotImplementedError ( )
class InlineStreamInValueOutMethod ( object ) :
""" A type for inline stream-request-unary-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def s er vic e( self , request_iterator , contex t ) :
""" Services an RPC that accepts a stream of values and produces one value .
def event ( self , request , response_consumer , abortion_callback , timeout ) :
""" Asynchronously invokes the underlying RPC.
Args :
request_iterator : An iterator that yields the request values of the RPC .
Drawing values from this iterator may also raise exceptions . RpcError to
indicate abortion of the RPC .
context : An RpcContext object .
Yields :
The values that comprise the response stream of the RPC .
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 .
Raises :
abandonment . Abandoned : If no response is necessary because the RPC has
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 .
Returns :
A Call object for the RPC .
"""
raise NotImplementedError ( )
class InlineStreamInStreamOutMethod ( object ) :
""" A type for inline stream-request-stream-response RPC methods . """
class StreamUnaryMultiCallable ( object ) :
""" Affords invoking a stream-unary RPC in any call style . """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def service ( self , request_iterator , contex t) :
""" Services an RPC that accepts and produces streams of values .
def __call__ ( self , request_iterator , timeou t) :
""" Synchronously invokes the underlying RPC .
Args :
request_iterator : An iterator that yields the request values of the RPC .
Drawing values from this iterator may also raise exceptions . RpcError to
indicate abortion of the RPC .
context : An RpcContext object .
request_iterator : An iterator that yields request values for the RPC .
timeout : A duration of time in seconds to allow for the RPC .
Yield s:
The values that comprise the response stream of the RPC .
Returns :
The response value for the RPC .
Raises :
abandonment . Abandoned : If completing the response stream is not necessary
because the RPC has 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 .
exceptions . RpcError : Indicating that the RPC was aborted .
"""
raise NotImplementedError ( )
class EventValueInValueOutMethod ( object ) :
""" A type for event-driven unary-request-unary-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def servic e( self , request , response_callback , contex t) :
""" Services an RPC that accepts one value and produces one value .
def future ( self , request_iterator , timeout ) :
""" Asynchronously invokes the underlying RPC.
Args :
request : The single request value for the RPC .
response_callback : A callback to be called to accept the response value of
the RPC .
context : An RpcContext object .
request_iterator : An iterator that yields request values for the RPC .
timeout : A duration of time in seconds to allow for the RPC .
Raises :
abandonment . Abandoned : May or may not be raised when the RPC has been
aborted .
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 ( )
class EventValueInStreamOutMethod ( object ) :
""" A type for event-driven unary-request-stream-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def s er vic e( self , request , response_consumer , contex t ) :
""" Services an RPC that accepts one value and produces a stream of values .
def event ( self , response_callback , abortion_callback , timeout ) :
""" Asynchronously invokes the underlying RPC.
Args :
request : The single request value for the RPC .
response_consumer : A stream . Consumer to be called to accept the response
values of the RPC .
context : An RpcContext object .
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 .
Raises :
abandonment . Abandoned : May or may not be raised when the RPC has been
abort ed.
Return s :
A pair of a Call object for the RPC and a stream . Consumer to which the
request values of the RPC should be pass ed.
"""
raise NotImplementedError ( )
class EventStreamInValueOutMethod ( object ) :
""" A type for event-driven stream-request-unary-response RPC methods . """
class StreamStreamMultiCallable ( object ) :
""" Affords invoking a stream-stream RPC in any call style . """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def service ( self , response_callback , contex t ) :
""" Services an RPC that accepts a stream of values and produces one value .
def __call__ ( self , request_iterator , timeou t ) :
""" Synchronously invokes the underlying RPC .
Args :
response_callback : A callback to be called to accept the response value of
the RPC .
context : An RpcContext object .
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 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 .
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 .
"""
raise NotImplementedError ( )
class EventStreamInStreamOutMethod ( object ) :
""" A type for event-driven stream-request-stream-response RPC methods. """
__metaclass__ = abc . ABCMeta
@abc . abstractmethod
def s er vic e( self , response_consumer , contex t) :
""" Services an RPC that accepts and produces streams of values .
def event ( self , response_consumer , abortion_callback , timeout ) :
""" Asynchronously invokes the underlying RPC.
Args :
response_consumer : A stream . Consumer to be called to accept the response
l Args :
response_consumer : A stream . Consumer to be called to accept the rest ponse
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 :
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 .
A pair of a Call object for the RPC and a stream . Consumer to which the
request values of the RPC should be passed .
"""
raise NotImplementedError ( )
class MultiMethod ( object ) :
class MethodImplementation ( object ) :
""" A sum type that describes an RPC method implementation.
Attributes :
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 .
"""
__metaclass__ = abc . ABCMeta
class MultiMethodImplementation ( object ) :
""" A general type able to service many RPC methods. """
__metaclass__ = abc . ABCMeta
@ -420,26 +381,7 @@ class MultiMethod(object):
raise NotImplementedError ( )
class Server ( 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 ) :
class GenericStub ( object ) :
""" Affords RPC methods to callers. """
__metaclass__ = abc . ABCMeta
@ -632,25 +574,67 @@ class Stub(object):
raise NotImplementedError ( )
@abc . abstractmethod
def unary_unary_sync_async ( self , name ) :
""" Creates a UnaryUnarySyncAsync value for a unary-unary RPC method.
def unary_unary_multi_callable ( self , name ) :
""" Creates a UnaryUnaryMultiCallable for a unary-unary RPC method.
Args :
name : The RPC method name .
Returns :
A UnaryUnaryMultiCallable value for the named unary - unary RPC method .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def unary_stream_multi_callable ( self , name ) :
""" Creates a UnaryStreamMultiCallable for a unary-stream RPC method.
Args :
name : The RPC method name .
Returns :
A UnaryUnarySyncAsync value for the named unary - unary RPC method .
A UnaryStreamMultiCallable value for the name unary - stream RPC method .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def stream_unary_sync_async ( self , name ) :
""" Creates a StreamUnarySyncAsync value for a stream-unary RPC method.
def stream_unary_multi_callable ( self , name ) :
""" Creates a StreamUnaryMultiCallabl e for a stream-unary RPC method.
Args :
name : The RPC method name .
Returns :
A StreamUnarySyncAsync value for the named stream - unary RPC method .
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