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.
metadata: Optional :term:`metadata` to be transmitted to
the service-side of the RPC.
credentials: An optional CallCredentials for the RPC.
- wait_for_ready: This is an EXPERIMENTAL argument. An optional flag t
- enable wait for ready mechanism.
+ wait_for_ready: This is an EXPERIMENTAL argument. An optional
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
"""
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()
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
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()
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
grpc.compression.Gzip. This is an EXPERIMENTAL option.
credentials: An optional CallCredentials for the RPC. Only valid for
secure Channel.
wait_for_ready: This is an EXPERIMENTAL argument. An optional
- flag to enable wait for ready mechanism
+ flag to enable :term:`wait_for_ready` mechanism.
compression: An element of grpc.compression, e.g.
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.
_cygrpc.server_credentials_local(local_connect_type.value))
+def alts_channel_credentials(service_accounts=None):
+ """Creates a ChannelCredentials for use with an ALTS-enabled Channel.
+
+ This is an EXPERIMENTAL API.
+ ALTS credentials API can only be used in GCP environment as it relies on
+ handshaker service being available. For more info about ALTS see
+ https://cloud.google.com/security/encryption-in-transit/application-layer-transport-security
+
+ Args:
+ service_accounts: A list of server identities accepted by the client.
+ If target service accounts are provided and none of them matches the
+ peer identity of the server, handshake will fail. The arg can be empty
+ if the client does not have any information about trusted server
+ identity.
+ Returns:
+ A ChannelCredentials for use with an ALTS-enabled Channel
+ """
+ return ChannelCredentials(
+ _cygrpc.channel_credentials_alts(service_accounts or []))
+
+
+def alts_server_credentials():
+ """Creates a ServerCredentials for use with an ALTS-enabled connection.
+
+ This is an EXPERIMENTAL API.
+ ALTS credentials API can only be used in GCP environment as it relies on
+ handshaker service being available. For more info about ALTS see
+ https://cloud.google.com/security/encryption-in-transit/application-layer-transport-security
+
+ Returns:
+ A ServerCredentials for use with an ALTS-enabled 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.
Args:
target: The server address
- options: An optional list of key-value pairs (channel args
+ options: An optional list of key-value pairs (:term:`channel_arguments`
in gRPC Core runtime) to configure the channel.
compression: An optional value indicating the compression method to be
used over the lifetime of the channel. This is an EXPERIMENTAL option.
Args:
target: The server address.
credentials: A ChannelCredentials instance.
- options: An optional list of key-value pairs (channel args
+ options: An optional list of key-value pairs (:term:`channel_arguments`
in gRPC Core runtime) to configure the channel.
compression: An optional value indicating the compression method to be
used over the lifetime of the channel. This is an EXPERIMENTAL option.
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:
and optionally manipulate the incoming RPCs before handing them over to
handlers. The interceptors are given control in the order they are
specified. This is an EXPERIMENTAL API.
- options: An optional list of key-value pairs (channel args in gRPC runtime)
+ options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC runtime)
to configure the channel.
maximum_concurrent_rpcs: The maximum number of concurrent RPCs this server
will service before returning RESOURCE_EXHAUSTED status, or None to
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',
+ 'alts_server_credentials',
'ssl_server_credentials',
'ssl_server_certificate_configuration',
'dynamic_ssl_server_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})