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()
def __call__(self, context, callback):
"""Implements authentication by passing metadata to a callback.
- Implementations of this method must not block.
+ This method will be invoked asynchronously in a separate thread.
Args:
context: An AuthMetadataContext providing information on the RPC that
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()
Args:
method: The name of the RPC method.
- request_serializer: Optional behaviour for serializing the request
+ request_serializer: Optional :term:`serializer` for serializing the request
message. Request goes unserialized in case None is passed.
- response_deserializer: Optional behaviour for deserializing the
+ response_deserializer: Optional :term:`deserializer` for deserializing the
response message. Response goes undeserialized in case None
is passed.
Args:
method: The name of the RPC method.
- request_serializer: Optional behaviour for serializing the request
+ request_serializer: Optional :term:`serializer` for serializing the request
message. Request goes unserialized in case None is passed.
- response_deserializer: Optional behaviour for deserializing the
+ response_deserializer: Optional :term:`deserializer` for deserializing the
response message. Response goes undeserialized in case None is
passed.
Args:
method: The name of the RPC method.
- request_serializer: Optional behaviour for serializing the request
+ request_serializer: Optional :term:`serializer` for serializing the request
message. Request goes unserialized in case None is passed.
- response_deserializer: Optional behaviour for deserializing the
+ response_deserializer: Optional :term:`deserializer` for deserializing the
response message. Response goes undeserialized in case None is
passed.
Args:
method: The name of the RPC method.
- request_serializer: Optional behaviour for serializing the request
+ request_serializer: Optional :term:`serializer` for serializing the request
message. Request goes unserialized in case None is passed.
- response_deserializer: Optional behaviour for deserializing the
+ response_deserializer: Optional :term:`deserializer` for deserializing the
response message. Response goes undeserialized in case None
is passed.
"""
raise NotImplementedError()
+ def __enter__(self):
+ """Enters the runtime context related to the channel object."""
+ raise NotImplementedError()
+
+ def __exit__(self, exc_type, exc_val, exc_tb):
+ """Exits the runtime context related to the channel object."""
+ raise NotImplementedError()
+
########################## Service-Side Context ##############################
"""
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.
or any arbitrary number of request messages.
response_streaming: Whether the RPC supports exactly one response message
or any arbitrary number of response messages.
- request_deserializer: A callable behavior that accepts a byte string and
+ request_deserializer: A callable :term:`deserializer` that accepts a byte string and
returns an object suitable to be passed to this object's business
logic, or None to indicate that this object's business logic should be
passed the raw request bytes.
- response_serializer: A callable behavior that accepts an object produced
+ response_serializer: A callable :term:`serializer` that accepts an object produced
by this object's business logic and returns a byte string, or None to
indicate that the byte strings produced by this object's business logic
should be transmitted on the wire as they are.
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):
Args:
behavior: The implementation of an RPC that accepts one request
and returns one response.
- request_deserializer: An optional behavior for request deserialization.
- response_serializer: An optional behavior for response serialization.
+ request_deserializer: An optional :term:`deserializer` for request deserialization.
+ response_serializer: An optional :term:`serializer` for response serialization.
Returns:
An RpcMethodHandler object that is typically used by grpc.Server.
Args:
behavior: The implementation of an RPC that accepts one request
and returns an iterator of response values.
- request_deserializer: An optional behavior for request deserialization.
- response_serializer: An optional behavior for response serialization.
+ request_deserializer: An optional :term:`deserializer` for request deserialization.
+ response_serializer: An optional :term:`serializer` for response serialization.
Returns:
An RpcMethodHandler object that is typically used by grpc.Server.
Args:
behavior: The implementation of an RPC that accepts an iterator of
request values and returns a single response value.
- request_deserializer: An optional behavior for request deserialization.
- response_serializer: An optional behavior for response serialization.
+ request_deserializer: An optional :term:`deserializer` for request deserialization.
+ response_serializer: An optional :term:`serializer` for response serialization.
Returns:
An RpcMethodHandler object that is typically used by grpc.Server.
Args:
behavior: The implementation of an RPC that accepts an iterator of
request values and returns an iterator of response values.
- request_deserializer: An optional behavior for request deserialization.
- response_serializer: An optional behavior for response serialization.
+ request_deserializer: An optional :term:`deserializer` for request deserialization.
+ response_serializer: An optional :term:`serializer` for response serialization.
Returns:
An RpcMethodHandler object that is typically used by grpc.Server.
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})
projects / platform / upstream / grpc.git / blobdiff