# 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 abc
import enum
import sys

import six

from 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:
        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()

    @abc.abstractmethod
    def cancelled(self):
        """Describes whether the computation was cancelled.

    This method does not block.

    Returns:
        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()

    @abc.abstractmethod
    def running(self):
        """Describes whether the computation is taking place.

    This method does not block.

    Returns:
        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()

    @abc.abstractmethod
    def done(self):
        """Describes whether the computation has taken place.

    This method does not block.

    Returns:
        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):
        """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. If None, the call will block until the
        computations's termination.

    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. If None, the call will block until the
        computations's termination.

    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. 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
        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.unique
class 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.
    SHUTDOWN: 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')
    SHUTDOWN = (_cygrpc.ConnectivityState.shutdown, 'shutdown')


@enum.unique
class 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.

    Returns:
      bool:
      True if RPC is active, False otherwise.
    """
        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:
      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()


#########################  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 sent by the server.

    This method blocks until the value is available.

    Returns:
      The initial :term:`metadata`.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def trailing_metadata(self):
        """Accesses the trailing metadata sent by the server.

    This method blocks until the value is available.

    Returns:
      The trailing :term:`metadata`.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def code(self):
        """Accesses the status code sent by the server.

    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 sent by the server.

    This method blocks until the value is available.

    Returns:
      The details string of the RPC.
    """
        raise NotImplementedError()


############  Authentication & Authorization Interfaces & Classes  #############


class ChannelCredentials(object):
    """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. For
  example, ssl_channel_credentials returns an instance, and secure_channel
  consumes an instance of this class.
  """

    def __init__(self, credentials):
        self._credentials = credentials


class CallCredentials(object):
    """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.

  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.
  """

    def __init__(self, credentials):
        self._credentials = credentials


class AuthMetadataContext(six.with_metaclass(abc.ABCMeta)):
    """Provides information to call credentials metadata plugins.

  Attributes:
    service_url: A string URL of the service being called into.
    method_name: A string of the fully qualified method name being called.
  """


class AuthMetadataPluginCallback(six.with_metaclass(abc.ABCMeta)):
    """Callback object received by a metadata plugin."""

    def __call__(self, metadata, error):
        """Inform the gRPC runtime of the metadata to construct a
           CallCredentials.

    Args:
      metadata: The :term:`metadata` used to construct the CallCredentials.
      error: An Exception to indicate error or None to indicate success.
    """
        raise NotImplementedError()


class AuthMetadataPlugin(six.with_metaclass(abc.ABCMeta)):
    """A specification for custom authentication."""

    def __call__(self, context, callback):
        """Implements authentication by passing metadata to a callback.

    Implementations of this method must not block.

    Args:
      context: An AuthMetadataContext providing information on the RPC that the
        plugin is being called to authenticate.
      callback: An AuthMetadataPluginCallback to be invoked either synchronously
        or asynchronously.
    """
        raise NotImplementedError()


class ServerCredentials(object):
    """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.
  """

    def __init__(self, credentials):
        self._credentials = credentials


########################  Multi-Callable Interfaces  ###########################


class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
    """Affords invoking a unary-unary RPC from client-side."""

    @abc.abstractmethod
    def __call__(self, request, timeout=None, metadata=None, credentials=None):
        """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: 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.

    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 with_call(self, request, timeout=None, metadata=None, credentials=None):
        """Synchronously invokes the underlying RPC.

    Args:
      request: The request value for the RPC.
      timeout: An optional durating of time in seconds to allow for the RPC.
      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 value for the RPC.

    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, credentials=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: 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
        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.
    """
        raise NotImplementedError()


class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
    """Affords invoking a unary-stream RPC from client-side."""

    @abc.abstractmethod
    def __call__(self, request, timeout=None, metadata=None, credentials=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.
               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
        values. Drawing response values from the returned Call-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 from client-side."""

    @abc.abstractmethod
    def __call__(self,
                 request_iterator,
                 timeout=None,
                 metadata=None,
                 credentials=None):
        """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.
               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.

    Raises:
      RpcError: Indicating that the RPC terminated with non-OK status. The
        raised RpcError will also implement grpc.Call, affording methods
        such as metadata, code, and details.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def with_call(self,
                  request_iterator,
                  timeout=None,
                  metadata=None,
                  credentials=None):
        """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 object for the RPC.

    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,
               credentials=None):
        """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
        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.
    """
        raise NotImplementedError()


class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
    """Affords invoking a stream-stream RPC on client-side."""

    @abc.abstractmethod
    def __call__(self,
                 request_iterator,
                 timeout=None,
                 metadata=None,
                 credentials=None):
        """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
        values. Drawing response values from the returned Call-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 on client-side."""

    @abc.abstractmethod
    def subscribe(self, callback, try_to_connect=False):
        """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 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 immediately. If set to False, gRPC runtime decides
        when to connect.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def unsubscribe(self, callback):
        """Unsubscribes a subscribed 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.
      request_serializer: Optional behaviour for serializing the request
        message. Request goes unserialized in case None is passed.
      response_deserializer: Optional behaviour for deserializing the response
        message. Response goes undeserialized in case None is passed.

    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.
      request_serializer: Optional behaviour for serializing the request
        message. Request goes unserialized in case None is passed.
      response_deserializer: Optional behaviour for deserializing the response
        message. Response goes undeserialized in case None is passed.

    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.
      request_serializer: Optional behaviour for serializing the request
        message. Request goes unserialized in case None is passed.
      response_deserializer: Optional behaviour for deserializing the response
        message. Response goes undeserialized in case None is passed.

    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.
      request_serializer: Optional behaviour for serializing the request
        message. Request goes unserialized in case None is passed.
      response_deserializer: Optional behaviour for deserializing the response
        message. Response goes undeserialized in case None is passed.

    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 sent by the client.

    Returns:
      The invocation :term:`metadata`.
    """
        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.
      The string format is determined by gRPC runtime.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def peer_identities(self):
        """Gets one or more peer identity(s).

      Equivalent to
      servicer_context.auth_context().get(
          servicer_context.peer_identity_key())

    Returns:
      An iterable of the identities, or None if the call is not authenticated.
      Each identity is returned as a raw bytes type.
     """
        raise NotImplementedError()

    @abc.abstractmethod
    def peer_identity_key(self):
        """The auth property used to identify the peer.

    For example, "x509_common_name" or "x509_subject_alternative_name" are
    used to identify an SSL peer.

    Returns:
      The auth property (string) that indicates the
      peer identity, or None if the call is not authenticated.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def auth_context(self):
        """Gets the auth context for the call.

      Returns:
        A map of strings to an iterable of bytes for each auth property.
      """
        raise NotImplementedError()

    @abc.abstractmethod
    def send_initial_metadata(self, initial_metadata):
        """Sends the initial metadata value to the client.

    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`.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def set_trailing_metadata(self, trailing_metadata):
        """Sends the trailing metadata for the RPC.

    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`.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def set_code(self, code):
        """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 object to be sent to the client.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def set_details(self, details):
        """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: An arbitrary string to be sent to the client upon completion.
    """
        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 :term:`metadata` sent by the client.
  """


class GenericRpcHandler(six.with_metaclass(abc.ABCMeta)):
    """An implementation of arbitrarily many RPC methods."""

    @abc.abstractmethod
    def service(self, handler_call_details):
        """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 if the
      implementation chooses to service this RPC, or None otherwise.
    """
        raise NotImplementedError()


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.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 service's name.

    Returns:
      The service name.
    """
        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.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def add_insecure_port(self, address):
        """Opens an insecure port for accepting RPCs.

    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:
      integer:
      An integer port on which server will accept RPC requests.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def add_secure_port(self, address, server_credentials):
        """Opens a secure port for accepting RPCs.

    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.
      server_credentials: A ServerCredentials object.

    Returns:
      integer:
      An integer port on which server will accept RPC requests.
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def start(self):
        """Starts this Server.

    This method may only be called once. (i.e. it is not idempotent).
    """
        raise NotImplementedError()

    @abc.abstractmethod
    def stop(self, grace):
        """Stops this Server.

    This method 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 aborted.

    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 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.

    Returns:
      A threading.Event that will be set when this Server has completely
      stopped, i.e. when running RPCs either complete or are aborted and
      all handlers have terminated.
    """
        raise NotImplementedError()


#################################  Functions    ################################


def unary_unary_rpc_method_handler(behavior,
                                   request_deserializer=None,
                                   response_serializer=None):
    """Creates an RpcMethodHandler for a unary-unary RPC method.

  Args:
    behavior: The implementation of an RPC that accepts one request and returns
    one response.
    request_deserializer: An optional behavior for request deserialization.
    response_serializer: An optional behavior for response serialization.

  Returns:
    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,
                                       response_serializer, behavior, None,
                                       None, None)


def unary_stream_rpc_method_handler(behavior,
                                    request_deserializer=None,
                                    response_serializer=None):
    """Creates an RpcMethodHandler for a unary-stream RPC method.

  Args:
    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 object that is typically used by grpc.Server.
  """
    from grpc import _utilities  # pylint: disable=cyclic-import
    return _utilities.RpcMethodHandler(False, True, request_deserializer,
                                       response_serializer, None, behavior,
                                       None, None)


def stream_unary_rpc_method_handler(behavior,
                                    request_deserializer=None,
                                    response_serializer=None):
    """Creates an RpcMethodHandler for a stream-unary RPC method.

  Args:
    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 object that is typically used by grpc.Server.
  """
    from grpc import _utilities  # pylint: disable=cyclic-import
    return _utilities.RpcMethodHandler(True, False, request_deserializer,
                                       response_serializer, None, None,
                                       behavior, None)


def stream_stream_rpc_method_handler(behavior,
                                     request_deserializer=None,
                                     response_serializer=None):
    """Creates an RpcMethodHandler for a stream-stream RPC method.

  Args:
    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 object that is typically used by grpc.Server.
  """
    from grpc import _utilities  # pylint: disable=cyclic-import
    return _utilities.RpcMethodHandler(True, True, request_deserializer,
                                       response_serializer, None, None, None,
                                       behavior)


def method_handlers_generic_handler(service, method_handlers):
    """Creates a GenericRpcHandler from RpcMethodHandlers.

  Args:
    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. 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)


def ssl_channel_credentials(root_certificates=None,
                            private_key=None,
                            certificate_chain=None):
    """Creates a ChannelCredentials for use with an SSL-enabled Channel.

  Args:
    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.
  """
    if private_key is not None or certificate_chain is not None:
        pair = _cygrpc.SslPemKeyCertPair(private_key, certificate_chain)
    else:
        pair = None
    return ChannelCredentials(
        _cygrpc.channel_credentials_ssl(root_certificates, pair))


def metadata_call_credentials(metadata_plugin, name=None):
    """Construct CallCredentials from an AuthMetadataPlugin.

  Args:
    metadata_plugin: An AuthMetadataPlugin to use for authentication.
    name: An optional name for the plugin.

  Returns:
    A CallCredentials.
  """
    from grpc import _plugin_wrapping  # pylint: disable=cyclic-import
    if name is None:
        try:
            effective_name = metadata_plugin.__name__
        except AttributeError:
            effective_name = metadata_plugin.__class__.__name__
    else:
        effective_name = name
    return CallCredentials(
        _plugin_wrapping.call_credentials_metadata_plugin(metadata_plugin,
                                                          effective_name))


def access_token_call_credentials(access_token):
    """Construct CallCredentials from an access token.

  Args:
    access_token: A string to place directly in the http request
      authorization header, for example
      "authorization: Bearer <access_token>".

  Returns:
    A CallCredentials.
  """
    from grpc import _auth  # pylint: disable=cyclic-import
    return metadata_call_credentials(
        _auth.AccessTokenCallCredentials(access_token))


def composite_call_credentials(*call_credentials):
    """Compose multiple CallCredentials to make a new CallCredentials.

  Args:
    *call_credentials: At least two CallCredentials objects.

  Returns:
    A CallCredentials object composed of the given CallCredentials objects.
  """
    from grpc import _credential_composition  # pylint: disable=cyclic-import
    cygrpc_call_credentials = tuple(
        single_call_credentials._credentials
        for single_call_credentials in call_credentials)
    return CallCredentials(
        _credential_composition.call(cygrpc_call_credentials))


def composite_channel_credentials(channel_credentials, *call_credentials):
    """Compose a ChannelCredentials and one or more CallCredentials objects.

  Args:
    channel_credentials: A ChannelCredentials object.
    *call_credentials: One or more CallCredentials objects.

  Returns:
    A ChannelCredentials composed of the given ChannelCredentials and
    CallCredentials objects.
  """
    from grpc import _credential_composition  # pylint: disable=cyclic-import
    cygrpc_call_credentials = tuple(
        single_call_credentials._credentials
        for single_call_credentials in call_credentials)
    return ChannelCredentials(
        _credential_composition.channel(channel_credentials._credentials,
                                        cygrpc_call_credentials))


def ssl_server_credentials(private_key_certificate_chain_pairs,
                           root_certificates=None,
                           require_client_auth=False):
    """Creates a ServerCredentials for use with an SSL-enabled Server.

  Args:
    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. Typically, this
    object is an argument to add_secure_port() method during server setup.
  """
    if len(private_key_certificate_chain_pairs) == 0:
        raise ValueError(
            'At least one private key-certificate chain pair is required!')
    elif require_client_auth and root_certificates is None:
        raise ValueError(
            'Illegal to require client auth without providing root certificates!'
        )
    else:
        return ServerCredentials(
            _cygrpc.server_credentials_ssl(root_certificates, [
                _cygrpc.SslPemKeyCertPair(key, pem)
                for key, pem in private_key_certificate_chain_pairs
            ], require_client_auth))


def channel_ready_future(channel):
    """Creates a Future that tracks when a Channel is ready.

  Cancelling the Future does not affect the channel's state machine.
  It merely decouples the Future from channel state machine.

  Args:
    channel: A Channel object.

  Returns:
    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)


def insecure_channel(target, options=None):
    """Creates an insecure Channel to a server.

  Args:
    target: The server address
    options: An optional list of key-value pairs (channel args in gRPC runtime)
    to configure the channel.

  Returns:
    A Channel object.
  """
    from grpc import _channel  # pylint: disable=cyclic-import
    return _channel.Channel(target, () if options is None else options, None)


def secure_channel(target, credentials, options=None):
    """Creates a secure Channel to a server.

  Args:
    target: The server address.
    credentials: A ChannelCredentials instance.
    options: An optional list of key-value pairs (channel args in gRPC runtime)
    to configure the channel.

  Returns:
    A Channel object.
  """
    from grpc import _channel  # pylint: disable=cyclic-import
    return _channel.Channel(target, () if options is None else options,
                            credentials._credentials)


def server(thread_pool,
           handlers=None,
           options=None,
           maximum_concurrent_rpcs=None):
    """Creates a Server with which RPCs can be serviced.

  Args:
    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 RESOURCE_EXHAUSTED status, or None to
      indicate no limit.

  Returns:
    A Server object.
  """
    from grpc import _server  # pylint: disable=cyclic-import
    return _server.Server(thread_pool, () if handlers is None else handlers, ()
                          if options is None else options,
                          maximum_concurrent_rpcs)


###################################  __all__  #################################

__all__ = ('FutureTimeoutError', 'FutureCancelledError', 'Future',
           'ChannelConnectivity', 'StatusCode', 'RpcError', 'RpcContext',
           'Call', 'ChannelCredentials', 'CallCredentials',
           'AuthMetadataContext', 'AuthMetadataPluginCallback',
           'AuthMetadataPlugin', 'ServerCredentials', 'UnaryUnaryMultiCallable',
           'UnaryStreamMultiCallable', 'StreamUnaryMultiCallable',
           'StreamStreamMultiCallable', 'Channel', 'ServicerContext',
           'RpcMethodHandler', 'HandlerCallDetails', 'GenericRpcHandler',
           'ServiceRpcHandler', 'Server', 'unary_unary_rpc_method_handler',
           'unary_stream_rpc_method_handler', 'stream_unary_rpc_method_handler',
           'stream_stream_rpc_method_handler',
           'method_handlers_generic_handler', 'ssl_channel_credentials',
           'metadata_call_credentials', 'access_token_call_credentials',
           'composite_call_credentials', 'composite_channel_credentials',
           'ssl_server_credentials', 'channel_ready_future', 'insecure_channel',
           'secure_channel', 'server',)

############################### Extension Shims ################################

# Here to maintain backwards compatibility; avoid using these in new code!
try:
    import grpc_tools
    sys.modules.update({'grpc.tools': grpc_tools})
except ImportError:
    pass
try:
    import grpc_health
    sys.modules.update({'grpc.health': grpc_health})
except ImportError:
    pass
try:
    import grpc_reflection
    sys.modules.update({'grpc.reflection': grpc_reflection})
except ImportError:
    pass
