| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789 | # Copyright 2015-2016, Google Inc.# All rights reserved.## Redistribution and use in source and binary forms, with or without# modification, are permitted provided that the following conditions are# met:##     * Redistributions of source code must retain the above copyright# notice, this list of conditions and the following disclaimer.#     * Redistributions in binary form must reproduce the above# copyright notice, this list of conditions and the following disclaimer# in the documentation and/or other materials provided with the# distribution.#     * Neither the name of Google Inc. nor the names of its# contributors may be used to endorse or promote products derived from# this software without specific prior written permission.## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."""gRPC's Python API."""__import__('pkg_resources').declare_namespace(__name__)import abcimport enumimport sixfrom grpc._cython import cygrpc as _cygrpc############################## Future Interface  ###############################class FutureTimeoutError(Exception):  """Indicates that a method call on a Future timed out."""class FutureCancelledError(Exception):  """Indicates that the computation underlying a Future was cancelled."""class Future(six.with_metaclass(abc.ABCMeta)):  """A representation of a computation in another control flow.  Computations represented by a Future may be yet to be begun, may be ongoing,  or may have already completed.  """  @abc.abstractmethod  def cancel(self):    """Attempts to cancel the computation.    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.    """    raise NotImplementedError()  @abc.abstractmethod  def cancelled(self):    """Describes whether the computation was cancelled.    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.    """    raise NotImplementedError()  @abc.abstractmethod  def running(self):    """Describes whether the computation is taking place.    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.    """    raise NotImplementedError()  @abc.abstractmethod  def done(self):    """Describes whether the computation has taken place.    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.    """    raise NotImplementedError()  @abc.abstractmethod  def result(self, timeout=None):    """Accesses the outcome 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.    Returns:      The return value of the computation.    Raises:      FutureTimeoutError: If a timeout value is passed and the computation does        not terminate within the allotted time.      FutureCancelledError: If the computation was cancelled.      Exception: If the computation raised an exception, this call will raise        the same exception.    """    raise NotImplementedError()  @abc.abstractmethod  def exception(self, timeout=None):    """Return the exception raised by the computation.    This method may return immediately or may block.    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.    Returns:      The exception raised by the computation, or None if the computation did        not raise an exception.    Raises:      FutureTimeoutError: If a timeout value is passed and the computation does        not terminate within the allotted time.      FutureCancelledError: If the computation was cancelled.    """    raise NotImplementedError()  @abc.abstractmethod  def traceback(self, timeout=None):    """Access the traceback of the exception raised by the computation.    This method may return immediately or may block.    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.    Returns:      The traceback of the exception raised by the computation, or None if the        computation did not raise an exception.    Raises:      FutureTimeoutError: If a timeout value is passed and the computation does        not terminate within the allotted time.      FutureCancelledError: If the computation was cancelled.    """    raise NotImplementedError()  @abc.abstractmethod  def add_done_callback(self, fn):    """Adds a function to be called at completion of the computation.    The callback will be passed this Future object describing the outcome of    the computation.    If the computation has already completed, the callback will be called    immediately.    Args:      fn: A callable taking this Future object as its single parameter.    """    raise NotImplementedError()################################  gRPC Enums  ##################################@enum.uniqueclass ChannelConnectivity(enum.Enum):  """Mirrors grpc_connectivity_state in the gRPC Core.  Attributes:    IDLE: The channel is idle.    CONNECTING: The channel is connecting.    READY: The channel is ready to conduct RPCs.    TRANSIENT_FAILURE: The channel has seen a failure from which it expects to      recover.    FATAL_FAILURE: The channel has seen a failure from which it cannot recover.  """  IDLE              = (_cygrpc.ConnectivityState.idle, 'idle')  CONNECTING        = (_cygrpc.ConnectivityState.connecting, 'connecting')  READY             = (_cygrpc.ConnectivityState.ready, 'ready')  TRANSIENT_FAILURE = (      _cygrpc.ConnectivityState.transient_failure, 'transient failure')  FATAL_FAILURE     = (_cygrpc.ConnectivityState.fatal_failure, 'fatal failure')@enum.uniqueclass StatusCode(enum.Enum):  """Mirrors grpc_status_code in the gRPC Core."""  OK                  = (_cygrpc.StatusCode.ok, 'ok')  CANCELLED           = (_cygrpc.StatusCode.cancelled, 'cancelled')  UNKNOWN             = (_cygrpc.StatusCode.unknown, 'unknown')  INVALID_ARGUMENT    = (      _cygrpc.StatusCode.invalid_argument, 'invalid argument')  DEADLINE_EXCEEDED   = (      _cygrpc.StatusCode.deadline_exceeded, 'deadline exceeded')  NOT_FOUND           = (_cygrpc.StatusCode.not_found, 'not found')  ALREADY_EXISTS      = (_cygrpc.StatusCode.already_exists, 'already exists')  PERMISSION_DENIED   = (      _cygrpc.StatusCode.permission_denied, 'permission denied')  RESOURCE_EXHAUSTED  = (      _cygrpc.StatusCode.resource_exhausted, 'resource exhausted')  FAILED_PRECONDITION = (      _cygrpc.StatusCode.failed_precondition, 'failed precondition')  ABORTED             = (_cygrpc.StatusCode.aborted, 'aborted')  OUT_OF_RANGE        = (_cygrpc.StatusCode.out_of_range, 'out of range')  UNIMPLEMENTED       = (_cygrpc.StatusCode.unimplemented, 'unimplemented')  INTERNAL            = (_cygrpc.StatusCode.internal, 'internal')  UNAVAILABLE         = (_cygrpc.StatusCode.unavailable, 'unavailable')  DATA_LOSS           = (_cygrpc.StatusCode.data_loss, 'data loss')  UNAUTHENTICATED     = (_cygrpc.StatusCode.unauthenticated, 'unauthenticated')#############################  gRPC Exceptions  ################################class RpcError(Exception):  """Raised by the gRPC library to indicate non-OK-status RPC termination."""##############################  Shared Context  ################################class RpcContext(six.with_metaclass(abc.ABCMeta)):  """Provides RPC-related information and action."""  @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, or None if no deadline was specified for the RPC.    """    raise NotImplementedError()  @abc.abstractmethod  def cancel(self):    """Cancels the RPC.    Idempotent and has no effect if the RPC has already terminated.    """    raise NotImplementedError()  @abc.abstractmethod  def add_callback(self, callback):    """Registers a callback to be called on RPC termination.    Args:      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        already terminated or some other reason).    """    raise NotImplementedError()#########################  Invocation-Side Context  ############################class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):  """Invocation-side utility object for an RPC."""  @abc.abstractmethod  def initial_metadata(self):    """Accesses the initial metadata from the service-side of the RPC.    This method blocks until the value is available.    Returns:      The initial metadata as a sequence of pairs of bytes.    """    raise NotImplementedError()  @abc.abstractmethod  def trailing_metadata(self):    """Accesses the trailing metadata from the service-side of the RPC.    This method blocks until the value is available.    Returns:      The trailing metadata as a sequence of pairs of bytes.    """    raise NotImplementedError()  @abc.abstractmethod  def code(self):    """Accesses the status code emitted by the service-side of the RPC.    This method blocks until the value is available.    Returns:      The StatusCode value for the RPC.    """    raise NotImplementedError()  @abc.abstractmethod  def details(self):    """Accesses the details value emitted by the service-side of the RPC.    This method blocks until the value is available.    Returns:      The bytes of the details of the RPC.    """    raise NotImplementedError()########################  Multi-Callable Interfaces  ###########################class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):  """Affords invoking a unary-unary RPC."""  @abc.abstractmethod  def __call__(self, request, timeout=None, metadata=None, with_call=False):    """Synchronously invokes the underlying RPC.    Args:      request: The request value for the RPC.      timeout: An optional duration of time in seconds to allow for the RPC.      metadata: An optional sequence of pairs of bytes to be transmitted to the        service-side of the RPC.      with_call: Whether or not to include return a Call for the RPC in addition        to the response.    Returns:      The response value for the RPC, and a Call for the RPC if with_call was        set to True at invocation.    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's        metadata, status code, and details.    """    raise NotImplementedError()  @abc.abstractmethod  def future(self, request, timeout=None, metadata=None):    """Asynchronously invokes the underlying RPC.    Args:      request: The request value for the RPC.      timeout: An optional duration of time in seconds to allow for the RPC.      metadata: An optional sequence of pairs of bytes to be transmitted to the        service-side of the RPC.    Returns:      An object that is both a Call for the RPC and a Future. In the event of        RPC completion, the return Future's result value will be the response        message of the RPC. Should the event terminate with non-OK status, the        returned Future's exception value will be an RpcError.    """    raise NotImplementedError()class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):  """Affords invoking a unary-stream RPC."""  @abc.abstractmethod  def __call__(self, request, timeout=None, metadata=None):    """Invokes the underlying RPC.    Args:      request: The request value for the RPC.      timeout: An optional duration of time in seconds to allow for the RPC.      metadata: An optional sequence of pairs of bytes to be transmitted to the        service-side of the RPC.    Returns:      An object that is both a Call for the RPC and an iterator of response        values. Drawing response values from the returned iterator may raise        RpcError indicating termination of the RPC with non-OK status.    """    raise NotImplementedError()class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):  """Affords invoking a stream-unary RPC in any call style."""  @abc.abstractmethod  def __call__(      self, request_iterator, timeout=None, metadata=None, with_call=False):    """Synchronously invokes the underlying RPC.    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.      metadata: An optional sequence of pairs of bytes to be transmitted to the        service-side of the RPC.      with_call: Whether or not to include return a Call for the RPC in addition        to the response.    Returns:      The response value for the RPC, and a Call for the RPC if with_call was        set to True at invocation.    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's        metadata, status code, and details.    """    raise NotImplementedError()  @abc.abstractmethod  def future(self, request_iterator, timeout=None, metadata=None):    """Asynchronously invokes the underlying RPC.    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.      metadata: An optional sequence of pairs of bytes to be transmitted to the        service-side of the RPC.    Returns:      An object that is both a Call for the RPC and a Future. In the event of        RPC completion, the return Future's result value will be the response        message of the RPC. Should the event terminate with non-OK status, the        returned Future's exception value will be an RpcError.    """    raise NotImplementedError()class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):  """Affords invoking a stream-stream RPC in any call style."""  @abc.abstractmethod  def __call__(self, request_iterator, timeout=None, metadata=None):    """Invokes the underlying RPC.    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.      metadata: An optional sequence of pairs of bytes to be transmitted to the        service-side of the RPC.    Returns:      An object that is both a Call for the RPC and an iterator of response        values. Drawing response values from the returned iterator may raise        RpcError indicating termination of the RPC with non-OK status.    """    raise NotImplementedError()#############################  Channel Interface  ##############################class Channel(six.with_metaclass(abc.ABCMeta)):  """Affords RPC invocation via generic methods."""  @abc.abstractmethod  def subscribe(self, callback, try_to_connect=False):    """Subscribes to this Channel's connectivity.    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        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.    """    raise NotImplementedError()  @abc.abstractmethod  def unsubscribe(self, callback):    """Unsubscribes a callback from this Channel's connectivity.    Args:      callback: A callable previously registered with this Channel from having        been passed to its "subscribe" method.    """    raise NotImplementedError()  @abc.abstractmethod  def unary_unary(      self, method, request_serializer=None, response_deserializer=None):    """Creates a UnaryUnaryMultiCallable for a unary-unary method.    Args:      method: The name of the RPC method.    Returns:      A UnaryUnaryMultiCallable value for the named unary-unary method.    """    raise NotImplementedError()  @abc.abstractmethod  def unary_stream(      self, method, request_serializer=None, response_deserializer=None):    """Creates a UnaryStreamMultiCallable for a unary-stream method.    Args:      method: The name of the RPC method.    Returns:      A UnaryStreamMultiCallable value for the name unary-stream method.    """    raise NotImplementedError()  @abc.abstractmethod  def stream_unary(      self, method, request_serializer=None, response_deserializer=None):    """Creates a StreamUnaryMultiCallable for a stream-unary method.    Args:      method: The name of the RPC method.    Returns:      A StreamUnaryMultiCallable value for the named stream-unary method.    """    raise NotImplementedError()  @abc.abstractmethod  def stream_stream(      self, method, request_serializer=None, response_deserializer=None):    """Creates a StreamStreamMultiCallable for a stream-stream method.    Args:      method: The name of the RPC method.    Returns:      A StreamStreamMultiCallable value for the named stream-stream method.    """    raise NotImplementedError()##########################  Service-Side Context  ##############################class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):  """A context object passed to method implementations."""  @abc.abstractmethod  def invocation_metadata(self):    """Accesses the metadata from the invocation-side of the RPC.    Returns:      The invocation metadata object as a sequence of pairs of bytes.    """    raise NotImplementedError()  @abc.abstractmethod  def peer(self):    """Identifies the peer that invoked the RPC being serviced.    Returns:      A string identifying the peer that invoked the RPC being serviced.    """    raise NotImplementedError()  @abc.abstractmethod  def send_initial_metadata(self, initial_metadata):    """Sends the initial metadata value to the invocation-side of the RPC.    This method need not be called by method implementations if they have no    service-side initial metadata to transmit.    Args:      initial_metadata: The initial metadata of the RPC as a sequence of pairs        of bytes.    """    raise NotImplementedError()  @abc.abstractmethod  def set_trailing_metadata(self, trailing_metadata):    """Accepts the trailing metadata value of the RPC.    This method need not be called by method implementations if they have no    service-side trailing metadata to transmit.    Args:      trailing_metadata: The trailing metadata of the RPC as a sequence of pairs        of bytes.    """    raise NotImplementedError()  @abc.abstractmethod  def set_code(self, code):    """Accepts the status code of the RPC.    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: The integer status code of the RPC to be transmitted to the        invocation side of the RPC.    """    raise NotImplementedError()  @abc.abstractmethod  def set_details(self, details):    """Accepts the service-side details of the RPC.    This method need not be called by method implementations if they have no    details to transmit.    Args:      details: The details bytes of the RPC to be transmitted to        the invocation side of the RPC.    """    raise NotImplementedError()#####################  Service-Side Handler Interfaces  ########################class RpcMethodHandler(six.with_metaclass(abc.ABCMeta)):  """An implementation of a single RPC method.  Attributes:    request_streaming: Whether the RPC supports exactly one request message or      any arbitrary number of request messages.    response_streaming: Whether the RPC supports exactly one response message or      any arbitrary number of response messages.    request_deserializer: A callable behavior that accepts a byte string and      returns an object suitable to be passed to this object's business logic,      or None to indicate that this object's business logic should be passed the      raw request bytes.    response_serializer: A callable behavior that accepts an object produced by      this object's business logic and returns a byte string, or None to      indicate that the byte strings produced by this object's business logic      should be transmitted on the wire as they are.    unary_unary: This object's application-specific business logic as a callable      value that takes a request value and a ServicerContext object and returns      a response value. Only non-None if both request_streaming and      response_streaming are False.    unary_stream: This object's application-specific business logic as a      callable value that takes a request value and a ServicerContext object and      returns an iterator of response values. Only non-None if request_streaming      is False and response_streaming is True.    stream_unary: This object's application-specific business logic as a      callable value that takes an iterator of request values and a      ServicerContext object and returns a response value. Only non-None if      request_streaming is True and response_streaming is False.    stream_stream: This object's application-specific business logic as a      callable value that takes an iterator of request values and a      ServicerContext object and returns an iterator of response values. Only      non-None if request_streaming and response_streaming are both True.  """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 metadata from the invocation side of the RPC.  """class GenericRpcHandler(six.with_metaclass(abc.ABCMeta)):  """An implementation of arbitrarily many RPC methods."""  @abc.abstractmethod  def service(self, handler_call_details):    """Services an RPC (or not).    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.    """    raise NotImplementedError()#############################  Server Interface  ###############################class Server(six.with_metaclass(abc.ABCMeta)):  """Services RPCs."""  @abc.abstractmethod  def add_generic_rpc_handlers(self, generic_rpc_handlers):    """Registers GenericRpcHandlers with this Server.    This method is only safe to call before the server is started.    Args:      generic_rpc_handlers: An iterable of GenericRpcHandlers that will be used        to service RPCs after this Server is started.    """    raise NotImplementedError()  @abc.abstractmethod  def add_insecure_port(self, address):    """Reserves a port for insecure RPC service once this Server becomes active.    This method may only be called before calling this Server's start method is    called.    Args:      address: The address for which to open 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.    """    raise NotImplementedError()  @abc.abstractmethod  def start(self):    """Starts this Server's service of RPCs.    This method may only be called while the server is not serving RPCs (i.e. it    is not idempotent).    """    raise NotImplementedError()  @abc.abstractmethod  def stop(self, grace):    """Stops this Server's service of RPCs.    All calls to this method immediately stop service of new RPCs. When existing    RPCs are aborted is controlled by the grace period parameter passed to this    method.    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.    Args:      grace: A duration of time in seconds to allow existing RPCs to complete        before being aborted by this Server's stopping. If None, this method        will block until the server is completely stopped.    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).    """    raise NotImplementedError()
 |