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