Renamed google.protobuf to protobuf26

third_party/google/protobuf/service.py

-# Protocol Buffers - Google's data interchange format
-# Copyright 2008 Google Inc.  All rights reserved.
-# http://code.google.com/p/protobuf/
-#
-# 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.
-
-"""DEPRECATED:  Declares the RPC service interfaces.
-
-This module declares the abstract interfaces underlying proto2 RPC
-services.  These are intended to be independent of any particular RPC
-implementation, so that proto2 services can be used on top of a variety
-of implementations.  Starting with version 2.3.0, RPC implementations should
-not try to build on these, but should instead provide code generator plugins
-which generate code specific to the particular RPC implementation.  This way
-the generated code can be more appropriate for the implementation in use
-and can avoid unnecessary layers of indirection.
-"""
-
-__author__ = 'petar@google.com (Petar Petrov)'
-
-
-class RpcException(Exception):
-  """Exception raised on failed blocking RPC method call."""
-  pass
-
-
-class Service(object):
-
-  """Abstract base interface for protocol-buffer-based RPC services.
-
-  Services themselves are abstract classes (implemented either by servers or as
-  stubs), but they subclass this base interface. The methods of this
-  interface can be used to call the methods of the service without knowing
-  its exact type at compile time (analogous to the Message interface).
-  """
-
-  def GetDescriptor():
-    """Retrieves this service's descriptor."""
-    raise NotImplementedError
-
-  def CallMethod(self, method_descriptor, rpc_controller,
-                 request, done):
-    """Calls a method of the service specified by method_descriptor.
-
-    If "done" is None then the call is blocking and the response
-    message will be returned directly.  Otherwise the call is asynchronous
-    and "done" will later be called with the response value.
-
-    In the blocking case, RpcException will be raised on error.
-
-    Preconditions:
-    * method_descriptor.service == GetDescriptor
-    * request is of the exact same classes as returned by
-      GetRequestClass(method).
-    * After the call has started, the request must not be modified.
-    * "rpc_controller" is of the correct type for the RPC implementation being
-      used by this Service.  For stubs, the "correct type" depends on the
-      RpcChannel which the stub is using.
-
-    Postconditions:
-    * "done" will be called when the method is complete.  This may be
-      before CallMethod() returns or it may be at some point in the future.
-    * If the RPC failed, the response value passed to "done" will be None.
-      Further details about the failure can be found by querying the
-      RpcController.
-    """
-    raise NotImplementedError
-
-  def GetRequestClass(self, method_descriptor):
-    """Returns the class of the request message for the specified method.
-
-    CallMethod() requires that the request is of a particular subclass of
-    Message. GetRequestClass() gets the default instance of this required
-    type.
-
-    Example:
-      method = service.GetDescriptor().FindMethodByName("Foo")
-      request = stub.GetRequestClass(method)()
-      request.ParseFromString(input)
-      service.CallMethod(method, request, callback)
-    """
-    raise NotImplementedError
-
-  def GetResponseClass(self, method_descriptor):
-    """Returns the class of the response message for the specified method.
-
-    This method isn't really needed, as the RpcChannel's CallMethod constructs
-    the response protocol message. It's provided anyway in case it is useful
-    for the caller to know the response type in advance.
-    """
-    raise NotImplementedError
-
-
-class RpcController(object):
-
-  """An RpcController mediates a single method call.
-
-  The primary purpose of the controller is to provide a way to manipulate
-  settings specific to the RPC implementation and to find out about RPC-level
-  errors. The methods provided by the RpcController interface are intended
-  to be a "least common denominator" set of features which we expect all
-  implementations to support.  Specific implementations may provide more
-  advanced features (e.g. deadline propagation).
-  """
-
-  # Client-side methods below
-
-  def Reset(self):
-    """Resets the RpcController to its initial state.
-
-    After the RpcController has been reset, it may be reused in
-    a new call. Must not be called while an RPC is in progress.
-    """
-    raise NotImplementedError
-
-  def Failed(self):
-    """Returns true if the call failed.
-
-    After a call has finished, returns true if the call failed.  The possible
-    reasons for failure depend on the RPC implementation.  Failed() must not
-    be called before a call has finished.  If Failed() returns true, the
-    contents of the response message are undefined.
-    """
-    raise NotImplementedError
-
-  def ErrorText(self):
-    """If Failed is true, returns a human-readable description of the error."""
-    raise NotImplementedError
-
-  def StartCancel(self):
-    """Initiate cancellation.
-
-    Advises the RPC system that the caller desires that the RPC call be
-    canceled.  The RPC system may cancel it immediately, may wait awhile and
-    then cancel it, or may not even cancel the call at all.  If the call is
-    canceled, the "done" callback will still be called and the RpcController
-    will indicate that the call failed at that time.
-    """
-    raise NotImplementedError
-
-  # Server-side methods below
-
-  def SetFailed(self, reason):
-    """Sets a failure reason.
-
-    Causes Failed() to return true on the client side.  "reason" will be
-    incorporated into the message returned by ErrorText().  If you find
-    you need to return machine-readable information about failures, you
-    should incorporate it into your response protocol buffer and should
-    NOT call SetFailed().
-    """
-    raise NotImplementedError
-
-  def IsCanceled(self):
-    """Checks if the client cancelled the RPC.
-
-    If true, indicates that the client canceled the RPC, so the server may
-    as well give up on replying to it.  The server should still call the
-    final "done" callback.
-    """
-    raise NotImplementedError
-
-  def NotifyOnCancel(self, callback):
-    """Sets a callback to invoke on cancel.
-
-    Asks that the given callback be called when the RPC is canceled.  The
-    callback will always be called exactly once.  If the RPC completes without
-    being canceled, the callback will be called after completion.  If the RPC
-    has already been canceled when NotifyOnCancel() is called, the callback
-    will be called immediately.
-
-    NotifyOnCancel() must be called no more than once per request.
-    """
-    raise NotImplementedError
-
-
-class RpcChannel(object):
-
-  """Abstract interface for an RPC channel.
-
-  An RpcChannel represents a communication line to a service which can be used
-  to call that service's methods.  The service may be running on another
-  machine. Normally, you should not use an RpcChannel directly, but instead
-  construct a stub {@link Service} wrapping it.  Example:
-
-  Example:
-    RpcChannel channel = rpcImpl.Channel("remotehost.example.com:1234")
-    RpcController controller = rpcImpl.Controller()
-    MyService service = MyService_Stub(channel)
-    service.MyMethod(controller, request, callback)
-  """
-
-  def CallMethod(self, method_descriptor, rpc_controller,
-                 request, response_class, done):
-    """Calls the method identified by the descriptor.
-
-    Call the given method of the remote service.  The signature of this
-    procedure looks the same as Service.CallMethod(), but the requirements
-    are less strict in one important way:  the request object doesn't have to
-    be of any specific class as long as its descriptor is method.input_type.
-    """
-    raise NotImplementedError