New abort with grpc.Status API

* Add `abort_with_status` method in ServicerContext
* Add `Status` interface similar to the design of Details in interceptor
* Add 3 unit test cases for abort mechanism

2 files changed, 40 insertions, 0 deletions

diff --git a/src/python/grpcio/grpc/__init__.py b/src/python/grpcio/grpc/__init__.py
index 6022fc3ef2..441f4ac813 100644
--- a/src/python/grpcio/grpc/__init__.py
+++ b/src/python/grpcio/grpc/__init__.py
@@ -266,6 +266,23 @@ class StatusCode(enum.Enum):
     UNAUTHENTICATED = (_cygrpc.StatusCode.unauthenticated, 'unauthenticated')
 
 
+#############################  gRPC Status  ################################
+
+
+class Status(six.with_metaclass(abc.ABCMeta)):
+    """Describes the status of an RPC.
+
+    This is an EXPERIMENTAL API.
+
+    Attributes:
+      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.
+      trailing_metadata: The trailing :term:`metadata` in the RPC.
+    """
+
+
 #############################  gRPC Exceptions  ################################
 
 
@@ -1119,6 +1136,24 @@ class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
         raise NotImplementedError()
 
     @abc.abstractmethod
+    def abort_with_status(self, status):
+        """Raises an exception to terminate the RPC with a non-OK status.
+
+        The status passed as argument will supercede any existing status code,
+        status message and trailing metadata.
+
+        This is an EXPERIMENTAL API.
+
+        Args:
+          status: A grpc.Status object.
+
+        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.
 
@@ -1747,6 +1782,7 @@ __all__ = (
     'Future',
     'ChannelConnectivity',
     'StatusCode',
+    'Status',
     'RpcError',
     'RpcContext',
     'Call',
diff --git a/src/python/grpcio/grpc/_server.py b/src/python/grpcio/grpc/_server.py
index e939f615df..3bbfa47da5 100644
--- a/src/python/grpcio/grpc/_server.py
+++ b/src/python/grpcio/grpc/_server.py
@@ -291,6 +291,10 @@ class _Context(grpc.ServicerContext):
             self._state.abortion = Exception()
             raise self._state.abortion
 
+    def abort_with_status(self, status):
+        self._state.trailing_metadata = status.trailing_metadata
+        self.abort(status.code, status.details)
+
     def set_code(self, code):
         with self._state.condition:
             self._state.code = code