Merge pull request #25383 from gnossen/fix_grpc_future_docs

Clarify Guarantees about grpc.Future Interface

src/python/grpcio/grpc/__init__.py

@@ -489,7 +489,8 @@ class UnaryStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
             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.
+            the RPC with non-OK status. This object *should* also fulfill the
+            Future interface, though it may not.
         """
         raise NotImplementedError()
 
@@ -562,7 +563,8 @@ class StreamStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
           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.
+          the RPC with non-OK status. This object *should* also fulfill the
+          Future interface, though it may not.
         """
         raise NotImplementedError()
 
@@ -797,10 +799,10 @@ class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
             grpc.compression.Gzip. This is an EXPERIMENTAL option.
 
         Returns:
-            An object that is both a Call for the RPC and an iterator of
+            An object that is a Call for the RPC, an iterator of response
-            response values. Drawing response values from the returned
+            values, and a Future for the RPC. Drawing response values from the
-            Call-iterator may raise RpcError indicating termination of the
+            returned Call-iterator may raise RpcError indicating termination of
-            RPC with non-OK status.
+            the RPC with non-OK status.
         """
         raise NotImplementedError()
 
@@ -936,10 +938,10 @@ class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
             grpc.compression.Gzip. This is an EXPERIMENTAL option.
 
         Returns:
-            An object that is both a Call for the RPC and an iterator of
+            An object that is a Call for the RPC, an iterator of response
-            response values. Drawing response values from the returned
+            values, and a Future for the RPC. Drawing response values from the
-            Call-iterator may raise RpcError indicating termination of the
+            returned Call-iterator may raise RpcError indicating termination of
-            RPC with non-OK status.
+            the RPC with non-OK status.
         """
         raise NotImplementedError()