| # Copyright 2015, 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. |
| |
| """Interfaces of GRPC.""" |
| |
| import abc |
| import enum |
| |
| import six |
| |
| # exceptions is referenced from specification in this module. |
| from grpc.framework.alpha import exceptions # pylint: disable=unused-import |
| from grpc.framework.foundation import activated |
| from grpc.framework.foundation import future |
| |
| |
| @enum.unique |
| class Cardinality(enum.Enum): |
| """Constants for the four cardinalities of RPC.""" |
| |
| UNARY_UNARY = 'request-unary/response-unary' |
| UNARY_STREAM = 'request-unary/response-streaming' |
| STREAM_UNARY = 'request-streaming/response-unary' |
| STREAM_STREAM = 'request-streaming/response-streaming' |
| |
| |
| @enum.unique |
| class Abortion(enum.Enum): |
| """Categories of RPC abortion.""" |
| |
| CANCELLED = 'cancelled' |
| EXPIRED = 'expired' |
| NETWORK_FAILURE = 'network failure' |
| SERVICED_FAILURE = 'serviced failure' |
| SERVICER_FAILURE = 'servicer failure' |
| |
| |
| class CancellableIterator(six.with_metaclass(abc.ABCMeta)): |
| """Implements the Iterator protocol and affords a cancel method.""" |
| |
| @abc.abstractmethod |
| def __iter__(self): |
| """Returns the self object in accordance with the Iterator protocol.""" |
| raise NotImplementedError() |
| |
| def __next__(self): |
| return self.next() |
| |
| @abc.abstractmethod |
| def next(self): |
| """Returns a value or raises StopIteration per the Iterator protocol.""" |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def cancel(self): |
| """Requests cancellation of whatever computation underlies this iterator.""" |
| raise NotImplementedError() |
| |
| |
| 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. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def add_abortion_callback(self, abortion_callback): |
| """Registers a callback to be called if the RPC is aborted. |
| Args: |
| abortion_callback: A callable to be called and passed an Abortion value |
| in the event of RPC abortion. |
| """ |
| raise NotImplementedError() |
| |
| |
| class UnaryUnarySyncAsync(six.with_metaclass(abc.ABCMeta)): |
| """Affords invoking a unary-unary RPC synchronously or asynchronously. |
| Values implementing this interface are directly callable and present an |
| "async" method. Both calls take a request value and a numeric timeout. |
| Direct invocation of a value of this type invokes its associated RPC and |
| blocks until the RPC's response is available. Calling the "async" method |
| of a value of this type invokes its associated RPC and immediately returns a |
| future.Future bound to the asynchronous execution of the RPC. |
| """ |
| |
| @abc.abstractmethod |
| def __call__(self, request, timeout): |
| """Synchronously invokes the underlying RPC. |
| Args: |
| request: The request value for the RPC. |
| timeout: A duration of time in seconds to allow for the RPC. |
| Returns: |
| The response value for the RPC. |
| Raises: |
| exceptions.RpcError: Indicating that the RPC was aborted. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def async(self, request, timeout): |
| """Asynchronously invokes the underlying RPC. |
| Args: |
| request: The request value for the RPC. |
| timeout: A duration of time in seconds to allow for the RPC. |
| Returns: |
| A future.Future representing the RPC. In the event of RPC completion, the |
| returned Future's result value will be the response value of the RPC. |
| In the event of RPC abortion, the returned Future's exception value |
| will be an exceptions.RpcError. |
| """ |
| raise NotImplementedError() |
| |
| |
| class StreamUnarySyncAsync(six.with_metaclass(abc.ABCMeta)): |
| """Affords invoking a stream-unary RPC synchronously or asynchronously. |
| Values implementing this interface are directly callable and present an |
| "async" method. Both calls take an iterator of request values and a numeric |
| timeout. Direct invocation of a value of this type invokes its associated RPC |
| and blocks until the RPC's response is available. Calling the "async" method |
| of a value of this type invokes its associated RPC and immediately returns a |
| future.Future bound to the asynchronous execution of the RPC. |
| """ |
| |
| @abc.abstractmethod |
| def __call__(self, request_iterator, timeout): |
| """Synchronously invokes the underlying RPC. |
| |
| Args: |
| request_iterator: An iterator that yields request values for the RPC. |
| timeout: A duration of time in seconds to allow for the RPC. |
| |
| Returns: |
| The response value for the RPC. |
| |
| Raises: |
| exceptions.RpcError: Indicating that the RPC was aborted. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def async(self, request_iterator, timeout): |
| """Asynchronously invokes the underlying RPC. |
| |
| Args: |
| request_iterator: An iterator that yields request values for the RPC. |
| timeout: A duration of time in seconds to allow for the RPC. |
| |
| Returns: |
| A future.Future representing the RPC. In the event of RPC completion, the |
| returned Future's result value will be the response value of the RPC. |
| In the event of RPC abortion, the returned Future's exception value |
| will be an exceptions.RpcError. |
| """ |
| raise NotImplementedError() |
| |
| |
| class RpcMethodDescription(six.with_metaclass(abc.ABCMeta)): |
| """A type for the common aspects of RPC method descriptions.""" |
| |
| @abc.abstractmethod |
| def cardinality(self): |
| """Identifies the cardinality of this RpcMethodDescription. |
| |
| Returns: |
| A Cardinality value identifying whether or not this |
| RpcMethodDescription is request-unary or request-streaming and |
| whether or not it is response-unary or response-streaming. |
| """ |
| raise NotImplementedError() |
| |
| |
| class RpcMethodInvocationDescription(six.with_metaclass(abc.ABCMeta, RpcMethodDescription)): |
| """Invocation-side description of an RPC method.""" |
| |
| @abc.abstractmethod |
| def serialize_request(self, request): |
| """Serializes a request value. |
| |
| Args: |
| request: A request value appropriate for the RPC method described by this |
| RpcMethodInvocationDescription. |
| |
| Returns: |
| The serialization of the given request value as a |
| bytestring. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def deserialize_response(self, serialized_response): |
| """Deserializes a response value. |
| |
| Args: |
| serialized_response: A bytestring that is the serialization of a response |
| value appropriate for the RPC method described by this |
| RpcMethodInvocationDescription. |
| |
| Returns: |
| A response value corresponding to the given bytestring. |
| """ |
| raise NotImplementedError() |
| |
| |
| class RpcMethodServiceDescription(six.with_metaclass(abc.ABCMeta, RpcMethodDescription)): |
| """Service-side description of an RPC method.""" |
| |
| @abc.abstractmethod |
| def deserialize_request(self, serialized_request): |
| """Deserializes a request value. |
| |
| Args: |
| serialized_request: A bytestring that is the serialization of a request |
| value appropriate for the RPC method described by this |
| RpcMethodServiceDescription. |
| |
| Returns: |
| A request value corresponding to the given bytestring. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def serialize_response(self, response): |
| """Serializes a response value. |
| |
| Args: |
| response: A response value appropriate for the RPC method described by |
| this RpcMethodServiceDescription. |
| |
| Returns: |
| The serialization of the given response value as a |
| bytestring. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def service_unary_unary(self, request, context): |
| """Carries out this RPC. |
| |
| This method may only be called if the cardinality of this |
| RpcMethodServiceDescription is Cardinality.UNARY_UNARY. |
| |
| Args: |
| request: A request value appropriate for the RPC method described by this |
| RpcMethodServiceDescription. |
| context: An RpcContext object for the RPC. |
| |
| Returns: |
| A response value appropriate for the RPC method described by this |
| RpcMethodServiceDescription. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def service_unary_stream(self, request, context): |
| """Carries out this RPC. |
| |
| This method may only be called if the cardinality of this |
| RpcMethodServiceDescription is Cardinality.UNARY_STREAM. |
| |
| Args: |
| request: A request value appropriate for the RPC method described by this |
| RpcMethodServiceDescription. |
| context: An RpcContext object for the RPC. |
| |
| Yields: |
| Zero or more response values appropriate for the RPC method described by |
| this RpcMethodServiceDescription. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def service_stream_unary(self, request_iterator, context): |
| """Carries out this RPC. |
| |
| This method may only be called if the cardinality of this |
| RpcMethodServiceDescription is Cardinality.STREAM_UNARY. |
| |
| Args: |
| request_iterator: An iterator of request values appropriate for the RPC |
| method described by this RpcMethodServiceDescription. |
| context: An RpcContext object for the RPC. |
| |
| Returns: |
| A response value appropriate for the RPC method described by this |
| RpcMethodServiceDescription. |
| """ |
| raise NotImplementedError() |
| |
| @abc.abstractmethod |
| def service_stream_stream(self, request_iterator, context): |
| """Carries out this RPC. |
| |
| This method may only be called if the cardinality of this |
| RpcMethodServiceDescription is Cardinality.STREAM_STREAM. |
| |
| Args: |
| request_iterator: An iterator of request values appropriate for the RPC |
| method described by this RpcMethodServiceDescription. |
| context: An RpcContext object for the RPC. |
| |
| Yields: |
| Zero or more response values appropriate for the RPC method described by |
| this RpcMethodServiceDescription. |
| """ |
| raise NotImplementedError() |
| |
| |
| class Stub(six.with_metaclass(abc.ABCMeta)): |
| """A stub with callable RPC method names for attributes. |
| |
| Instances of this type are context managers and only afford RPC invocation |
| when used in context. |
| |
| Instances of this type, when used in context, respond to attribute access |
| as follows: if the requested attribute is the name of a unary-unary RPC |
| method, the value of the attribute will be a UnaryUnarySyncAsync with which |
| to invoke the RPC method. If the requested attribute is the name of a |
| unary-stream RPC method, the value of the attribute will be a callable taking |
| a request object and a timeout parameter and returning a CancellableIterator |
| that yields the response values of the RPC. If the requested attribute is the |
| name of a stream-unary RPC method, the value of the attribute will be a |
| StreamUnarySyncAsync with which to invoke the RPC method. If the requested |
| attribute is the name of a stream-stream RPC method, the value of the |
| attribute will be a callable taking an iterator of request objects and a |
| timeout and returning a CancellableIterator that yields the response values |
| of the RPC. |
| |
| In all cases indication of abortion is indicated by raising of |
| exceptions.RpcError, exceptions.CancellationError, |
| and exceptions.ExpirationError. |
| """ |
| |
| |
| class Server(six.with_metaclass(abc.ABCMeta, activated.Activated)): |
| """A GRPC Server.""" |
| |
| @abc.abstractmethod |
| def port(self): |
| """Reports the port on which the server is serving. |
| |
| This method may only be called while the server is activated. |
| |
| Returns: |
| The port on which the server is serving. |
| """ |
| raise NotImplementedError() |