grpcio-fips 1.44.0__4-cp38-cp38-win_amd64.whl

grpc/framework/foundation/logging_pool.py

@@ -0,0 +1,71 @@
+# 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.
+"""A thread pool that logs exceptions raised by tasks executed within it."""
+
+from concurrent import futures
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _wrap(behavior):
+    """Wraps an arbitrary callable behavior in exception-logging."""
+
+    def _wrapping(*args, **kwargs):
+        try:
+            return behavior(*args, **kwargs)
+        except Exception:
+            _LOGGER.exception(
+                'Unexpected exception from %s executed in logging pool!',
+                behavior)
+            raise
+
+    return _wrapping
+
+
+class _LoggingPool(object):
+    """An exception-logging futures.ThreadPoolExecutor-compatible thread pool."""
+
+    def __init__(self, backing_pool):
+        self._backing_pool = backing_pool
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._backing_pool.shutdown(wait=True)
+
+    def submit(self, fn, *args, **kwargs):
+        return self._backing_pool.submit(_wrap(fn), *args, **kwargs)
+
+    def map(self, func, *iterables, **kwargs):
+        return self._backing_pool.map(_wrap(func),
+                                      *iterables,
+                                      timeout=kwargs.get('timeout', None))
+
+    def shutdown(self, wait=True):
+        self._backing_pool.shutdown(wait=wait)
+
+
+def pool(max_workers):
+    """Creates a thread pool that logs exceptions raised by the tasks within it.
+
+  Args:
+    max_workers: The maximum number of worker threads to allow the pool.
+
+  Returns:
+    A futures.ThreadPoolExecutor-compatible thread pool that logs exceptions
+      raised by the tasks executed within it.
+  """
+    return _LoggingPool(futures.ThreadPoolExecutor(max_workers))

grpc/framework/foundation/stream.py

@@ -0,0 +1,45 @@
+# 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.
+"""Interfaces related to streams of values or objects."""
+
+import abc
+
+import six
+
+
+class Consumer(six.with_metaclass(abc.ABCMeta)):
+    """Interface for consumers of finite streams of values or objects."""
+
+    @abc.abstractmethod
+    def consume(self, value):
+        """Accepts a value.
+
+    Args:
+      value: Any value accepted by this Consumer.
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def terminate(self):
+        """Indicates to this Consumer that no more values will be supplied."""
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def consume_and_terminate(self, value):
+        """Supplies a value and signals that no more values will be supplied.
+
+    Args:
+      value: Any value accepted by this Consumer.
+    """
+        raise NotImplementedError()

grpc/framework/foundation/stream_util.py

@@ -0,0 +1,148 @@
+# 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.
+"""Helpful utilities related to the stream module."""
+
+import logging
+import threading
+
+from grpc.framework.foundation import stream
+
+_NO_VALUE = object()
+_LOGGER = logging.getLogger(__name__)
+
+
+class TransformingConsumer(stream.Consumer):
+    """A stream.Consumer that passes a transformation of its input to another."""
+
+    def __init__(self, transformation, downstream):
+        self._transformation = transformation
+        self._downstream = downstream
+
+    def consume(self, value):
+        self._downstream.consume(self._transformation(value))
+
+    def terminate(self):
+        self._downstream.terminate()
+
+    def consume_and_terminate(self, value):
+        self._downstream.consume_and_terminate(self._transformation(value))
+
+
+class IterableConsumer(stream.Consumer):
+    """A Consumer that when iterated over emits the values it has consumed."""
+
+    def __init__(self):
+        self._condition = threading.Condition()
+        self._values = []
+        self._active = True
+
+    def consume(self, value):
+        with self._condition:
+            if self._active:
+                self._values.append(value)
+                self._condition.notify()
+
+    def terminate(self):
+        with self._condition:
+            self._active = False
+            self._condition.notify()
+
+    def consume_and_terminate(self, value):
+        with self._condition:
+            if self._active:
+                self._values.append(value)
+                self._active = False
+                self._condition.notify()
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        return self.next()
+
+    def next(self):
+        with self._condition:
+            while self._active and not self._values:
+                self._condition.wait()
+            if self._values:
+                return self._values.pop(0)
+            else:
+                raise StopIteration()
+
+
+class ThreadSwitchingConsumer(stream.Consumer):
+    """A Consumer decorator that affords serialization and asynchrony."""
+
+    def __init__(self, sink, pool):
+        self._lock = threading.Lock()
+        self._sink = sink
+        self._pool = pool
+        # True if self._spin has been submitted to the pool to be called once and
+        # that call has not yet returned, False otherwise.
+        self._spinning = False
+        self._values = []
+        self._active = True
+
+    def _spin(self, sink, value, terminate):
+        while True:
+            try:
+                if value is _NO_VALUE:
+                    sink.terminate()
+                elif terminate:
+                    sink.consume_and_terminate(value)
+                else:
+                    sink.consume(value)
+            except Exception as e:  # pylint:disable=broad-except
+                _LOGGER.exception(e)
+
+            with self._lock:
+                if terminate:
+                    self._spinning = False
+                    return
+                elif self._values:
+                    value = self._values.pop(0)
+                    terminate = not self._values and not self._active
+                elif not self._active:
+                    value = _NO_VALUE
+                    terminate = True
+                else:
+                    self._spinning = False
+                    return
+
+    def consume(self, value):
+        with self._lock:
+            if self._active:
+                if self._spinning:
+                    self._values.append(value)
+                else:
+                    self._pool.submit(self._spin, self._sink, value, False)
+                    self._spinning = True
+
+    def terminate(self):
+        with self._lock:
+            if self._active:
+                self._active = False
+                if not self._spinning:
+                    self._pool.submit(self._spin, self._sink, _NO_VALUE, True)
+                    self._spinning = True
+
+    def consume_and_terminate(self, value):
+        with self._lock:
+            if self._active:
+                self._active = False
+                if self._spinning:
+                    self._values.append(value)
+                else:
+                    self._pool.submit(self._spin, self._sink, value, True)
+                    self._spinning = True

grpc/framework/interfaces/__init__.py

@@ -0,0 +1,13 @@
+# 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.

grpc/framework/interfaces/base/__init__.py

@@ -0,0 +1,13 @@
+# 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.

grpc/framework/interfaces/base/base.py

@@ -0,0 +1,327 @@
+# 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.
+"""The base interface of RPC Framework.
+
+Implementations of this interface support the conduct of "operations":
+exchanges between two distinct ends of an arbitrary number of data payloads
+and metadata such as a name for the operation, initial and terminal metadata
+in each direction, and flow control. These operations may be used for transfers
+of data, remote procedure calls, status indication, or anything else
+applications choose.
+"""
+
+# threading is referenced from specification in this module.
+import abc
+import enum
+import threading  # pylint: disable=unused-import
+
+import six
+
+# pylint: disable=too-many-arguments
+
+
+class NoSuchMethodError(Exception):
+    """Indicates that an unrecognized operation has been called.
+
+    Attributes:
+      code: A code value to communicate to the other side of the operation
+        along with indication of operation termination. May be None.
+      details: A details value to communicate to the other side of the
+        operation along with indication of operation termination. May be None.
+    """
+
+    def __init__(self, code, details):
+        """Constructor.
+
+        Args:
+          code: A code value to communicate to the other side of the operation
+            along with indication of operation termination. May be None.
+          details: A details value to communicate to the other side of the
+            operation along with indication of operation termination. May be None.
+        """
+        super(NoSuchMethodError, self).__init__()
+        self.code = code
+        self.details = details
+
+
+class Outcome(object):
+    """The outcome of an operation.
+
+  Attributes:
+    kind: A Kind value coarsely identifying how the operation terminated.
+    code: An application-specific code value or None if no such value was
+      provided.
+    details: An application-specific details value or None if no such value was
+      provided.
+  """
+
+    @enum.unique
+    class Kind(enum.Enum):
+        """Ways in which an operation can terminate."""
+
+        COMPLETED = 'completed'
+        CANCELLED = 'cancelled'
+        EXPIRED = 'expired'
+        LOCAL_SHUTDOWN = 'local shutdown'
+        REMOTE_SHUTDOWN = 'remote shutdown'
+        RECEPTION_FAILURE = 'reception failure'
+        TRANSMISSION_FAILURE = 'transmission failure'
+        LOCAL_FAILURE = 'local failure'
+        REMOTE_FAILURE = 'remote failure'
+
+
+class Completion(six.with_metaclass(abc.ABCMeta)):
+    """An aggregate of the values exchanged upon operation completion.
+
+  Attributes:
+    terminal_metadata: A terminal metadata value for the operaton.
+    code: A code value for the operation.
+    message: A message value for the operation.
+  """
+
+
+class OperationContext(six.with_metaclass(abc.ABCMeta)):
+    """Provides operation-related information and action."""
+
+    @abc.abstractmethod
+    def outcome(self):
+        """Indicates the operation's outcome (or that the operation is ongoing).
+
+    Returns:
+      None if the operation is still active or the Outcome value for the
+        operation if it has terminated.
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def add_termination_callback(self, callback):
+        """Adds a function to be called upon operation termination.
+
+    Args:
+      callback: A callable to be passed an Outcome value on operation
+        termination.
+
+    Returns:
+      None if the operation has not yet terminated and the passed callback will
+        later be called when it does terminate, or if the operation has already
+        terminated an Outcome value describing the operation termination and the
+        passed callback will not be called as a result of this method call.
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def time_remaining(self):
+        """Describes the length of allowed time remaining for the operation.
+
+    Returns:
+      A nonnegative float indicating the length of allowed time in seconds
+      remaining for the operation to complete before it is considered to have
+      timed out. Zero is returned if the operation has terminated.
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def cancel(self):
+        """Cancels the operation if the operation has not yet terminated."""
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def fail(self, exception):
+        """Indicates that the operation has failed.
+
+    Args:
+      exception: An exception germane to the operation failure. May be None.
+    """
+        raise NotImplementedError()
+
+
+class Operator(six.with_metaclass(abc.ABCMeta)):
+    """An interface through which to participate in an operation."""
+
+    @abc.abstractmethod
+    def advance(self,
+                initial_metadata=None,
+                payload=None,
+                completion=None,
+                allowance=None):
+        """Progresses the operation.
+
+    Args:
+      initial_metadata: An initial metadata value. Only one may ever be
+        communicated in each direction for an operation, and they must be
+        communicated no later than either the first payload or the completion.
+      payload: A payload value.
+      completion: A Completion value. May only ever be non-None once in either
+        direction, and no payloads may be passed after it has been communicated.
+      allowance: A positive integer communicating the number of additional
+        payloads allowed to be passed by the remote side of the operation.
+    """
+        raise NotImplementedError()
+
+
+class ProtocolReceiver(six.with_metaclass(abc.ABCMeta)):
+    """A means of receiving protocol values during an operation."""
+
+    @abc.abstractmethod
+    def context(self, protocol_context):
+        """Accepts the protocol context object for the operation.
+
+    Args:
+      protocol_context: The protocol context object for the operation.
+    """
+        raise NotImplementedError()
+
+
+class Subscription(six.with_metaclass(abc.ABCMeta)):
+    """Describes customer code's interest in values from the other side.
+
+  Attributes:
+    kind: A Kind value describing the overall kind of this value.
+    termination_callback: A callable to be passed the Outcome associated with
+      the operation after it has terminated. Must be non-None if kind is
+      Kind.TERMINATION_ONLY. Must be None otherwise.
+    allowance: A callable behavior that accepts positive integers representing
+      the number of additional payloads allowed to be passed to the other side
+      of the operation. Must be None if kind is Kind.FULL. Must not be None
+      otherwise.
+    operator: An Operator to be passed values from the other side of the
+      operation. Must be non-None if kind is Kind.FULL. Must be None otherwise.
+    protocol_receiver: A ProtocolReceiver to be passed protocol objects as they
+      become available during the operation. Must be non-None if kind is
+      Kind.FULL.
+  """
+
+    @enum.unique
+    class Kind(enum.Enum):
+
+        NONE = 'none'
+        TERMINATION_ONLY = 'termination only'
+        FULL = 'full'
+
+
+class Servicer(six.with_metaclass(abc.ABCMeta)):
+    """Interface for service implementations."""
+
+    @abc.abstractmethod
+    def service(self, group, method, context, output_operator):
+        """Services an operation.
+
+    Args:
+      group: The group identifier of the operation to be serviced.
+      method: The method identifier of the operation to be serviced.
+      context: An OperationContext object affording contextual information and
+        actions.
+      output_operator: An Operator that will accept output values of the
+        operation.
+
+    Returns:
+      A Subscription via which this object may or may not accept more values of
+        the operation.
+
+    Raises:
+      NoSuchMethodError: If this Servicer does not handle operations with the
+        given group and method.
+      abandonment.Abandoned: If the operation has been aborted and there no
+        longer is any reason to service the operation.
+    """
+        raise NotImplementedError()
+
+
+class End(six.with_metaclass(abc.ABCMeta)):
+    """Common type for entry-point objects on both sides of an operation."""
+
+    @abc.abstractmethod
+    def start(self):
+        """Starts this object's service of operations."""
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def stop(self, grace):
+        """Stops this object's service of operations.
+
+    This object will refuse service of new operations as soon as this method is
+    called but operations under way at the time of the call may be given a
+    grace period during which they are allowed to finish.
+
+    Args:
+      grace: A duration of time in seconds to allow ongoing operations to
+        terminate before being forcefully terminated by the stopping of this
+        End. May be zero to terminate all ongoing operations and immediately
+        stop.
+
+    Returns:
+      A threading.Event that will be set to indicate all operations having
+        terminated and this End having completely stopped. The returned event
+        may not be set until after the full grace period (if some ongoing
+        operation continues for the full length of the period) or it may be set
+        much sooner (if for example this End had no operations in progress at
+        the time its stop method was called).
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def operate(self,
+                group,
+                method,
+                subscription,
+                timeout,
+                initial_metadata=None,
+                payload=None,
+                completion=None,
+                protocol_options=None):
+        """Commences an operation.
+
+    Args:
+      group: The group identifier of the invoked operation.
+      method: The method identifier of the invoked operation.
+      subscription: A Subscription to which the results of the operation will be
+        passed.
+      timeout: A length of time in seconds to allow for the operation.
+      initial_metadata: An initial metadata value to be sent to the other side
+        of the operation. May be None if the initial metadata will be later
+        passed via the returned operator or if there will be no initial metadata
+        passed at all.
+      payload: An initial payload for the operation.
+      completion: A Completion value indicating the end of transmission to the
+        other side of the operation.
+      protocol_options: A value specified by the provider of a Base interface
+        implementation affording custom state and behavior.
+
+    Returns:
+      A pair of objects affording information about the operation and action
+        continuing the operation. The first element of the returned pair is an
+        OperationContext for the operation and the second element of the
+        returned pair is an Operator to which operation values not passed in
+        this call should later be passed.
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def operation_stats(self):
+        """Reports the number of terminated operations broken down by outcome.
+
+    Returns:
+      A dictionary from Outcome.Kind value to an integer identifying the number
+        of operations that terminated with that outcome kind.
+    """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def add_idle_action(self, action):
+        """Adds an action to be called when this End has no ongoing operations.
+
+    Args:
+      action: A callable that accepts no arguments.
+    """
+        raise NotImplementedError()

grpc/framework/interfaces/base/utilities.py

@@ -0,0 +1,71 @@
+# 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 use with the base interface of RPC Framework."""
+
+import collections
+
+from grpc.framework.interfaces.base import base
+
+
+class _Completion(base.Completion,
+                  collections.namedtuple('_Completion', (
+                      'terminal_metadata',
+                      'code',
+                      'message',
+                  ))):
+    """A trivial implementation of base.Completion."""
+
+
+class _Subscription(base.Subscription,
+                    collections.namedtuple('_Subscription', (
+                        'kind',
+                        'termination_callback',
+                        'allowance',
+                        'operator',
+                        'protocol_receiver',
+                    ))):
+    """A trivial implementation of base.Subscription."""
+
+
+_NONE_SUBSCRIPTION = _Subscription(base.Subscription.Kind.NONE, None, None,
+                                   None, None)
+
+
+def completion(terminal_metadata, code, message):
+    """Creates a base.Completion aggregating the given operation values.
+
+  Args:
+    terminal_metadata: A terminal metadata value for an operaton.
+    code: A code value for an operation.
+    message: A message value for an operation.
+
+  Returns:
+    A base.Completion aggregating the given operation values.
+  """
+    return _Completion(terminal_metadata, code, message)
+
+
+def full_subscription(operator, protocol_receiver):
+    """Creates a "full" base.Subscription for the given base.Operator.
+
+  Args:
+    operator: A base.Operator to be used in an operation.
+    protocol_receiver: A base.ProtocolReceiver to be used in an operation.
+
+  Returns:
+    A base.Subscription of kind base.Subscription.Kind.FULL wrapping the given
+      base.Operator and base.ProtocolReceiver.
+  """
+    return _Subscription(base.Subscription.Kind.FULL, None, None, operator,
+                         protocol_receiver)