grpcio-fips 1.70.0__4-cp313-cp313-win_amd64.whl

grpc/beta/implementations.py

@@ -0,0 +1,345 @@
+# Copyright 2015-2016 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Entry points into the Beta API of gRPC Python."""
+
+# threading is referenced from specification in this module.
+import threading  # pylint: disable=unused-import
+
+# interfaces, cardinality, and face are referenced from specification in this
+# module.
+import grpc
+from grpc import _auth
+from grpc.beta import _client_adaptations
+from grpc.beta import _metadata
+from grpc.beta import _server_adaptations
+from grpc.beta import interfaces  # pylint: disable=unused-import
+from grpc.framework.common import cardinality  # pylint: disable=unused-import
+from grpc.framework.interfaces.face import face  # pylint: disable=unused-import
+
+# pylint: disable=too-many-arguments
+
+ChannelCredentials = grpc.ChannelCredentials
+ssl_channel_credentials = grpc.ssl_channel_credentials
+CallCredentials = grpc.CallCredentials
+
+
+def metadata_call_credentials(metadata_plugin, name=None):
+    def plugin(context, callback):
+        def wrapped_callback(beta_metadata, error):
+            callback(_metadata.unbeta(beta_metadata), error)
+
+        metadata_plugin(context, wrapped_callback)
+
+    return grpc.metadata_call_credentials(plugin, name=name)
+
+
+def google_call_credentials(credentials):
+    """Construct CallCredentials from GoogleCredentials.
+
+    Args:
+      credentials: A GoogleCredentials object from the oauth2client library.
+
+    Returns:
+      A CallCredentials object for use in a GRPCCallOptions object.
+    """
+    return metadata_call_credentials(_auth.GoogleCallCredentials(credentials))
+
+
+access_token_call_credentials = grpc.access_token_call_credentials
+composite_call_credentials = grpc.composite_call_credentials
+composite_channel_credentials = grpc.composite_channel_credentials
+
+
+class Channel(object):
+    """A channel to a remote host through which RPCs may be conducted.
+
+    Only the "subscribe" and "unsubscribe" methods are supported for application
+    use. This class' instance constructor and all other attributes are
+    unsupported.
+    """
+
+    def __init__(self, channel):
+        self._channel = channel
+
+    def subscribe(self, callback, try_to_connect=None):
+        """Subscribes to this Channel's connectivity.
+
+        Args:
+          callback: A callable to be invoked and passed an
+            interfaces.ChannelConnectivity identifying this Channel's connectivity.
+            The callable will be invoked immediately upon subscription and again for
+            every change to this Channel's connectivity thereafter until it is
+            unsubscribed.
+          try_to_connect: A boolean indicating whether or not this Channel should
+            attempt to connect if it is not already connected and ready to conduct
+            RPCs.
+        """
+        self._channel.subscribe(callback, try_to_connect=try_to_connect)
+
+    def unsubscribe(self, callback):
+        """Unsubscribes a callback from this Channel's connectivity.
+
+        Args:
+          callback: A callable previously registered with this Channel from having
+            been passed to its "subscribe" method.
+        """
+        self._channel.unsubscribe(callback)
+
+
+def insecure_channel(host, port):
+    """Creates an insecure Channel to a remote host.
+
+    Args:
+      host: The name of the remote host to which to connect.
+      port: The port of the remote host to which to connect.
+        If None only the 'host' part will be used.
+
+    Returns:
+      A Channel to the remote host through which RPCs may be conducted.
+    """
+    channel = grpc.insecure_channel(
+        host if port is None else "%s:%d" % (host, port)
+    )
+    return Channel(channel)
+
+
+def secure_channel(host, port, channel_credentials):
+    """Creates a secure Channel to a remote host.
+
+    Args:
+      host: The name of the remote host to which to connect.
+      port: The port of the remote host to which to connect.
+        If None only the 'host' part will be used.
+      channel_credentials: A ChannelCredentials.
+
+    Returns:
+      A secure Channel to the remote host through which RPCs may be conducted.
+    """
+    channel = grpc.secure_channel(
+        host if port is None else "%s:%d" % (host, port), channel_credentials
+    )
+    return Channel(channel)
+
+
+class StubOptions(object):
+    """A value encapsulating the various options for creation of a Stub.
+
+    This class and its instances have no supported interface - it exists to define
+    the type of its instances and its instances exist to be passed to other
+    functions.
+    """
+
+    def __init__(
+        self,
+        host,
+        request_serializers,
+        response_deserializers,
+        metadata_transformer,
+        thread_pool,
+        thread_pool_size,
+    ):
+        self.host = host
+        self.request_serializers = request_serializers
+        self.response_deserializers = response_deserializers
+        self.metadata_transformer = metadata_transformer
+        self.thread_pool = thread_pool
+        self.thread_pool_size = thread_pool_size
+
+
+_EMPTY_STUB_OPTIONS = StubOptions(None, None, None, None, None, None)
+
+
+def stub_options(
+    host=None,
+    request_serializers=None,
+    response_deserializers=None,
+    metadata_transformer=None,
+    thread_pool=None,
+    thread_pool_size=None,
+):
+    """Creates a StubOptions value to be passed at stub creation.
+
+    All parameters are optional and should always be passed by keyword.
+
+    Args:
+      host: A host string to set on RPC calls.
+      request_serializers: A dictionary from service name-method name pair to
+        request serialization behavior.
+      response_deserializers: A dictionary from service name-method name pair to
+        response deserialization behavior.
+      metadata_transformer: A callable that given a metadata object produces
+        another metadata object to be used in the underlying communication on the
+        wire.
+      thread_pool: A thread pool to use in stubs.
+      thread_pool_size: The size of thread pool to create for use in stubs;
+        ignored if thread_pool has been passed.
+
+    Returns:
+      A StubOptions value created from the passed parameters.
+    """
+    return StubOptions(
+        host,
+        request_serializers,
+        response_deserializers,
+        metadata_transformer,
+        thread_pool,
+        thread_pool_size,
+    )
+
+
+def generic_stub(channel, options=None):
+    """Creates a face.GenericStub on which RPCs can be made.
+
+    Args:
+      channel: A Channel for use by the created stub.
+      options: A StubOptions customizing the created stub.
+
+    Returns:
+      A face.GenericStub on which RPCs can be made.
+    """
+    effective_options = _EMPTY_STUB_OPTIONS if options is None else options
+    return _client_adaptations.generic_stub(
+        channel._channel,  # pylint: disable=protected-access
+        effective_options.host,
+        effective_options.metadata_transformer,
+        effective_options.request_serializers,
+        effective_options.response_deserializers,
+    )
+
+
+def dynamic_stub(channel, service, cardinalities, options=None):
+    """Creates a face.DynamicStub with which RPCs can be invoked.
+
+    Args:
+      channel: A Channel for the returned face.DynamicStub to use.
+      service: The package-qualified full name of the service.
+      cardinalities: A dictionary from RPC method name to cardinality.Cardinality
+        value identifying the cardinality of the RPC method.
+      options: An optional StubOptions value further customizing the functionality
+        of the returned face.DynamicStub.
+
+    Returns:
+      A face.DynamicStub with which RPCs can be invoked.
+    """
+    effective_options = _EMPTY_STUB_OPTIONS if options is None else options
+    return _client_adaptations.dynamic_stub(
+        channel._channel,  # pylint: disable=protected-access
+        service,
+        cardinalities,
+        effective_options.host,
+        effective_options.metadata_transformer,
+        effective_options.request_serializers,
+        effective_options.response_deserializers,
+    )
+
+
+ServerCredentials = grpc.ServerCredentials
+ssl_server_credentials = grpc.ssl_server_credentials
+
+
+class ServerOptions(object):
+    """A value encapsulating the various options for creation of a Server.
+
+    This class and its instances have no supported interface - it exists to define
+    the type of its instances and its instances exist to be passed to other
+    functions.
+    """
+
+    def __init__(
+        self,
+        multi_method_implementation,
+        request_deserializers,
+        response_serializers,
+        thread_pool,
+        thread_pool_size,
+        default_timeout,
+        maximum_timeout,
+    ):
+        self.multi_method_implementation = multi_method_implementation
+        self.request_deserializers = request_deserializers
+        self.response_serializers = response_serializers
+        self.thread_pool = thread_pool
+        self.thread_pool_size = thread_pool_size
+        self.default_timeout = default_timeout
+        self.maximum_timeout = maximum_timeout
+
+
+_EMPTY_SERVER_OPTIONS = ServerOptions(None, None, None, None, None, None, None)
+
+
+def server_options(
+    multi_method_implementation=None,
+    request_deserializers=None,
+    response_serializers=None,
+    thread_pool=None,
+    thread_pool_size=None,
+    default_timeout=None,
+    maximum_timeout=None,
+):
+    """Creates a ServerOptions value to be passed at server creation.
+
+    All parameters are optional and should always be passed by keyword.
+
+    Args:
+      multi_method_implementation: A face.MultiMethodImplementation to be called
+        to service an RPC if the server has no specific method implementation for
+        the name of the RPC for which service was requested.
+      request_deserializers: A dictionary from service name-method name pair to
+        request deserialization behavior.
+      response_serializers: A dictionary from service name-method name pair to
+        response serialization behavior.
+      thread_pool: A thread pool to use in stubs.
+      thread_pool_size: The size of thread pool to create for use in stubs;
+        ignored if thread_pool has been passed.
+      default_timeout: A duration in seconds to allow for RPC service when
+        servicing RPCs that did not include a timeout value when invoked.
+      maximum_timeout: A duration in seconds to allow for RPC service when
+        servicing RPCs no matter what timeout value was passed when the RPC was
+        invoked.
+
+    Returns:
+      A StubOptions value created from the passed parameters.
+    """
+    return ServerOptions(
+        multi_method_implementation,
+        request_deserializers,
+        response_serializers,
+        thread_pool,
+        thread_pool_size,
+        default_timeout,
+        maximum_timeout,
+    )
+
+
+def server(service_implementations, options=None):
+    """Creates an interfaces.Server with which RPCs can be serviced.
+
+    Args:
+      service_implementations: A dictionary from service name-method name pair to
+        face.MethodImplementation.
+      options: An optional ServerOptions value further customizing the
+        functionality of the returned Server.
+
+    Returns:
+      An interfaces.Server with which RPCs can be serviced.
+    """
+    effective_options = _EMPTY_SERVER_OPTIONS if options is None else options
+    return _server_adaptations.server(
+        service_implementations,
+        effective_options.multi_method_implementation,
+        effective_options.request_deserializers,
+        effective_options.response_serializers,
+        effective_options.thread_pool,
+        effective_options.thread_pool_size,
+    )

grpc/beta/interfaces.py

@@ -0,0 +1,163 @@
+# Copyright 2015 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Constants and interfaces of the Beta API of gRPC Python."""
+
+import abc
+
+import grpc
+
+ChannelConnectivity = grpc.ChannelConnectivity
+# FATAL_FAILURE was a Beta-API name for SHUTDOWN
+ChannelConnectivity.FATAL_FAILURE = ChannelConnectivity.SHUTDOWN
+
+StatusCode = grpc.StatusCode
+
+
+class GRPCCallOptions(object):
+    """A value encapsulating gRPC-specific options passed on RPC invocation.
+
+    This class and its instances have no supported interface - it exists to
+    define the type of its instances and its instances exist to be passed to
+    other functions.
+    """
+
+    def __init__(self, disable_compression, subcall_of, credentials):
+        self.disable_compression = disable_compression
+        self.subcall_of = subcall_of
+        self.credentials = credentials
+
+
+def grpc_call_options(disable_compression=False, credentials=None):
+    """Creates a GRPCCallOptions value to be passed at RPC invocation.
+
+    All parameters are optional and should always be passed by keyword.
+
+    Args:
+      disable_compression: A boolean indicating whether or not compression should
+        be disabled for the request object of the RPC. Only valid for
+        request-unary RPCs.
+      credentials: A CallCredentials object to use for the invoked RPC.
+    """
+    return GRPCCallOptions(disable_compression, None, credentials)
+
+
+GRPCAuthMetadataContext = grpc.AuthMetadataContext
+GRPCAuthMetadataPluginCallback = grpc.AuthMetadataPluginCallback
+GRPCAuthMetadataPlugin = grpc.AuthMetadataPlugin
+
+
+class GRPCServicerContext(abc.ABC):
+    """Exposes gRPC-specific options and behaviors to code servicing RPCs."""
+
+    @abc.abstractmethod
+    def peer(self):
+        """Identifies the peer that invoked the RPC being serviced.
+
+        Returns:
+          A string identifying the peer that invoked the RPC being serviced.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def disable_next_response_compression(self):
+        """Disables compression of the next response passed by the application."""
+        raise NotImplementedError()
+
+
+class GRPCInvocationContext(abc.ABC):
+    """Exposes gRPC-specific options and behaviors to code invoking RPCs."""
+
+    @abc.abstractmethod
+    def disable_next_request_compression(self):
+        """Disables compression of the next request passed by the application."""
+        raise NotImplementedError()
+
+
+class Server(abc.ABC):
+    """Services RPCs."""
+
+    @abc.abstractmethod
+    def add_insecure_port(self, address):
+        """Reserves a port for insecure RPC service once this Server becomes active.
+
+        This method may only be called before calling this Server's start method is
+        called.
+
+        Args:
+          address: The address for which to open a port.
+
+        Returns:
+          An integer port on which RPCs will be serviced after this link has been
+            started. This is typically the same number as the port number contained
+            in the passed address, but will likely be different if the port number
+            contained in the passed address was zero.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def add_secure_port(self, address, server_credentials):
+        """Reserves a port for secure RPC service after this Server becomes active.
+
+        This method may only be called before calling this Server's start method is
+        called.
+
+        Args:
+          address: The address for which to open a port.
+          server_credentials: A ServerCredentials.
+
+        Returns:
+          An integer port on which RPCs will be serviced after this link has been
+            started. This is typically the same number as the port number contained
+            in the passed address, but will likely be different if the port number
+            contained in the passed address was zero.
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def start(self):
+        """Starts this Server's service of RPCs.
+
+        This method may only be called while the server is not serving RPCs (i.e. it
+        is not idempotent).
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def stop(self, grace):
+        """Stops this Server's service of RPCs.
+
+        All calls to this method immediately stop service of new RPCs. When existing
+        RPCs are aborted is controlled by the grace period parameter passed to this
+        method.
+
+        This method may be called at any time and is idempotent. Passing a smaller
+        grace value than has been passed in a previous call will have the effect of
+        stopping the Server sooner. Passing a larger grace value than has been
+        passed in a previous call will not have the effect of stopping the server
+        later.
+
+        Args:
+          grace: A duration of time in seconds to allow existing RPCs to complete
+            before being aborted by this Server's stopping. May be zero for
+            immediate abortion of all in-progress RPCs.
+
+        Returns:
+          A threading.Event that will be set when this Server has completely
+          stopped. The returned event may not be set until after the full grace
+          period (if some ongoing RPC continues for the full length of the period)
+          of it may be set much sooner (such as if this Server had no RPCs underway
+          at the time it was stopped or if all RPCs that it had underway completed
+          very early in the grace period).
+        """
+        raise NotImplementedError()

grpc/beta/utilities.py

@@ -0,0 +1,153 @@
+# Copyright 2015 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Utilities for the gRPC Python Beta API."""
+
+import threading
+import time
+
+# implementations is referenced from specification in this module.
+from grpc.beta import implementations  # pylint: disable=unused-import
+from grpc.beta import interfaces
+from grpc.framework.foundation import callable_util
+from grpc.framework.foundation import future
+
+_DONE_CALLBACK_EXCEPTION_LOG_MESSAGE = (
+    'Exception calling connectivity future "done" callback!'
+)
+
+
+class _ChannelReadyFuture(future.Future):
+    def __init__(self, channel):
+        self._condition = threading.Condition()
+        self._channel = channel
+
+        self._matured = False
+        self._cancelled = False
+        self._done_callbacks = []
+
+    def _block(self, timeout):
+        until = None if timeout is None else time.time() + timeout
+        with self._condition:
+            while True:
+                if self._cancelled:
+                    raise future.CancelledError()
+                elif self._matured:
+                    return
+                else:
+                    if until is None:
+                        self._condition.wait()
+                    else:
+                        remaining = until - time.time()
+                        if remaining < 0:
+                            raise future.TimeoutError()
+                        else:
+                            self._condition.wait(timeout=remaining)
+
+    def _update(self, connectivity):
+        with self._condition:
+            if (
+                not self._cancelled
+                and connectivity is interfaces.ChannelConnectivity.READY
+            ):
+                self._matured = True
+                self._channel.unsubscribe(self._update)
+                self._condition.notify_all()
+                done_callbacks = tuple(self._done_callbacks)
+                self._done_callbacks = None
+            else:
+                return
+
+        for done_callback in done_callbacks:
+            callable_util.call_logging_exceptions(
+                done_callback, _DONE_CALLBACK_EXCEPTION_LOG_MESSAGE, self
+            )
+
+    def cancel(self):
+        with self._condition:
+            if not self._matured:
+                self._cancelled = True
+                self._channel.unsubscribe(self._update)
+                self._condition.notify_all()
+                done_callbacks = tuple(self._done_callbacks)
+                self._done_callbacks = None
+            else:
+                return False
+
+        for done_callback in done_callbacks:
+            callable_util.call_logging_exceptions(
+                done_callback, _DONE_CALLBACK_EXCEPTION_LOG_MESSAGE, self
+            )
+
+        return True
+
+    def cancelled(self):
+        with self._condition:
+            return self._cancelled
+
+    def running(self):
+        with self._condition:
+            return not self._cancelled and not self._matured
+
+    def done(self):
+        with self._condition:
+            return self._cancelled or self._matured
+
+    def result(self, timeout=None):
+        self._block(timeout)
+        return None
+
+    def exception(self, timeout=None):
+        self._block(timeout)
+        return None
+
+    def traceback(self, timeout=None):
+        self._block(timeout)
+        return None
+
+    def add_done_callback(self, fn):
+        with self._condition:
+            if not self._cancelled and not self._matured:
+                self._done_callbacks.append(fn)
+                return
+
+        fn(self)
+
+    def start(self):
+        with self._condition:
+            self._channel.subscribe(self._update, try_to_connect=True)
+
+    def __del__(self):
+        with self._condition:
+            if not self._cancelled and not self._matured:
+                self._channel.unsubscribe(self._update)
+
+
+def channel_ready_future(channel):
+    """Creates a future.Future tracking when an implementations.Channel is ready.
+
+    Cancelling the returned future.Future does not tell the given
+    implementations.Channel to abandon attempts it may have been making to
+    connect; cancelling merely deactivates the return future.Future's
+    subscription to the given implementations.Channel's connectivity.
+
+    Args:
+      channel: An implementations.Channel.
+
+    Returns:
+      A future.Future that matures when the given Channel has connectivity
+        interfaces.ChannelConnectivity.READY.
+    """
+    ready_future = _ChannelReadyFuture(channel)
+    ready_future.start()
+    return ready_future