Introduce ServicerContext.abort to abort an RPC

gRPC Python required RPCs terminating with non-OK status code to still
return a valid response value after calling set_code, even though the
response value was not supposed to be communicated to the client, and
returning None is considered a programming error.

This commit introduces an alternative mechanism to terminate RPCs by
calling the `abort` method on `ServicerContext` passed to the handler,
which raises an exception and signals to the gRPC runtime to abort the
RPC with the specified status code and details.

1 files changed, 30 insertions, 10 deletions

diff --git a/src/python/grpcio/grpc/__init__.py b/src/python/grpcio/grpc/__init__.py
index 564772527e..0f6bdfc1c2 100644
--- a/src/python/grpcio/grpc/__init__.py
+++ b/src/python/grpcio/grpc/__init__.py
@@ -835,27 +835,47 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
         raise NotImplementedError()
 
     @abc.abstractmethod
+    def abort(self, code, details):
+        """Raises an exception to terminate the RPC with a non-OK status.
+
+        The code and details passed as arguments will supercede any existing
+        ones.
+
+        Args:
+          code: A StatusCode object to be sent to the client.
+            It must not be StatusCode.OK.
+          details: An ASCII-encodable string to be sent to the client upon
+            termination of the RPC.
+
+        Raises:
+          Exception: An exception is always raised to signal the abortion the
+            RPC to the gRPC runtime.
+        """
+        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.
+        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.
-    """
+        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.
+        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.
-    """
+        Args:
+          details: An ASCII-encodable string to be sent to the client upon
+            termination of the RPC.
+        """
         raise NotImplementedError()