grpc.framework.foundation package¶
Submodules¶
grpc.framework.foundation.abandonment module¶
Utilities for indicating abandonment of computation.
grpc.framework.foundation.callable_util module¶
Utilities for working with callables.
-
class
grpc.framework.foundation.callable_util.
Outcome
[source]¶ Bases:
object
A sum type describing the outcome of some call.
-
kind
¶ One of Kind.RETURNED or Kind.RAISED respectively indicating that the call returned a value or raised an exception.
-
return_value
¶ The value returned by the call. Must be present if kind is Kind.RETURNED.
-
exception
¶ The exception raised by the call. Must be present if kind is Kind.RAISED.
-
-
grpc.framework.foundation.callable_util.
call_logging_exceptions
(behavior, message, *args, **kwargs)[source]¶ Calls a behavior in a try-except that logs any exceptions it raises.
Parameters: - behavior – Any callable.
- message – A string to log if the behavior raises an exception.
- *args – Positional arguments to pass to the given behavior.
- **kwargs – Keyword arguments to pass to the given behavior.
Returns: - An Outcome describing whether the given behavior returned a value or raised
an exception.
-
grpc.framework.foundation.callable_util.
with_exceptions_logged
(behavior, message)[source]¶ Wraps a callable in a try-except that logs any exceptions it raises.
Parameters: - behavior – Any callable.
- message – A string to log if the behavior raises an exception.
Returns: - A callable that when executed invokes the given behavior. The returned
callable takes the same arguments as the given behavior but returns a future.Outcome describing whether the given behavior returned a value or raised an exception.
grpc.framework.foundation.future module¶
A Future interface.
Python doesn’t have a Future interface in its standard library. In the absence of such a standard, three separate, incompatible implementations (concurrent.futures.Future, ndb.Future, and asyncio.Future) have appeared. This interface attempts to be as compatible as possible with concurrent.futures.Future. From ndb.Future it adopts a traceback-object accessor method.
Unlike the concrete and implemented Future classes listed above, the Future class defined in this module is an entirely abstract interface that anyone may implement and use.
The one known incompatibility between this interface and the interface of concurrent.futures.Future is that this interface defines its own CancelledError and TimeoutError exceptions rather than raising the implementation-private concurrent.futures._base.CancelledError and the built-in-but-only-in-3.3-and-later TimeoutError.
-
exception
grpc.framework.foundation.future.
CancelledError
[source]¶ Bases:
Exception
Indicates that the computation underlying a Future was cancelled.
-
class
grpc.framework.foundation.future.
Future
[source]¶ Bases:
object
A representation of a computation in another control flow.
Computations represented by a Future may be yet to be begun, may be ongoing, or may have already completed.
-
add_done_callback
(fn)[source]¶ Adds a function to be called at completion of the computation.
The callback will be passed this Future object describing the outcome of the computation.
If the computation has already completed, the callback will be called immediately.
Parameters: fn – A callable taking this Future object as its single parameter.
-
cancel
()[source]¶ Attempts to cancel the computation.
This method does not block.
Returns: - True if the computation has not yet begun, will not be allowed to take
- place, and determination of both was possible without blocking. False under all other circumstances including but not limited to the computation’s already having begun, the computation’s already having finished, and the computation’s having been scheduled for execution on a remote system for which a determination of whether or not it commenced before being cancelled cannot be made without blocking.
-
cancelled
()[source]¶ Describes whether the computation was cancelled.
This method does not block.
Returns: - True if the computation was cancelled any time before its result became
- immediately available. False under all other circumstances including but not limited to this object’s cancel method not having been called and the computation’s result having become immediately available.
-
done
()[source]¶ Describes whether the computation has taken place.
This method does not block.
Returns: - True if the computation is known to have either completed or have been
- unscheduled or interrupted. False if the computation may possibly be executing or scheduled to execute later.
-
exception
(timeout=None)[source]¶ Return the exception raised by the computation.
This method may return immediately or may block.
Parameters: timeout – The length of time in seconds to wait for the computation to terminate or be cancelled, or None if this method should block until the computation is terminated or is cancelled no matter how long that takes.
Returns: - The exception raised by the computation, or None if the computation did
not raise an exception.
Raises: TimeoutError
– If a timeout value is passed and the computation does not terminate within the allotted time.CancelledError
– If the computation was cancelled.
-
result
(timeout=None)[source]¶ Accesses the outcome of the computation or raises its exception.
This method may return immediately or may block.
Parameters: timeout – The length of time in seconds to wait for the computation to finish or be cancelled, or None if this method should block until the computation has finished or is cancelled no matter how long that takes.
Returns: The return value of the computation.
Raises: TimeoutError
– If a timeout value is passed and the computation does not terminate within the allotted time.CancelledError
– If the computation was cancelled.Exception
– If the computation raised an exception, this call will raise the same exception.
-
running
()[source]¶ Describes whether the computation is taking place.
This method does not block.
Returns: - True if the computation is scheduled to take place in the future or is
- taking place now, or False if the computation took place in the past or was cancelled.
-
traceback
(timeout=None)[source]¶ Access the traceback of the exception raised by the computation.
This method may return immediately or may block.
Parameters: timeout – The length of time in seconds to wait for the computation to terminate or be cancelled, or None if this method should block until the computation is terminated or is cancelled no matter how long that takes.
Returns: - The traceback of the exception raised by the computation, or None if the
computation did not raise an exception.
Raises: TimeoutError
– If a timeout value is passed and the computation does not terminate within the allotted time.CancelledError
– If the computation was cancelled.
-
grpc.framework.foundation.logging_pool module¶
A thread pool that logs exceptions raised by tasks executed within it.
-
grpc.framework.foundation.logging_pool.
pool
(max_workers)[source]¶ Creates a thread pool that logs exceptions raised by the tasks within it.
Parameters: 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.
grpc.framework.foundation.stream module¶
Interfaces related to streams of values or objects.
grpc.framework.foundation.stream_util module¶
Helpful utilities related to the stream module.
-
class
grpc.framework.foundation.stream_util.
IterableConsumer
[source]¶ Bases:
grpc.framework.foundation.stream.Consumer
A Consumer that when iterated over emits the values it has consumed.
-
class
grpc.framework.foundation.stream_util.
ThreadSwitchingConsumer
(sink, pool)[source]¶ Bases:
grpc.framework.foundation.stream.Consumer
A Consumer decorator that affords serialization and asynchrony.
-
class
grpc.framework.foundation.stream_util.
TransformingConsumer
(transformation, downstream)[source]¶ Bases:
grpc.framework.foundation.stream.Consumer
A stream.Consumer that passes a transformation of its input to another.