@ -61,13 +61,12 @@ class Future(six.with_metaclass(abc.ABCMeta)):
This method does not block .
Returns :
True if the computation has not yet begun , will not be allowed to take
place , and determination of both was possible without blocking . False
under all other circumstances including but not limited to the
computation ' s already having begun, the computation ' s already having
finished , and the computation ' s having been scheduled for execution on a
remote system for which a determination of whether or not it commenced
before being cancelled cannot be made without blocking .
bool :
Returns True if the computation was canceled .
Returns False under all other circumstances , for example :
1. computation has begun and could not be canceled .
2. computation has finished
3. computation is scheduled for execution and it is impossible to determine its state without blocking .
"""
raise NotImplementedError ( )
@ -78,10 +77,12 @@ class Future(six.with_metaclass(abc.ABCMeta)):
This method does not block .
Returns :
True if the computation was cancelled any time before its result became
immediately available . False under all other circumstances including but
not limited to this object ' s cancel method not having been called and
the computation ' s result having become immediately available.
bool :
Returns True if the computation was cancelled before its result became
available .
False under all other circumstances , for example :
1. computation was not cancelled .
2. computation ' s result is available.
"""
raise NotImplementedError ( )
@ -92,9 +93,10 @@ class Future(six.with_metaclass(abc.ABCMeta)):
This method does not block .
Returns :
True if the computation is scheduled to take place in the future or is
taking place now , or False if the computation took place in the past or
was cancelled .
bool :
Returns True if the computation is scheduled for execution or currently
executing .
Returns False if the computation already executed or was cancelled .
"""
raise NotImplementedError ( )
@ -105,22 +107,24 @@ class Future(six.with_metaclass(abc.ABCMeta)):
This method does not block .
Returns :
True if the computation is known to have either completed or have been
unscheduled or interrupted . False if the computation may possibly be
executing or scheduled to execute later .
bool :
Returns True if the computation already executed or was cancelled .
Returns False if the computation is scheduled for execution or currently
executing .
This is exactly opposite of the running ( ) method ' s result.
"""
raise NotImplementedError ( )
@abc . abstractmethod
def result ( self , timeout = None ) :
""" Accesses the outcome of the computation or raises its exception.
""" Returns the result of the computation or raises its exception.
This method may return immediately or may block .
Args :
timeout : The length of time in seconds to wait for the computation to
finish or be cancelled , or None if this method should block until the
computation has finished or is cancelled no matter how long that takes .
finish or be cancelled . If None , the call will block until the computations ' s
termination .
Returns :
The return value of the computation .
@ -142,12 +146,11 @@ class Future(six.with_metaclass(abc.ABCMeta)):
Args :
timeout : The length of time in seconds to wait for the computation to
terminate or be cancelled , or None if this method should block until
the computation is terminated or is cancelled no matter how long that
takes .
terminate or be cancelled . If None , the call will block until the computations ' s
termination .
Returns :
The exception raised by the computation , or None if the computation did
The exception raised by the computation , or None if the computation did
not raise an exception .
Raises :
@ -165,12 +168,11 @@ class Future(six.with_metaclass(abc.ABCMeta)):
Args :
timeout : The length of time in seconds to wait for the computation to
terminate or be cancelled , or None if this method should block until
the computation is terminated or is cancelled no matter how long that
takes .
terminate or be cancelled . If None , the call will block until the
computations ' s termination.
Returns :
The traceback of the exception raised by the computation , or None if the
The traceback of the exception raised by the computation , or None if the
computation did not raise an exception .
Raises :
@ -260,7 +262,12 @@ class RpcContext(six.with_metaclass(abc.ABCMeta)):
@abc . abstractmethod
def is_active ( self ) :
""" Describes whether the RPC is active or has terminated. """
""" Describes whether the RPC is active or has terminated.
Returns :
bool :
True if RPC is active , False otherwise .
"""
raise NotImplementedError ( )
@abc . abstractmethod
@ -290,8 +297,9 @@ class RpcContext(six.with_metaclass(abc.ABCMeta)):
callback : A no - parameter callable to be called on RPC termination .
Returns :
True if the callback was added and will be called later ; False if the
callback was not added and will not later be called ( because the RPC
bool :
True if the callback was added and will be called later ; False if the
callback was not added and will not be called ( because the RPC
already terminated or some other reason ) .
"""
raise NotImplementedError ( )
@ -305,7 +313,7 @@ class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def initial_metadata ( self ) :
""" Accesses the initial metadata from the service-side of the RPC .
""" Accesses the initial metadata sent by the server .
This method blocks until the value is available .
@ -316,7 +324,7 @@ class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def trailing_metadata ( self ) :
""" Accesses the trailing metadata from the service-side of the RPC .
""" Accesses the trailing metadata sent by the server .
This method blocks until the value is available .
@ -327,7 +335,7 @@ class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def code ( self ) :
""" Accesses the status code emitted by the service-side of the RPC .
""" Accesses the status code sent by the server .
This method blocks until the value is available .
@ -338,7 +346,7 @@ class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def details ( self ) :
""" Accesses the details value emitted by the service-side of the RPC .
""" Accesses the details sent by the server .
This method blocks until the value is available .
@ -352,10 +360,12 @@ class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):
class ChannelCredentials ( object ) :
""" A value encapsulating the data required to create a secure Channel.
""" An encapsulation of the data required to create a secure Channel.
This class has no supported interface - it exists to define the type of its
instances and its instances exist to be passed to other functions .
instances and its instances exist to be passed to other functions . For example ,
ssl_channel_credentials returns an instance , and secure_channel consumes an
instance of this class .
"""
def __init__ ( self , credentials ) :
@ -363,7 +373,7 @@ class ChannelCredentials(object):
class CallCredentials ( object ) :
""" A value encapsulating data asserting an identity over a channel.
""" An encapsulation of the data required to assert an identity over a channel.
A CallCredentials may be composed with ChannelCredentials to always assert
identity for every call over that Channel .
@ -416,7 +426,7 @@ class AuthMetadataPlugin(six.with_metaclass(abc.ABCMeta)):
class ServerCredentials ( object ) :
""" A value encapsulating the data required to open a secure port on a Server.
""" An encapsulation of the data required to open a secure port on a Server.
This class has no supported interface - it exists to define the type of its
instances and its instances exist to be passed to other functions .
@ -430,7 +440,7 @@ class ServerCredentials(object):
class UnaryUnaryMultiCallable ( six . with_metaclass ( abc . ABCMeta ) ) :
""" Affords invoking a unary-unary RPC. """
""" Affords invoking a unary-unary RPC from client-side . """
@abc . abstractmethod
def __call__ ( self , request , timeout = None , metadata = None , credentials = None ) :
@ -486,7 +496,7 @@ class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
credentials : An optional CallCredentials for the RPC .
Returns :
An object that is both a Call for the RPC and a Future . In the event of
An object that is both a Call for the RPC and a Future . In the event of
RPC completion , the return Call - Future ' s result value will be the
response message of the RPC . Should the event terminate with non - OK
status , the returned Call - Future ' s exception value will be an RpcError.
@ -495,7 +505,7 @@ class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
class UnaryStreamMultiCallable ( six . with_metaclass ( abc . ABCMeta ) ) :
""" Affords invoking a unary-stream RPC. """
""" Affords invoking a unary-stream RPC from client-side . """
@abc . abstractmethod
def __call__ ( self , request , timeout = None , metadata = None , credentials = None ) :
@ -504,12 +514,13 @@ class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
Args :
request : The request value for the RPC .
timeout : An optional duration of time in seconds to allow for the RPC .
If None , the timeout is considered infinite .
metadata : An optional : term : ` metadata ` to be transmitted to the
service - side of the RPC .
credentials : An optional CallCredentials for the RPC .
Returns :
An object that is both a Call for the RPC and an iterator of response
An object that is both a Call for the RPC and an iterator of response
values . Drawing response values from the returned Call - iterator may
raise RpcError indicating termination of the RPC with non - OK status .
"""
@ -517,7 +528,7 @@ class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
class StreamUnaryMultiCallable ( six . with_metaclass ( abc . ABCMeta ) ) :
""" Affords invoking a stream-unary RPC in any call styl e. """
""" Affords invoking a stream-unary RPC from client-sid e. """
@abc . abstractmethod
def __call__ ( self ,
@ -530,6 +541,7 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
Args :
request_iterator : An iterator that yields request values for the RPC .
timeout : An optional duration of time in seconds to allow for the RPC .
If None , the timeout is considered infinite .
metadata : Optional : term : ` metadata ` to be transmitted to the
service - side of the RPC .
credentials : An optional CallCredentials for the RPC .
@ -539,8 +551,8 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
Raises :
RpcError : Indicating that the RPC terminated with non - OK status . The
raised RpcError will also be a Call for the RPC affording the RPC '
metadata , status code , and details .
raised RpcError will also implement grpc . Call , affording method s
such as metadata , code , and details .
"""
raise NotImplementedError ( )
@ -550,17 +562,18 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
timeout = None ,
metadata = None ,
credentials = None ) :
""" Synchronously invokes the underlying RPC.
""" Synchronously invokes the underlying RPC on the client .
Args :
request_iterator : An iterator that yields request values for the RPC .
timeout : An optional duration of time in seconds to allow for the RPC .
If None , the timeout is considered infinite .
metadata : Optional : term : ` metadata ` to be transmitted to the
service - side of the RPC .
credentials : An optional CallCredentials for the RPC .
Returns :
The response value for the RPC and a Call for the RPC .
The response value for the RPC and a Call object for the RPC .
Raises :
RpcError : Indicating that the RPC terminated with non - OK status . The
@ -575,17 +588,18 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
timeout = None ,
metadata = None ,
credentials = None ) :
""" Asynchronously invokes the underlying RPC.
""" Asynchronously invokes the underlying RPC on the client .
Args :
request_iterator : An iterator that yields request values for the RPC .
timeout : An optional duration of time in seconds to allow for the RPC .
If None , the timeout is considered infinite .
metadata : Optional : term : ` metadata ` to be transmitted to the
service - side of the RPC .
credentials : An optional CallCredentials for the RPC .
Returns :
An object that is both a Call for the RPC and a Future . In the event of
An object that is both a Call for the RPC and a Future . In the event of
RPC completion , the return Call - Future ' s result value will be the
response message of the RPC . Should the event terminate with non - OK
status , the returned Call - Future ' s exception value will be an RpcError.
@ -594,7 +608,7 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
class StreamStreamMultiCallable ( six . with_metaclass ( abc . ABCMeta ) ) :
""" Affords invoking a stream-stream RPC in any call styl e. """
""" Affords invoking a stream-stream RPC on client-sid e. """
@abc . abstractmethod
def __call__ ( self ,
@ -602,17 +616,18 @@ class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
timeout = None ,
metadata = None ,
credentials = None ) :
""" Invokes the underlying RPC.
""" Invokes the underlying RPC on the client .
Args :
request_iterator : An iterator that yields request values for the RPC .
timeout : An optional duration of time in seconds to allow for the RPC .
if not specified the timeout is considered infinite .
metadata : Optional : term : ` metadata ` to be transmitted to the
service - side of the RPC .
credentials : An optional CallCredentials for the RPC .
Returns :
An object that is both a Call for the RPC and an iterator of response
An object that is both a Call for the RPC and an iterator of response
values . Drawing response values from the returned Call - iterator may
raise RpcError indicating termination of the RPC with non - OK status .
"""
@ -623,27 +638,32 @@ class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
class Channel ( six . with_metaclass ( abc . ABCMeta ) ) :
""" Affords RPC invocation via generic methods. """
""" Affords RPC invocation via generic methods on client-side . """
@abc . abstractmethod
def subscribe ( self , callback , try_to_connect = False ) :
""" Subscribes to this Channel ' s connectivity.
""" Subscribe to this Channel ' s connectivity state machine.
A Channel may be in any of the states described by ChannelConnectivity .
This method allows application to monitor the state transitions .
The typical use case is to debug or gain better visibility into gRPC
runtime ' s state.
Args :
callback : A callable to be invoked and passed a ChannelConnectivity value
describing this Channel ' s connectivity. The callable will be invoked
immediately upon subscription and again for every change to this
Channel ' s connectivity thereafter until it is unsubscribed or this
callback : A callable to be invoked with ChannelConnectivity argument .
ChannelConnectivity describes current state of the channel .
The callable will be invoked immediately upon subscription and again for
every change to ChannelConnectivity until it is unsubscribed or this
Channel object goes out of scope .
try_to_connect : A boolean indicating whether or not this Channel should
attempt to connect if it is not already connected and ready to conduct
RPCs .
attempt to connect immediately . If set to False , gRPC runtime decides
when to connect .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def unsubscribe ( self , callback ) :
""" Unsubscribes a callback from this Channel ' s connectivity.
""" Unsubscribes a subscribed callback from this Channel ' s connectivity.
Args :
callback : A callable previously registered with this Channel from having
@ -736,7 +756,7 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def invocation_metadata ( self ) :
""" Accesses the metadata from the invocation-side of the RPC .
""" Accesses the metadata from the sent by the client .
Returns :
The invocation : term : ` metadata ` .
@ -749,15 +769,16 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
Returns :
A string identifying the peer that invoked the RPC being serviced .
The string format is determined by gRPC runtime .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def send_initial_metadata ( self , initial_metadata ) :
""" Sends the initial metadata value to the invocation-side of the RPC .
""" Sends the initial metadata value to the client .
This method need not be called by method implementations if they have no
service - side initial metadata to transmit .
This method need not be called by implementations if they have no
metadata to add to what the gRPC runtime will transmit .
Args :
initial_metadata : The initial : term : ` metadata ` .
@ -766,10 +787,10 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def set_trailing_metadata ( self , trailing_metadata ) :
""" Accepts the trailing metadata value of the RPC.
""" Sends the trailing metadata for the RPC.
This method need not be called by method implementations if they have no
service - side trailing metadata to transmit .
This method need not be called by implementations if they have no
metadata to add to what the gRPC runtime will transmit .
Args :
trailing_metadata : The trailing : term : ` metadata ` .
@ -778,27 +799,25 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
@abc . abstractmethod
def set_code ( self , code ) :
""" Accepts the status code of the RPC .
""" Sets the value to be used as status code upon RPC completion .
This method need not be called by method implementations if they wish the
gRPC runtime to determine the status code of the RPC .
Args :
code : A StatusCode value to be transmitted to the invocation side of the
RPC as the status code of the RPC .
code : A StatusCode object to be sent to the client .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def set_details ( self , details ) :
""" Accepts the service-side details of the RPC .
""" Sets the value to be used as detail string upon RPC completion .
This method need not be called by method implementations if they have no
details to transmit .
Args :
details : A string to be transmitted to the invocation side of the RPC as
the status details of the RPC .
details : An arbitrary string to be sent to the client upon completion .
"""
raise NotImplementedError ( )
@ -845,7 +864,7 @@ class HandlerCallDetails(six.with_metaclass(abc.ABCMeta)):
""" Describes an RPC that has just arrived for service.
Attributes :
method : The method name of the RPC .
invocation_metadata : The : term : ` metadata ` from the invocation side of the RPC .
invocation_metadata : The : term : ` metadata ` sent by the client .
"""
@ -854,14 +873,14 @@ class GenericRpcHandler(six.with_metaclass(abc.ABCMeta)):
@abc . abstractmethod
def service ( self , handler_call_details ) :
""" Services an RPC (or not) .
""" Returns the handler for servicing the RPC .
Args :
handler_call_details : A HandlerCallDetails describing the RPC .
Returns :
An RpcMethodHandler with which the RPC may be serviced , or None to
indicate that this object will not be servicing the RPC .
An RpcMethodHandler with which the RPC may be serviced if the implementation
chooses to service this RPC , or None otherwise .
"""
raise NotImplementedError ( )
@ -870,15 +889,15 @@ class ServiceRpcHandler(six.with_metaclass(abc.ABCMeta, GenericRpcHandler)):
""" An implementation of RPC methods belonging to a service.
A service handles RPC methods with structured names of the form
' /Service.Name/Service.MethodX ' , where ' Service.Name ' is the value
returned by service_name ( ) , and ' Service.MethodX ' is the servic e method
name . A service can have multiple service methods names , but only a single
' /Service.Name/Service.Method ' , where ' Service.Name ' is the value
returned by service_name ( ) , and ' Service.Method ' is the method
name . A service can have multiple method names , but only a single
service name .
"""
@abc . abstractmethod
def service_name ( self ) :
""" Returns this services name.
""" Returns this service '
Returns :
The service name .
@ -900,88 +919,78 @@ class Server(six.with_metaclass(abc.ABCMeta)):
Args :
generic_rpc_handlers : An iterable of GenericRpcHandlers that will be used
to service RPCs after this Server is started .
to service RPCs .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def add_insecure_port ( self , address ) :
""" Reserves a port for insecure RPC service once this Server becomes active .
""" Opens an insecure port for accepting RPCs .
This method may only be called before calling this Server ' s start method is
called .
This method may only be called before starting the server .
Args :
address : The address for which to open a port .
if the port is 0 , or not specified in the address , then gRPC runtime
will choose a port .
Returns :
An integer port on which RPCs will be serviced after this link has been
started . This is typically the same number as the port number contained
in the passed address , but will likely be different if the port number
contained in the passed address was zero .
integer :
An integer port on which server will accept RPC requests .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def add_secure_port ( self , address , server_credentials ) :
""" Reserves a port for secure RPC service after this Server becomes active .
""" Opens a secure port for accepting RPCs .
This method may only be called before calling this Server ' s start method is
called .
This method may only be called before starting the server .
Args :
address : The address for which to open a port .
server_credentials : A ServerCredentials .
if the port is 0 , or not specified in the address , then gRPC runtime
will choose a port .
server_credentials : A ServerCredentials object .
Returns :
An integer port on which RPCs will be serviced after this link has been
started . This is typically the same number as the port number contained
in the passed address , but will likely be different if the port number
contained in the passed address was zero .
integer :
An integer port on which server will accept RPC requests .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def start ( self ) :
""" Starts this Server ' s service of RPCs .
""" Starts this Server.
This method may only be called while the server is not serving RPCs ( i . e . it
is not idempotent ) .
This method may only be called once . ( i . e . it is not idempotent ) .
"""
raise NotImplementedError ( )
@abc . abstractmethod
def stop ( self , grace ) :
""" Stops this Server ' s service of RPCs .
""" Stops this Server.
All calls to t hismethod immediately stop service of new RPCs . When existing
RPCs are aborted is controlled by the grace period parameter passed to this
metho d.
T hismethod immediately stop service of new RPCs in all cases .
If a grace period is specified , this method returns immediately
and all RPCs active at the end of the grace period are aborte d.
This method may be called at any time and is idempotent . Passing a smaller
grace value than has been passed in a previous call will have the effect of
stopping the Server sooner . Passing a larger grace value than has been
passed in a previous call will not have the effect of stopping the server
later .
If a grace period is not specified , then all existing RPCs are
teriminated immediately and the this method blocks until the last
RPC handler terminates .
This method does not block for any significant length of time . If None is
passed as the grace value , existing RPCs are immediately aborted and this
method blocks until this Server is completely stopped .
This method is idempotent and may be called at any time . Passing a smaller
grace value in subsequentcall will have the effect of stopping the Server
sooner . Passing a larger grace value in subsequent call * will not * have the
effect of stopping the server later ( i . e . the most restrictive grace
value is used ) .
Args :
grace : A duration of time in seconds or None . If a duration of time in
seconds , the time to allow existing RPCs to complete before being
aborted by this Server ' s stopping. If None, all RPCs will be aborted
immediately and this method will block until this Server is completely
stopped .
grace : A duration of time in seconds or None .
Returns :
A threading . Event that will be set when this Server has completely
stopped . The returned event may not be set until after the full grace
period ( if some ongoing RPC continues for the full length of the period )
of it may be set much sooner ( such as if this Server had no RPCs underway
at the time it was stopped or if all RPCs that it had underway completed
very early in the grace period ) .
stopped , i . e . when running RPCs either complete or are aborted and
all handlers have terminated .
"""
raise NotImplementedError ( )
@ -995,14 +1004,13 @@ def unary_unary_rpc_method_handler(behavior,
""" Creates an RpcMethodHandler for a unary-unary RPC method.
Args :
behavior : The implementation of an RPC method as a callable behavior taking
a single request value a nd returning a singl eresponse valu e .
request_deserializer : An optional request deserialization behavior .
response_serializer : An optional response serialization behavior .
behavior : The implementation of an RPC that accepts one request and returns
o neresponse .
request_deserializer : An optional behavior for request deserialization .
response_serializer : An optional behavior for response serialization .
Returns :
An RpcMethodHandler for a unary - unary RPC method constructed from the given
parameters .
An RpcMethodHandler object that is typically used by grpc . Server .
"""
from grpc import _utilities # pylint: disable=cyclic-import
return _utilities . RpcMethodHandler ( False , False , request_deserializer ,
@ -1016,14 +1024,13 @@ def unary_stream_rpc_method_handler(behavior,
""" Creates an RpcMethodHandler for a unary-stream RPC method.
Args :
behavior : The implementation of an RPC method as a callable behavior taking
a single request value and returning a n iterator of response values .
request_deserializer : An optional request deserialization behavior .
response_serializer : An optional response serialization behavior .
behavior : The implementation of an RPC that accepts one request and returns
an iterator of response values .
request_deserializer : An optional behavior for request deserialization .
response_serializer : An optional behavior for response serialization .
Returns :
An RpcMethodHandler for a unary - stream RPC method constructed from the
given parameters .
An RpcMethodHandler object that is typically used by grpc . Server .
"""
from grpc import _utilities # pylint: disable=cyclic-import
return _utilities . RpcMethodHandler ( False , True , request_deserializer ,
@ -1037,14 +1044,13 @@ def stream_unary_rpc_method_handler(behavior,
""" Creates an RpcMethodHandler for a stream-unary RPC method.
Args :
behavior : The implementation of an RPC method as a callable behavior taking
an iterator of request values and returning a single response value .
request_deserializer : An optional request deserialization behavior .
response_serializer : An optional response serialization behavior .
behavior : The implementation of an RPC that accepts an iterator of request
values and returns a single response value .
request_deserializer : An optional behavior for request deserialization .
response_serializer : An optional behavior for response serialization .
Returns :
An RpcMethodHandler for a stream - unary RPC method constructed from the
given parameters .
An RpcMethodHandler object that is typically used by grpc . Server .
"""
from grpc import _utilities # pylint: disable=cyclic-import
return _utilities . RpcMethodHandler ( True , False , request_deserializer ,
@ -1058,15 +1064,13 @@ def stream_stream_rpc_method_handler(behavior,
""" Creates an RpcMethodHandler for a stream-stream RPC method.
Args :
behavior : The implementation of an RPC method as a callable behavior taking
an iterator of request values and returning an iterator of response
values .
request_deserializer : An optional request deserialization behavior .
response_serializer : An optional response serialization behavior .
behavior : The implementation of an RPC that accepts an iterator of request
values and returns an iterator of response values .
request_deserializer : An optional behavior for request deserialization .
response_serializer : An optional behavior for response serialization .
Returns :
An RpcMethodHandler for a stream - stream RPC method constructed from the
given parameters .
An RpcMethodHandler object that is typically used by grpc . Server .
"""
from grpc import _utilities # pylint: disable=cyclic-import
return _utilities . RpcMethodHandler ( True , True , request_deserializer ,
@ -1075,15 +1079,16 @@ def stream_stream_rpc_method_handler(behavior,
def method_handlers_generic_handler ( service , method_handlers ) :
""" Creates a grpc. GenericRpcHandler from RpcMethodHandlers.
""" Creates a GenericRpcHandler from RpcMethodHandlers.
Args :
service : A service name to be used for the given method handlers .
method_handlers : A dictionary from method name to RpcMethodHandler
implementing the named method .
service : The name of the service that is implemented by the method_ handlers.
method_handlers : A dictionary that maps method names to corresponding
RpcMethodHandler .
Returns :
A GenericRpcHandler constructed from the given parameters .
A GenericRpcHandler . This is typically added to the grpc . Server object
with add_generic_rpc_handlers ( ) before starting the server .
"""
from grpc import _utilities # pylint: disable=cyclic-import
return _utilities . DictionaryGenericHandler ( service , method_handlers )
@ -1095,12 +1100,12 @@ def ssl_channel_credentials(root_certificates=None,
""" Creates a ChannelCredentials for use with an SSL-enabled Channel.
Args :
root_certificates : The PEM - encoded root certificates or unset to ask for
them to be retrieved from a default location .
private_key : The PEM - encoded private key to use or unset if no private key
should be used .
certificate_chain : The PEM - encoded certificate chain to use or unset if no
certificate chain should be used .
root_certificates : The PEM - encoded root certificates as a byte string ,
or None to retrieve them from a default location chosen by gRPC runtime .
private_key : The PEM - encoded private key as a byte string , or None if no
private key should be used .
certificate_chain : The PEM - encoded certificate chain as a byte string
to use or or None if no certificate chain should be used .
Returns :
A ChannelCredentials for use with an SSL - enabled Channel .
@ -1117,9 +1122,8 @@ def metadata_call_credentials(metadata_plugin, name=None):
""" Construct CallCredentials from an AuthMetadataPlugin.
Args :
metadata_plugin : An AuthMetadataPlugin to use as the authentication behavior
in the created CallCredentials .
name : A name for the plugin .
metadata_plugin : An AuthMetadataPlugin to use for authentication .
name : An optional name for the plugin .
Returns :
A CallCredentials .
@ -1142,7 +1146,8 @@ def access_token_call_credentials(access_token):
Args :
access_token : A string to place directly in the http request
authorization header , ie " authorization: Bearer <access_token> " .
authorization header , for example
" authorization: Bearer <access_token> " .
Returns :
A CallCredentials .
@ -1173,12 +1178,12 @@ def composite_channel_credentials(channel_credentials, *call_credentials):
""" Compose a ChannelCredentials and one or more CallCredentials objects.
Args :
channel_credentials : A ChannelCredentials .
channel_credentials : A ChannelCredentials object .
* call_credentials : One or more CallCredentials objects .
Returns :
A ChannelCredentials composed of the given ChannelCredentials and
CallCredentials objects .
CallCredentials objects .
"""
from grpc import _credential_composition # pylint: disable=cyclic-import
cygrpc_call_credentials = tuple (
@ -1195,18 +1200,18 @@ def ssl_server_credentials(private_key_certificate_chain_pairs,
""" Creates a ServerCredentials for use with an SSL-enabled Server.
Args :
private_key_certificate_chain_pairs : A nonempty sequence each element of
which is a pair the first element of which is a PEM - encoded private key
and the second element of which is the corresponding PEM - encoded
certificate chain .
root_certificates : PEM - encoded client root certificates to be used for
verifying authenticated clients . If omitted , require_client_auth must also
be omitted or be False .
require_client_auth : A boolean indicating whether or not to require clients
to be authenticated . May only be True if root_certificates is not None .
private_key_certificate_chain_pairs : A list of pairs of the form
[ PEM - encoded private key , PEM - encoded certificate chain ] .
root_certificates : An optional byte string of PEM - encoded client root
certificates that the server will use to verify client authentication .
If omitted , require_client_auth must also be False .
require_client_auth : A boolean indicating whether or not to require
clients to be authenticated . May only be True if root_certificates
is not None .
Returns :
A ServerCredentials for use with an SSL - enabled Server .
A ServerCredentials for use with an SSL - enabled Server . Typically , this
object is an argument to add_secure_port ( ) method during server setup .
"""
if len ( private_key_certificate_chain_pairs ) == 0 :
raise ValueError (
@ -1224,18 +1229,17 @@ def ssl_server_credentials(private_key_certificate_chain_pairs,
def channel_ready_future ( channel ) :
""" Creates a Future tracking when a Channel is ready.
""" Creates a Future that tracks when a Channel is ready.
Cancelling the returned Future does not tell the given Channel to abandon
attempts it may have been making to connect ; cancelling merely deactivates the
returned Future ' s subscription to the given Channel ' s connectivity .
Cancelling the Future does not affect the channel ' s state machine.
It merely decouples the Future from channel state machine .
Args :
channel : A Channel .
channel : A Channel object .
Returns :
A Future that matures when the given Channel has connectivity
ChannelConnectivity . READY .
A Future object that matures when the channel connectivity is
ChannelConnectivity . READY .
"""
from grpc import _utilities # pylint: disable=cyclic-import
return _utilities . channel_ready_future ( channel )
@ -1245,12 +1249,12 @@ def insecure_channel(target, options=None):
""" Creates an insecure Channel to a server.
Args :
target : The target to which to connect .
options : A sequence of string - value pairs according to which to configure
the created channel .
target : The server address
options : An optional list of key - value pairs ( channel args in gRPC runtime )
to configure the channel .
Returns :
A Channel t o the target through which RPCs may be condu cted .
A Channel obj ect .
"""
from grpc import _channel # pylint: disable=cyclic-import
return _channel . Channel ( target , ( ) if options is None else options , None )
@ -1260,13 +1264,13 @@ def secure_channel(target, credentials, options=None):
""" Creates a secure Channel to a server.
Args :
target : The target to which to connect .
target : The server address .
credentials : A ChannelCredentials instance .
options : A sequence of string - value pairs according to which to configure
the created channel .
options : An optional list of key - value pairs ( channel args in gRPC runtime )
to configure the channel .
Returns :
A Channel t o the target through which RPCs may be condu cted .
A Channel obj ect .
"""
from grpc import _channel # pylint: disable=cyclic-import
return _channel . Channel ( target , ( ) if options is None else options ,
@ -1280,21 +1284,19 @@ def server(thread_pool,
""" Creates a Server with which RPCs can be serviced.
Args :
thread_pool : A futures . ThreadPoolExecutor to be used by the returned Server
to service RPCs .
handlers : An optional sequence of GenericRpcHandlers to be used to service
RPCs after the returned Server is started . These handlers need not be the
only handlers the server will use to service RPCs ; other handlers may
later be added by calling add_generic_rpc_handlers any time before the
returned Server is started .
options : A sequence of string - value pairs according to which to configure
the created server .
thread_pool : A futures . ThreadPoolExecutor to be used by the Server
to execute RPC handlers .
handlers : An optional list of GenericRpcHandlers used for executing RPCs .
More handlers may be added by calling add_generic_rpc_handlers any time
before the server is started .
options : An optional list of key - value pairs ( channel args in gRPC runtime )
to configure the channel .
maximum_concurrent_rpcs : The maximum number of concurrent RPCs this server
will service before returning status RESOURCE_EXHAUSTED , or None to
will service before returning RESOURCE_EXHAUSTED status , or None to
indicate no limit .
Returns :
A Server with which RPCs can be serviced .
A Server object .
"""
from grpc import _server # pylint: disable=cyclic-import
return _server . Server ( thread_pool , ( ) if handlers is None else handlers , ( )
Yuxuan Li
8 years ago