import enum
import logging
import sys
-import six
-from grpc._cython import cygrpc as _cygrpc
from grpc import _compression
+from grpc._cython import cygrpc as _cygrpc
+from grpc._runtime_protos import protos
+from grpc._runtime_protos import protos_and_services
+from grpc._runtime_protos import services
+import six
logging.getLogger(__name__).addHandler(logging.NullHandler())
try:
+ # pylint: disable=ungrouped-imports
from grpc._grpcio_metadata import __version__
except ImportError:
__version__ = "dev0"
The callback will be passed this Future object describing the outcome
of the computation. Callbacks will be invoked after the future is
- terimated, whether successfully or not.
+ terminated, whether successfully or not.
If the computation has already completed, the callback will be called
immediately.
class ClientCallDetails(six.with_metaclass(abc.ABCMeta)):
"""Describes an RPC to be invoked.
- This is an EXPERIMENTAL API.
-
Attributes:
method: The method name of the RPC.
timeout: An optional duration of time in seconds to allow for the RPC.
class UnaryUnaryClientInterceptor(six.with_metaclass(abc.ABCMeta)):
- """Affords intercepting unary-unary invocations.
-
- This is an EXPERIMENTAL API.
- """
+ """Affords intercepting unary-unary invocations."""
@abc.abstractmethod
def intercept_unary_unary(self, continuation, client_call_details, request):
class UnaryStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
- """Affords intercepting unary-stream invocations.
-
- This is an EXPERIMENTAL API.
- """
+ """Affords intercepting unary-stream invocations."""
@abc.abstractmethod
def intercept_unary_stream(self, continuation, client_call_details,
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()
class StreamUnaryClientInterceptor(six.with_metaclass(abc.ABCMeta)):
- """Affords intercepting stream-unary invocations.
-
- This is an EXPERIMENTAL API.
- """
+ """Affords intercepting stream-unary invocations."""
@abc.abstractmethod
def intercept_stream_unary(self, continuation, client_call_details,
class StreamStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
- """Affords intercepting stream-stream invocations.
-
- This is an EXPERIMENTAL API.
- """
+ """Affords intercepting stream-stream invocations."""
@abc.abstractmethod
def intercept_stream_stream(self, continuation, client_call_details,
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()
grpc.compression.Gzip. This is an EXPERIMENTAL option.
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.
+ An object that is a Call for the RPC, an iterator of response
+ values, and a Future for the RPC. Drawing response values from the
+ returned Call-iterator may raise RpcError indicating termination of
+ the RPC with non-OK status.
"""
raise NotImplementedError()
grpc.compression.Gzip. This is an EXPERIMENTAL option.
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.
+ An object that is a Call for the RPC, an iterator of response
+ values, and a Future for the RPC. Drawing response values from the
+ returned Call-iterator may raise RpcError indicating termination of
+ the RPC with non-OK status.
"""
raise NotImplementedError()
"""
raise NotImplementedError()
+ def trailing_metadata(self):
+ """Access value to be used as trailing metadata upon RPC completion.
+
+ This is an EXPERIMENTAL API.
+
+ Returns:
+ The trailing :term:`metadata` for the RPC.
+ """
+ raise NotImplementedError()
+
@abc.abstractmethod
def abort(self, code, details):
"""Raises an exception to terminate the RPC with a non-OK status.
"""
raise NotImplementedError()
+ def code(self):
+ """Accesses the value to be used as status code upon RPC completion.
+
+ This is an EXPERIMENTAL API.
+
+ Returns:
+ The StatusCode value for the RPC.
+ """
+ raise NotImplementedError()
+
+ def details(self):
+ """Accesses the value to be used as detail string upon RPC completion.
+
+ This is an EXPERIMENTAL API.
+
+ Returns:
+ The details string of the RPC.
+ """
+ raise NotImplementedError()
+
def disable_next_message_compression(self):
"""Disables compression for the next response message.
class ServerInterceptor(six.with_metaclass(abc.ABCMeta)):
- """Affords intercepting incoming RPCs on the service-side.
-
- This is an EXPERIMENTAL API.
- """
+ """Affords intercepting incoming RPCs on the service-side."""
@abc.abstractmethod
def intercept_service(self, continuation, handler_call_details):
certificate_chain))
+def xds_channel_credentials(fallback_credentials=None):
+ """Creates a ChannelCredentials for use with xDS. This is an EXPERIMENTAL
+ API.
+
+ Args:
+ fallback_credentials: Credentials to use in case it is not possible to
+ establish a secure connection via xDS. If no fallback_credentials
+ argument is supplied, a default SSLChannelCredentials is used.
+ """
+ fallback_credentials = ssl_channel_credentials(
+ ) if fallback_credentials is None else fallback_credentials
+ return ChannelCredentials(
+ _cygrpc.XDSChannelCredentials(fallback_credentials._credentials))
+
+
def metadata_call_credentials(metadata_plugin, name=None):
"""Construct CallCredentials from an AuthMetadataPlugin.
], require_client_auth))
+def xds_server_credentials(fallback_credentials):
+ """Creates a ServerCredentials for use with xDS. This is an EXPERIMENTAL
+ API.
+
+ Args:
+ fallback_credentials: Credentials to use in case it is not possible to
+ establish a secure connection via xDS. No default value is provided.
+ """
+ return ServerCredentials(
+ _cygrpc.xds_server_credentials(fallback_credentials._credentials))
+
+
+def insecure_server_credentials():
+ """Creates a credentials object directing the server to use no credentials.
+ This is an EXPERIMENTAL API.
+
+ This object cannot be used directly in a call to `add_secure_port`.
+ Instead, it should be used to construct other credentials objects, e.g.
+ with xds_server_credentials.
+ """
+ return ServerCredentials(_cygrpc.insecure_server_credentials())
+
+
def ssl_server_certificate_configuration(private_key_certificate_chain_pairs,
root_certificates=None):
"""Creates a ServerCertificateConfiguration for use with a Server.
return ServerCredentials(_cygrpc.server_credentials_alts())
+def compute_engine_channel_credentials(call_credentials):
+ """Creates a compute engine channel credential.
+
+ This credential can only be used in a GCP environment as it relies on
+ a handshaker service. For more info about ALTS, see
+ https://cloud.google.com/security/encryption-in-transit/application-layer-transport-security
+
+ This channel credential is expected to be used as part of a composite
+ credential in conjunction with a call credentials that authenticates the
+ VM's default service account. If used with any other sort of call
+ credential, the connection may suddenly and unexpectedly begin failing RPCs.
+ """
+ return ChannelCredentials(
+ _cygrpc.channel_credentials_compute_engine(
+ call_credentials._credentials))
+
+
def channel_ready_future(channel):
"""Creates a Future that tracks when a Channel is ready.
def intercept_channel(channel, *interceptors):
"""Intercepts a channel through a set of interceptors.
- This is an EXPERIMENTAL API.
-
Args:
channel: A Channel.
interceptors: Zero or more objects of type
interceptors=None,
options=None,
maximum_concurrent_rpcs=None,
- compression=None):
+ compression=None,
+ xds=False):
"""Creates a Server with which RPCs can be serviced.
Args:
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This compression algorithm will be used for the
lifetime of the server unless overridden. This is an EXPERIMENTAL option.
+ xds: If set to true, retrieves server configuration via xDS. This is an
+ EXPERIMENTAL option.
Returns:
A Server object.
() if handlers is None else handlers,
() if interceptors is None else interceptors,
() if options is None else options,
- maximum_concurrent_rpcs, compression)
+ maximum_concurrent_rpcs, compression, xds)
@contextlib.contextmanager
'access_token_call_credentials',
'composite_call_credentials',
'composite_channel_credentials',
+ 'compute_engine_channel_credentials',
'local_channel_credentials',
'local_server_credentials',
'alts_channel_credentials',
'secure_channel',
'intercept_channel',
'server',
+ 'protos',
+ 'services',
+ 'protos_and_services',
+ 'xds_channel_credentials',
+ 'xds_server_credentials',
+ 'insecure_server_credentials',
)
############################### Extension Shims ################################
sys.modules.update({'grpc.reflection': grpc_reflection})
except ImportError:
pass
+
+# Prevents import order issue in the case of renamed path.
+if sys.version_info >= (3, 6) and __name__ == "grpc":
+ from grpc import aio # pylint: disable=ungrouped-imports
+ sys.modules.update({'grpc.aio': aio})