1 # Copyright 2015-2016 gRPC authors.
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
14 """gRPC's Python API."""
23 from grpc._cython import cygrpc as _cygrpc
24 from grpc import _compression
26 logging.getLogger(__name__).addHandler(logging.NullHandler())
29 from grpc._grpcio_metadata import __version__
33 ############################## Future Interface ###############################
36 class FutureTimeoutError(Exception):
37 """Indicates that a method call on a Future timed out."""
40 class FutureCancelledError(Exception):
41 """Indicates that the computation underlying a Future was cancelled."""
44 class Future(six.with_metaclass(abc.ABCMeta)):
45 """A representation of a computation in another control flow.
47 Computations represented by a Future may be yet to be begun,
48 may be ongoing, or may have already completed.
53 """Attempts to cancel the computation.
55 This method does not block.
59 Returns True if the computation was canceled.
61 Returns False under all other circumstances, for example:
63 1. computation has begun and could not be canceled.
64 2. computation has finished
65 3. computation is scheduled for execution and it is impossible
66 to determine its state without blocking.
68 raise NotImplementedError()
72 """Describes whether the computation was cancelled.
74 This method does not block.
78 Returns True if the computation was cancelled before its result became
81 Returns False under all other circumstances, for example:
83 1. computation was not cancelled.
84 2. computation's result is available.
86 raise NotImplementedError()
90 """Describes whether the computation is taking place.
92 This method does not block.
95 Returns True if the computation is scheduled for execution or
98 Returns False if the computation already executed or was cancelled.
100 raise NotImplementedError()
104 """Describes whether the computation has taken place.
106 This method does not block.
110 Returns True if the computation already executed or was cancelled.
111 Returns False if the computation is scheduled for execution or
113 This is exactly opposite of the running() method's result.
115 raise NotImplementedError()
118 def result(self, timeout=None):
119 """Returns the result of the computation or raises its exception.
121 This method may return immediately or may block.
124 timeout: The length of time in seconds to wait for the computation to
125 finish or be cancelled. If None, the call will block until the
126 computations's termination.
129 The return value of the computation.
132 FutureTimeoutError: If a timeout value is passed and the computation
133 does not terminate within the allotted time.
134 FutureCancelledError: If the computation was cancelled.
135 Exception: If the computation raised an exception, this call will
136 raise the same exception.
138 raise NotImplementedError()
141 def exception(self, timeout=None):
142 """Return the exception raised by the computation.
144 This method may return immediately or may block.
147 timeout: The length of time in seconds to wait for the computation to
148 terminate or be cancelled. If None, the call will block until the
149 computations's termination.
152 The exception raised by the computation, or None if the computation
153 did not raise an exception.
156 FutureTimeoutError: If a timeout value is passed and the computation
157 does not terminate within the allotted time.
158 FutureCancelledError: If the computation was cancelled.
160 raise NotImplementedError()
163 def traceback(self, timeout=None):
164 """Access the traceback of the exception raised by the computation.
166 This method may return immediately or may block.
169 timeout: The length of time in seconds to wait for the computation
170 to terminate or be cancelled. If None, the call will block until
171 the computation's termination.
174 The traceback of the exception raised by the computation, or None
175 if the computation did not raise an exception.
178 FutureTimeoutError: If a timeout value is passed and the computation
179 does not terminate within the allotted time.
180 FutureCancelledError: If the computation was cancelled.
182 raise NotImplementedError()
185 def add_done_callback(self, fn):
186 """Adds a function to be called at completion of the computation.
188 The callback will be passed this Future object describing the outcome
189 of the computation. Callbacks will be invoked after the future is
190 terimated, whether successfully or not.
192 If the computation has already completed, the callback will be called
195 Exceptions raised in the callback will be logged at ERROR level, but
196 will not terminate any threads of execution.
199 fn: A callable taking this Future object as its single parameter.
201 raise NotImplementedError()
204 ################################ gRPC Enums ##################################
208 class ChannelConnectivity(enum.Enum):
209 """Mirrors grpc_connectivity_state in the gRPC Core.
212 IDLE: The channel is idle.
213 CONNECTING: The channel is connecting.
214 READY: The channel is ready to conduct RPCs.
215 TRANSIENT_FAILURE: The channel has seen a failure from which it expects
217 SHUTDOWN: The channel has seen a failure from which it cannot recover.
219 IDLE = (_cygrpc.ConnectivityState.idle, 'idle')
220 CONNECTING = (_cygrpc.ConnectivityState.connecting, 'connecting')
221 READY = (_cygrpc.ConnectivityState.ready, 'ready')
222 TRANSIENT_FAILURE = (_cygrpc.ConnectivityState.transient_failure,
224 SHUTDOWN = (_cygrpc.ConnectivityState.shutdown, 'shutdown')
228 class StatusCode(enum.Enum):
229 """Mirrors grpc_status_code in the gRPC Core.
232 OK: Not an error; returned on success
233 CANCELLED: The operation was cancelled (typically by the caller).
234 UNKNOWN: Unknown error.
235 INVALID_ARGUMENT: Client specified an invalid argument.
236 DEADLINE_EXCEEDED: Deadline expired before operation could complete.
237 NOT_FOUND: Some requested entity (e.g., file or directory) was not found.
238 ALREADY_EXISTS: Some entity that we attempted to create (e.g., file or directory)
240 PERMISSION_DENIED: The caller does not have permission to execute the specified
242 UNAUTHENTICATED: The request does not have valid authentication credentials for the
244 RESOURCE_EXHAUSTED: Some resource has been exhausted, perhaps a per-user quota, or
245 perhaps the entire file system is out of space.
246 FAILED_PRECONDITION: Operation was rejected because the system is not in a state
247 required for the operation's execution.
248 ABORTED: The operation was aborted, typically due to a concurrency issue
249 like sequencer check failures, transaction aborts, etc.
250 UNIMPLEMENTED: Operation is not implemented or not supported/enabled in this service.
251 INTERNAL: Internal errors. Means some invariants expected by underlying
252 system has been broken.
253 UNAVAILABLE: The service is currently unavailable.
254 DATA_LOSS: Unrecoverable data loss or corruption.
256 OK = (_cygrpc.StatusCode.ok, 'ok')
257 CANCELLED = (_cygrpc.StatusCode.cancelled, 'cancelled')
258 UNKNOWN = (_cygrpc.StatusCode.unknown, 'unknown')
259 INVALID_ARGUMENT = (_cygrpc.StatusCode.invalid_argument, 'invalid argument')
260 DEADLINE_EXCEEDED = (_cygrpc.StatusCode.deadline_exceeded,
262 NOT_FOUND = (_cygrpc.StatusCode.not_found, 'not found')
263 ALREADY_EXISTS = (_cygrpc.StatusCode.already_exists, 'already exists')
264 PERMISSION_DENIED = (_cygrpc.StatusCode.permission_denied,
266 RESOURCE_EXHAUSTED = (_cygrpc.StatusCode.resource_exhausted,
267 'resource exhausted')
268 FAILED_PRECONDITION = (_cygrpc.StatusCode.failed_precondition,
269 'failed precondition')
270 ABORTED = (_cygrpc.StatusCode.aborted, 'aborted')
271 OUT_OF_RANGE = (_cygrpc.StatusCode.out_of_range, 'out of range')
272 UNIMPLEMENTED = (_cygrpc.StatusCode.unimplemented, 'unimplemented')
273 INTERNAL = (_cygrpc.StatusCode.internal, 'internal')
274 UNAVAILABLE = (_cygrpc.StatusCode.unavailable, 'unavailable')
275 DATA_LOSS = (_cygrpc.StatusCode.data_loss, 'data loss')
276 UNAUTHENTICATED = (_cygrpc.StatusCode.unauthenticated, 'unauthenticated')
279 ############################# gRPC Status ################################
282 class Status(six.with_metaclass(abc.ABCMeta)):
283 """Describes the status of an RPC.
285 This is an EXPERIMENTAL API.
288 code: A StatusCode object to be sent to the client.
289 details: A UTF-8-encodable string to be sent to the client upon
290 termination of the RPC.
291 trailing_metadata: The trailing :term:`metadata` in the RPC.
295 ############################# gRPC Exceptions ################################
298 class RpcError(Exception):
299 """Raised by the gRPC library to indicate non-OK-status RPC termination."""
302 ############################## Shared Context ################################
305 class RpcContext(six.with_metaclass(abc.ABCMeta)):
306 """Provides RPC-related information and action."""
310 """Describes whether the RPC is active or has terminated.
314 True if RPC is active, False otherwise.
316 raise NotImplementedError()
319 def time_remaining(self):
320 """Describes the length of allowed time remaining for the RPC.
323 A nonnegative float indicating the length of allowed time in seconds
324 remaining for the RPC to complete before it is considered to have
325 timed out, or None if no deadline was specified for the RPC.
327 raise NotImplementedError()
333 Idempotent and has no effect if the RPC has already terminated.
335 raise NotImplementedError()
338 def add_callback(self, callback):
339 """Registers a callback to be called on RPC termination.
342 callback: A no-parameter callable to be called on RPC termination.
345 True if the callback was added and will be called later; False if
346 the callback was not added and will not be called (because the RPC
347 already terminated or some other reason).
349 raise NotImplementedError()
352 ######################### Invocation-Side Context ############################
355 class Call(six.with_metaclass(abc.ABCMeta, RpcContext)):
356 """Invocation-side utility object for an RPC."""
359 def initial_metadata(self):
360 """Accesses the initial metadata sent by the server.
362 This method blocks until the value is available.
365 The initial :term:`metadata`.
367 raise NotImplementedError()
370 def trailing_metadata(self):
371 """Accesses the trailing metadata sent by the server.
373 This method blocks until the value is available.
376 The trailing :term:`metadata`.
378 raise NotImplementedError()
382 """Accesses the status code sent by the server.
384 This method blocks until the value is available.
387 The StatusCode value for the RPC.
389 raise NotImplementedError()
393 """Accesses the details sent by the server.
395 This method blocks until the value is available.
398 The details string of the RPC.
400 raise NotImplementedError()
403 ############## Invocation-Side Interceptor Interfaces & Classes ##############
406 class ClientCallDetails(six.with_metaclass(abc.ABCMeta)):
407 """Describes an RPC to be invoked.
409 This is an EXPERIMENTAL API.
412 method: The method name of the RPC.
413 timeout: An optional duration of time in seconds to allow for the RPC.
414 metadata: Optional :term:`metadata` to be transmitted to
415 the service-side of the RPC.
416 credentials: An optional CallCredentials for the RPC.
417 wait_for_ready: This is an EXPERIMENTAL argument. An optional flag t
418 enable wait for ready mechanism.
419 compression: An element of grpc.compression, e.g.
420 grpc.compression.Gzip. This is an EXPERIMENTAL option.
424 class UnaryUnaryClientInterceptor(six.with_metaclass(abc.ABCMeta)):
425 """Affords intercepting unary-unary invocations.
427 This is an EXPERIMENTAL API.
431 def intercept_unary_unary(self, continuation, client_call_details, request):
432 """Intercepts a unary-unary invocation asynchronously.
435 continuation: A function that proceeds with the invocation by
436 executing the next interceptor in chain or invoking the
437 actual RPC on the underlying Channel. It is the interceptor's
438 responsibility to call it if it decides to move the RPC forward.
439 The interceptor can use
440 `response_future = continuation(client_call_details, request)`
441 to continue with the RPC. `continuation` returns an object that is
442 both a Call for the RPC and a Future. In the event of RPC
443 completion, the return Call-Future's result value will be
444 the response message of the RPC. Should the event terminate
445 with non-OK status, the returned Call-Future's exception value
447 client_call_details: A ClientCallDetails object describing the
449 request: The request value for the RPC.
452 An object that is both a Call for the RPC and a Future.
453 In the event of RPC completion, the return Call-Future's
454 result value will be the response message of the RPC.
455 Should the event terminate with non-OK status, the returned
456 Call-Future's exception value will be an RpcError.
458 raise NotImplementedError()
461 class UnaryStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
462 """Affords intercepting unary-stream invocations.
464 This is an EXPERIMENTAL API.
468 def intercept_unary_stream(self, continuation, client_call_details,
470 """Intercepts a unary-stream invocation.
473 continuation: A function that proceeds with the invocation by
474 executing the next interceptor in chain or invoking the
475 actual RPC on the underlying Channel. It is the interceptor's
476 responsibility to call it if it decides to move the RPC forward.
477 The interceptor can use
478 `response_iterator = continuation(client_call_details, request)`
479 to continue with the RPC. `continuation` returns an object that is
480 both a Call for the RPC and an iterator for response values.
481 Drawing response values from the returned Call-iterator may
482 raise RpcError indicating termination of the RPC with non-OK
484 client_call_details: A ClientCallDetails object describing the
486 request: The request value for the RPC.
489 An object that is both a Call for the RPC and an iterator of
490 response values. Drawing response values from the returned
491 Call-iterator may raise RpcError indicating termination of
492 the RPC with non-OK status.
494 raise NotImplementedError()
497 class StreamUnaryClientInterceptor(six.with_metaclass(abc.ABCMeta)):
498 """Affords intercepting stream-unary invocations.
500 This is an EXPERIMENTAL API.
504 def intercept_stream_unary(self, continuation, client_call_details,
506 """Intercepts a stream-unary invocation asynchronously.
509 continuation: A function that proceeds with the invocation by
510 executing the next interceptor in chain or invoking the
511 actual RPC on the underlying Channel. It is the interceptor's
512 responsibility to call it if it decides to move the RPC forward.
513 The interceptor can use
514 `response_future = continuation(client_call_details, request_iterator)`
515 to continue with the RPC. `continuation` returns an object that is
516 both a Call for the RPC and a Future. In the event of RPC completion,
517 the return Call-Future's result value will be the response message
518 of the RPC. Should the event terminate with non-OK status, the
519 returned Call-Future's exception value will be an RpcError.
520 client_call_details: A ClientCallDetails object describing the
522 request_iterator: An iterator that yields request values for the RPC.
525 An object that is both a Call for the RPC and a Future.
526 In the event of RPC completion, the return Call-Future's
527 result value will be the response message of the RPC.
528 Should the event terminate with non-OK status, the returned
529 Call-Future's exception value will be an RpcError.
531 raise NotImplementedError()
534 class StreamStreamClientInterceptor(six.with_metaclass(abc.ABCMeta)):
535 """Affords intercepting stream-stream invocations.
537 This is an EXPERIMENTAL API.
541 def intercept_stream_stream(self, continuation, client_call_details,
543 """Intercepts a stream-stream invocation.
546 continuation: A function that proceeds with the invocation by
547 executing the next interceptor in chain or invoking the
548 actual RPC on the underlying Channel. It is the interceptor's
549 responsibility to call it if it decides to move the RPC forward.
550 The interceptor can use
551 `response_iterator = continuation(client_call_details, request_iterator)`
552 to continue with the RPC. `continuation` returns an object that is
553 both a Call for the RPC and an iterator for response values.
554 Drawing response values from the returned Call-iterator may
555 raise RpcError indicating termination of the RPC with non-OK
557 client_call_details: A ClientCallDetails object describing the
559 request_iterator: An iterator that yields request values for the RPC.
562 An object that is both a Call for the RPC and an iterator of
563 response values. Drawing response values from the returned
564 Call-iterator may raise RpcError indicating termination of
565 the RPC with non-OK status.
567 raise NotImplementedError()
570 ############ Authentication & Authorization Interfaces & Classes #############
573 class ChannelCredentials(object):
574 """An encapsulation of the data required to create a secure Channel.
576 This class has no supported interface - it exists to define the type of its
577 instances and its instances exist to be passed to other functions. For
578 example, ssl_channel_credentials returns an instance of this class and
579 secure_channel requires an instance of this class.
582 def __init__(self, credentials):
583 self._credentials = credentials
586 class CallCredentials(object):
587 """An encapsulation of the data required to assert an identity over a call.
589 A CallCredentials has to be used with secure Channel, otherwise the
590 metadata will not be transmitted to the server.
592 A CallCredentials may be composed with ChannelCredentials to always assert
593 identity for every call over that Channel.
595 This class has no supported interface - it exists to define the type of its
596 instances and its instances exist to be passed to other functions.
599 def __init__(self, credentials):
600 self._credentials = credentials
603 class AuthMetadataContext(six.with_metaclass(abc.ABCMeta)):
604 """Provides information to call credentials metadata plugins.
607 service_url: A string URL of the service being called into.
608 method_name: A string of the fully qualified method name being called.
612 class AuthMetadataPluginCallback(six.with_metaclass(abc.ABCMeta)):
613 """Callback object received by a metadata plugin."""
615 def __call__(self, metadata, error):
616 """Passes to the gRPC runtime authentication metadata for an RPC.
619 metadata: The :term:`metadata` used to construct the CallCredentials.
620 error: An Exception to indicate error or None to indicate success.
622 raise NotImplementedError()
625 class AuthMetadataPlugin(six.with_metaclass(abc.ABCMeta)):
626 """A specification for custom authentication."""
628 def __call__(self, context, callback):
629 """Implements authentication by passing metadata to a callback.
631 Implementations of this method must not block.
634 context: An AuthMetadataContext providing information on the RPC that
635 the plugin is being called to authenticate.
636 callback: An AuthMetadataPluginCallback to be invoked either
637 synchronously or asynchronously.
639 raise NotImplementedError()
642 class ServerCredentials(object):
643 """An encapsulation of the data required to open a secure port on a Server.
645 This class has no supported interface - it exists to define the type of its
646 instances and its instances exist to be passed to other functions.
649 def __init__(self, credentials):
650 self._credentials = credentials
653 class ServerCertificateConfiguration(object):
654 """A certificate configuration for use with an SSL-enabled Server.
656 Instances of this class can be returned in the certificate configuration
659 This class has no supported interface -- it exists to define the
660 type of its instances and its instances exist to be passed to
664 def __init__(self, certificate_configuration):
665 self._certificate_configuration = certificate_configuration
668 ######################## Multi-Callable Interfaces ###########################
671 class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
672 """Affords invoking a unary-unary RPC from client-side."""
682 """Synchronously invokes the underlying RPC.
685 request: The request value for the RPC.
686 timeout: An optional duration of time in seconds to allow
688 metadata: Optional :term:`metadata` to be transmitted to the
689 service-side of the RPC.
690 credentials: An optional CallCredentials for the RPC. Only valid for
692 wait_for_ready: This is an EXPERIMENTAL argument. An optional
693 flag to enable wait for ready mechanism
694 compression: An element of grpc.compression, e.g.
695 grpc.compression.Gzip. This is an EXPERIMENTAL option.
698 The response value for the RPC.
701 RpcError: Indicating that the RPC terminated with non-OK status. The
702 raised RpcError will also be a Call for the RPC affording the RPC's
703 metadata, status code, and details.
705 raise NotImplementedError()
715 """Synchronously invokes the underlying RPC.
718 request: The request value for the RPC.
719 timeout: An optional durating of time in seconds to allow for
721 metadata: Optional :term:`metadata` to be transmitted to the
722 service-side of the RPC.
723 credentials: An optional CallCredentials for the RPC. Only valid for
725 wait_for_ready: This is an EXPERIMENTAL argument. An optional
726 flag to enable wait for ready mechanism
727 compression: An element of grpc.compression, e.g.
728 grpc.compression.Gzip. This is an EXPERIMENTAL option.
731 The response value for the RPC and a Call value for the RPC.
734 RpcError: Indicating that the RPC terminated with non-OK status. The
735 raised RpcError will also be a Call for the RPC affording the RPC's
736 metadata, status code, and details.
738 raise NotImplementedError()
748 """Asynchronously invokes the underlying RPC.
751 request: The request value for the RPC.
752 timeout: An optional duration of time in seconds to allow for
754 metadata: Optional :term:`metadata` to be transmitted to the
755 service-side of the RPC.
756 credentials: An optional CallCredentials for the RPC. Only valid for
758 wait_for_ready: This is an EXPERIMENTAL argument. An optional
759 flag to enable wait for ready mechanism
760 compression: An element of grpc.compression, e.g.
761 grpc.compression.Gzip. This is an EXPERIMENTAL option.
764 An object that is both a Call for the RPC and a Future.
765 In the event of RPC completion, the return Call-Future's result
766 value will be the response message of the RPC.
767 Should the event terminate with non-OK status,
768 the returned Call-Future's exception value will be an RpcError.
770 raise NotImplementedError()
773 class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
774 """Affords invoking a unary-stream RPC from client-side."""
784 """Invokes the underlying RPC.
787 request: The request value for the RPC.
788 timeout: An optional duration of time in seconds to allow for
789 the RPC. If None, the timeout is considered infinite.
790 metadata: An optional :term:`metadata` to be transmitted to the
791 service-side of the RPC.
792 credentials: An optional CallCredentials for the RPC. Only valid for
794 wait_for_ready: This is an EXPERIMENTAL argument. An optional
795 flag to enable wait for ready mechanism
796 compression: An element of grpc.compression, e.g.
797 grpc.compression.Gzip. This is an EXPERIMENTAL option.
800 An object that is both a Call for the RPC and an iterator of
801 response values. Drawing response values from the returned
802 Call-iterator may raise RpcError indicating termination of the
803 RPC with non-OK status.
805 raise NotImplementedError()
808 class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)):
809 """Affords invoking a stream-unary RPC from client-side."""
819 """Synchronously invokes the underlying RPC.
822 request_iterator: An iterator that yields request values for
824 timeout: An optional duration of time in seconds to allow for
825 the RPC. If None, the timeout is considered infinite.
826 metadata: Optional :term:`metadata` to be transmitted to the
827 service-side of the RPC.
828 credentials: An optional CallCredentials for the RPC. Only valid for
830 wait_for_ready: This is an EXPERIMENTAL argument. An optional
831 flag to enable wait for ready mechanism
832 compression: An element of grpc.compression, e.g.
833 grpc.compression.Gzip. This is an EXPERIMENTAL option.
836 The response value for the RPC.
839 RpcError: Indicating that the RPC terminated with non-OK status. The
840 raised RpcError will also implement grpc.Call, affording methods
841 such as metadata, code, and details.
843 raise NotImplementedError()
853 """Synchronously invokes the underlying RPC on the client.
856 request_iterator: An iterator that yields request values for
858 timeout: An optional duration of time in seconds to allow for
859 the RPC. If None, the timeout is considered infinite.
860 metadata: Optional :term:`metadata` to be transmitted to the
861 service-side of the RPC.
862 credentials: An optional CallCredentials for the RPC. Only valid for
864 wait_for_ready: This is an EXPERIMENTAL argument. An optional
865 flag to enable wait for ready mechanism
866 compression: An element of grpc.compression, e.g.
867 grpc.compression.Gzip. This is an EXPERIMENTAL option.
870 The response value for the RPC and a Call object for the RPC.
873 RpcError: Indicating that the RPC terminated with non-OK status. The
874 raised RpcError will also be a Call for the RPC affording the RPC's
875 metadata, status code, and details.
877 raise NotImplementedError()
887 """Asynchronously invokes the underlying RPC on the client.
890 request_iterator: An iterator that yields request values for the RPC.
891 timeout: An optional duration of time in seconds to allow for
892 the RPC. If None, the timeout is considered infinite.
893 metadata: Optional :term:`metadata` to be transmitted to the
894 service-side of the RPC.
895 credentials: An optional CallCredentials for the RPC. Only valid for
897 wait_for_ready: This is an EXPERIMENTAL argument. An optional
898 flag to enable wait for ready mechanism
899 compression: An element of grpc.compression, e.g.
900 grpc.compression.Gzip. This is an EXPERIMENTAL option.
903 An object that is both a Call for the RPC and a Future.
904 In the event of RPC completion, the return Call-Future's result value
905 will be the response message of the RPC. Should the event terminate
906 with non-OK status, the returned Call-Future's exception value will
909 raise NotImplementedError()
912 class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)):
913 """Affords invoking a stream-stream RPC on client-side."""
923 """Invokes the underlying RPC on the client.
926 request_iterator: An iterator that yields request values for the RPC.
927 timeout: An optional duration of time in seconds to allow for
928 the RPC. If not specified, the timeout is considered infinite.
929 metadata: Optional :term:`metadata` to be transmitted to the
930 service-side of the RPC.
931 credentials: An optional CallCredentials for the RPC. Only valid for
933 wait_for_ready: This is an EXPERIMENTAL argument. An optional
934 flag to enable wait for ready mechanism
935 compression: An element of grpc.compression, e.g.
936 grpc.compression.Gzip. This is an EXPERIMENTAL option.
939 An object that is both a Call for the RPC and an iterator of
940 response values. Drawing response values from the returned
941 Call-iterator may raise RpcError indicating termination of the
942 RPC with non-OK status.
944 raise NotImplementedError()
947 ############################# Channel Interface ##############################
950 class Channel(six.with_metaclass(abc.ABCMeta)):
951 """Affords RPC invocation via generic methods on client-side.
953 Channel objects implement the Context Manager type, although they need not
954 support being entered and exited multiple times.
958 def subscribe(self, callback, try_to_connect=False):
959 """Subscribe to this Channel's connectivity state machine.
961 A Channel may be in any of the states described by ChannelConnectivity.
962 This method allows application to monitor the state transitions.
963 The typical use case is to debug or gain better visibility into gRPC
967 callback: A callable to be invoked with ChannelConnectivity argument.
968 ChannelConnectivity describes current state of the channel.
969 The callable will be invoked immediately upon subscription
970 and again for every change to ChannelConnectivity until it
971 is unsubscribed or this Channel object goes out of scope.
972 try_to_connect: A boolean indicating whether or not this Channel
973 should attempt to connect immediately. If set to False, gRPC
974 runtime decides when to connect.
976 raise NotImplementedError()
979 def unsubscribe(self, callback):
980 """Unsubscribes a subscribed callback from this Channel's connectivity.
983 callback: A callable previously registered with this Channel from
984 having been passed to its "subscribe" method.
986 raise NotImplementedError()
989 def unary_unary(self,
991 request_serializer=None,
992 response_deserializer=None):
993 """Creates a UnaryUnaryMultiCallable for a unary-unary method.
996 method: The name of the RPC method.
997 request_serializer: Optional behaviour for serializing the request
998 message. Request goes unserialized in case None is passed.
999 response_deserializer: Optional behaviour for deserializing the
1000 response message. Response goes undeserialized in case None
1004 A UnaryUnaryMultiCallable value for the named unary-unary method.
1006 raise NotImplementedError()
1009 def unary_stream(self,
1011 request_serializer=None,
1012 response_deserializer=None):
1013 """Creates a UnaryStreamMultiCallable for a unary-stream method.
1016 method: The name of the RPC method.
1017 request_serializer: Optional behaviour for serializing the request
1018 message. Request goes unserialized in case None is passed.
1019 response_deserializer: Optional behaviour for deserializing the
1020 response message. Response goes undeserialized in case None is
1024 A UnaryStreamMultiCallable value for the name unary-stream method.
1026 raise NotImplementedError()
1029 def stream_unary(self,
1031 request_serializer=None,
1032 response_deserializer=None):
1033 """Creates a StreamUnaryMultiCallable for a stream-unary method.
1036 method: The name of the RPC method.
1037 request_serializer: Optional behaviour for serializing the request
1038 message. Request goes unserialized in case None is passed.
1039 response_deserializer: Optional behaviour for deserializing the
1040 response message. Response goes undeserialized in case None is
1044 A StreamUnaryMultiCallable value for the named stream-unary method.
1046 raise NotImplementedError()
1049 def stream_stream(self,
1051 request_serializer=None,
1052 response_deserializer=None):
1053 """Creates a StreamStreamMultiCallable for a stream-stream method.
1056 method: The name of the RPC method.
1057 request_serializer: Optional behaviour for serializing the request
1058 message. Request goes unserialized in case None is passed.
1059 response_deserializer: Optional behaviour for deserializing the
1060 response message. Response goes undeserialized in case None
1064 A StreamStreamMultiCallable value for the named stream-stream method.
1066 raise NotImplementedError()
1070 """Closes this Channel and releases all resources held by it.
1072 Closing the Channel will immediately terminate all RPCs active with the
1073 Channel and it is not valid to invoke new RPCs with the Channel.
1075 This method is idempotent.
1077 raise NotImplementedError()
1080 ########################## Service-Side Context ##############################
1083 class ServicerContext(six.with_metaclass(abc.ABCMeta, RpcContext)):
1084 """A context object passed to method implementations."""
1087 def invocation_metadata(self):
1088 """Accesses the metadata from the sent by the client.
1091 The invocation :term:`metadata`.
1093 raise NotImplementedError()
1097 """Identifies the peer that invoked the RPC being serviced.
1100 A string identifying the peer that invoked the RPC being serviced.
1101 The string format is determined by gRPC runtime.
1103 raise NotImplementedError()
1106 def peer_identities(self):
1107 """Gets one or more peer identity(s).
1110 servicer_context.auth_context().get(servicer_context.peer_identity_key())
1113 An iterable of the identities, or None if the call is not
1114 authenticated. Each identity is returned as a raw bytes type.
1116 raise NotImplementedError()
1119 def peer_identity_key(self):
1120 """The auth property used to identify the peer.
1122 For example, "x509_common_name" or "x509_subject_alternative_name" are
1123 used to identify an SSL peer.
1126 The auth property (string) that indicates the
1127 peer identity, or None if the call is not authenticated.
1129 raise NotImplementedError()
1132 def auth_context(self):
1133 """Gets the auth context for the call.
1136 A map of strings to an iterable of bytes for each auth property.
1138 raise NotImplementedError()
1140 def set_compression(self, compression):
1141 """Set the compression algorithm to be used for the entire call.
1143 This is an EXPERIMENTAL method.
1146 compression: An element of grpc.compression, e.g.
1147 grpc.compression.Gzip.
1149 raise NotImplementedError()
1152 def send_initial_metadata(self, initial_metadata):
1153 """Sends the initial metadata value to the client.
1155 This method need not be called by implementations if they have no
1156 metadata to add to what the gRPC runtime will transmit.
1159 initial_metadata: The initial :term:`metadata`.
1161 raise NotImplementedError()
1164 def set_trailing_metadata(self, trailing_metadata):
1165 """Sends the trailing metadata for the RPC.
1167 This method need not be called by implementations if they have no
1168 metadata to add to what the gRPC runtime will transmit.
1171 trailing_metadata: The trailing :term:`metadata`.
1173 raise NotImplementedError()
1176 def abort(self, code, details):
1177 """Raises an exception to terminate the RPC with a non-OK status.
1179 The code and details passed as arguments will supercede any existing
1183 code: A StatusCode object to be sent to the client.
1184 It must not be StatusCode.OK.
1185 details: A UTF-8-encodable string to be sent to the client upon
1186 termination of the RPC.
1189 Exception: An exception is always raised to signal the abortion the
1190 RPC to the gRPC runtime.
1192 raise NotImplementedError()
1195 def abort_with_status(self, status):
1196 """Raises an exception to terminate the RPC with a non-OK status.
1198 The status passed as argument will supercede any existing status code,
1199 status message and trailing metadata.
1201 This is an EXPERIMENTAL API.
1204 status: A grpc.Status object. The status code in it must not be
1208 Exception: An exception is always raised to signal the abortion the
1209 RPC to the gRPC runtime.
1211 raise NotImplementedError()
1214 def set_code(self, code):
1215 """Sets the value to be used as status code upon RPC completion.
1217 This method need not be called by method implementations if they wish
1218 the gRPC runtime to determine the status code of the RPC.
1221 code: A StatusCode object to be sent to the client.
1223 raise NotImplementedError()
1226 def set_details(self, details):
1227 """Sets the value to be used as detail string upon RPC completion.
1229 This method need not be called by method implementations if they have
1230 no details to transmit.
1233 details: A UTF-8-encodable string to be sent to the client upon
1234 termination of the RPC.
1236 raise NotImplementedError()
1238 def disable_next_message_compression(self):
1239 """Disables compression for the next response message.
1241 This is an EXPERIMENTAL method.
1243 This method will override any compression configuration set during
1244 server creation or set on the call.
1246 raise NotImplementedError()
1249 ##################### Service-Side Handler Interfaces ########################
1252 class RpcMethodHandler(six.with_metaclass(abc.ABCMeta)):
1253 """An implementation of a single RPC method.
1256 request_streaming: Whether the RPC supports exactly one request message
1257 or any arbitrary number of request messages.
1258 response_streaming: Whether the RPC supports exactly one response message
1259 or any arbitrary number of response messages.
1260 request_deserializer: A callable behavior that accepts a byte string and
1261 returns an object suitable to be passed to this object's business
1262 logic, or None to indicate that this object's business logic should be
1263 passed the raw request bytes.
1264 response_serializer: A callable behavior that accepts an object produced
1265 by this object's business logic and returns a byte string, or None to
1266 indicate that the byte strings produced by this object's business logic
1267 should be transmitted on the wire as they are.
1268 unary_unary: This object's application-specific business logic as a
1269 callable value that takes a request value and a ServicerContext object
1270 and returns a response value. Only non-None if both request_streaming
1271 and response_streaming are False.
1272 unary_stream: This object's application-specific business logic as a
1273 callable value that takes a request value and a ServicerContext object
1274 and returns an iterator of response values. Only non-None if
1275 request_streaming is False and response_streaming is True.
1276 stream_unary: This object's application-specific business logic as a
1277 callable value that takes an iterator of request values and a
1278 ServicerContext object and returns a response value. Only non-None if
1279 request_streaming is True and response_streaming is False.
1280 stream_stream: This object's application-specific business logic as a
1281 callable value that takes an iterator of request values and a
1282 ServicerContext object and returns an iterator of response values.
1283 Only non-None if request_streaming and response_streaming are both
1288 class HandlerCallDetails(six.with_metaclass(abc.ABCMeta)):
1289 """Describes an RPC that has just arrived for service.
1292 method: The method name of the RPC.
1293 invocation_metadata: The :term:`metadata` sent by the client.
1297 class GenericRpcHandler(six.with_metaclass(abc.ABCMeta)):
1298 """An implementation of arbitrarily many RPC methods."""
1301 def service(self, handler_call_details):
1302 """Returns the handler for servicing the RPC.
1305 handler_call_details: A HandlerCallDetails describing the RPC.
1308 An RpcMethodHandler with which the RPC may be serviced if the
1309 implementation chooses to service this RPC, or None otherwise.
1311 raise NotImplementedError()
1314 class ServiceRpcHandler(six.with_metaclass(abc.ABCMeta, GenericRpcHandler)):
1315 """An implementation of RPC methods belonging to a service.
1317 A service handles RPC methods with structured names of the form
1318 '/Service.Name/Service.Method', where 'Service.Name' is the value
1319 returned by service_name(), and 'Service.Method' is the method
1320 name. A service can have multiple method names, but only a single
1325 def service_name(self):
1326 """Returns this service's name.
1331 raise NotImplementedError()
1334 #################### Service-Side Interceptor Interfaces #####################
1337 class ServerInterceptor(six.with_metaclass(abc.ABCMeta)):
1338 """Affords intercepting incoming RPCs on the service-side.
1340 This is an EXPERIMENTAL API.
1344 def intercept_service(self, continuation, handler_call_details):
1345 """Intercepts incoming RPCs before handing them over to a handler.
1348 continuation: A function that takes a HandlerCallDetails and
1349 proceeds to invoke the next interceptor in the chain, if any,
1350 or the RPC handler lookup logic, with the call details passed
1351 as an argument, and returns an RpcMethodHandler instance if
1352 the RPC is considered serviced, or None otherwise.
1353 handler_call_details: A HandlerCallDetails describing the RPC.
1356 An RpcMethodHandler with which the RPC may be serviced if the
1357 interceptor chooses to service this RPC, or None otherwise.
1359 raise NotImplementedError()
1362 ############################# Server Interface ###############################
1365 class Server(six.with_metaclass(abc.ABCMeta)):
1366 """Services RPCs."""
1369 def add_generic_rpc_handlers(self, generic_rpc_handlers):
1370 """Registers GenericRpcHandlers with this Server.
1372 This method is only safe to call before the server is started.
1375 generic_rpc_handlers: An iterable of GenericRpcHandlers that will be
1376 used to service RPCs.
1378 raise NotImplementedError()
1381 def add_insecure_port(self, address):
1382 """Opens an insecure port for accepting RPCs.
1384 This method may only be called before starting the server.
1387 address: The address for which to open a port. If the port is 0,
1388 or not specified in the address, then gRPC runtime will choose a port.
1391 An integer port on which server will accept RPC requests.
1393 raise NotImplementedError()
1396 def add_secure_port(self, address, server_credentials):
1397 """Opens a secure port for accepting RPCs.
1399 This method may only be called before starting the server.
1402 address: The address for which to open a port.
1403 if the port is 0, or not specified in the address, then gRPC
1404 runtime will choose a port.
1405 server_credentials: A ServerCredentials object.
1408 An integer port on which server will accept RPC requests.
1410 raise NotImplementedError()
1414 """Starts this Server.
1416 This method may only be called once. (i.e. it is not idempotent).
1418 raise NotImplementedError()
1421 def stop(self, grace):
1422 """Stops this Server.
1424 This method immediately stop service of new RPCs in all cases.
1426 If a grace period is specified, this method returns immediately
1427 and all RPCs active at the end of the grace period are aborted.
1428 If a grace period is not specified (by passing None for `grace`),
1429 all existing RPCs are aborted immediately and this method
1430 blocks until the last RPC handler terminates.
1432 This method is idempotent and may be called at any time.
1433 Passing a smaller grace value in a subsequent call will have
1434 the effect of stopping the Server sooner (passing None will
1435 have the effect of stopping the server immediately). Passing
1436 a larger grace value in a subsequent call *will not* have the
1437 effect of stopping the server later (i.e. the most restrictive
1438 grace value is used).
1441 grace: A duration of time in seconds or None.
1444 A threading.Event that will be set when this Server has completely
1445 stopped, i.e. when running RPCs either complete or are aborted and
1446 all handlers have terminated.
1448 raise NotImplementedError()
1450 def wait_for_termination(self, timeout=None):
1451 """Block current thread until the server stops.
1453 This is an EXPERIMENTAL API.
1455 The wait will not consume computational resources during blocking, and
1456 it will block until one of the two following conditions are met:
1458 1) The server is stopped or terminated;
1459 2) A timeout occurs if timeout is not `None`.
1461 The timeout argument works in the same way as `threading.Event.wait()`.
1462 https://docs.python.org/3/library/threading.html#threading.Event.wait
1465 timeout: A floating point number specifying a timeout for the
1466 operation in seconds.
1469 A bool indicates if the operation times out.
1471 raise NotImplementedError()
1474 ################################# Functions ################################
1477 def unary_unary_rpc_method_handler(behavior,
1478 request_deserializer=None,
1479 response_serializer=None):
1480 """Creates an RpcMethodHandler for a unary-unary RPC method.
1483 behavior: The implementation of an RPC that accepts one request
1484 and returns one response.
1485 request_deserializer: An optional behavior for request deserialization.
1486 response_serializer: An optional behavior for response serialization.
1489 An RpcMethodHandler object that is typically used by grpc.Server.
1491 from grpc import _utilities # pylint: disable=cyclic-import
1492 return _utilities.RpcMethodHandler(False, False, request_deserializer,
1493 response_serializer, behavior, None,
1497 def unary_stream_rpc_method_handler(behavior,
1498 request_deserializer=None,
1499 response_serializer=None):
1500 """Creates an RpcMethodHandler for a unary-stream RPC method.
1503 behavior: The implementation of an RPC that accepts one request
1504 and returns an iterator of response values.
1505 request_deserializer: An optional behavior for request deserialization.
1506 response_serializer: An optional behavior for response serialization.
1509 An RpcMethodHandler object that is typically used by grpc.Server.
1511 from grpc import _utilities # pylint: disable=cyclic-import
1512 return _utilities.RpcMethodHandler(False, True, request_deserializer,
1513 response_serializer, None, behavior,
1517 def stream_unary_rpc_method_handler(behavior,
1518 request_deserializer=None,
1519 response_serializer=None):
1520 """Creates an RpcMethodHandler for a stream-unary RPC method.
1523 behavior: The implementation of an RPC that accepts an iterator of
1524 request values and returns a single response value.
1525 request_deserializer: An optional behavior for request deserialization.
1526 response_serializer: An optional behavior for response serialization.
1529 An RpcMethodHandler object that is typically used by grpc.Server.
1531 from grpc import _utilities # pylint: disable=cyclic-import
1532 return _utilities.RpcMethodHandler(True, False, request_deserializer,
1533 response_serializer, None, None,
1537 def stream_stream_rpc_method_handler(behavior,
1538 request_deserializer=None,
1539 response_serializer=None):
1540 """Creates an RpcMethodHandler for a stream-stream RPC method.
1543 behavior: The implementation of an RPC that accepts an iterator of
1544 request values and returns an iterator of response values.
1545 request_deserializer: An optional behavior for request deserialization.
1546 response_serializer: An optional behavior for response serialization.
1549 An RpcMethodHandler object that is typically used by grpc.Server.
1551 from grpc import _utilities # pylint: disable=cyclic-import
1552 return _utilities.RpcMethodHandler(True, True, request_deserializer,
1553 response_serializer, None, None, None,
1557 def method_handlers_generic_handler(service, method_handlers):
1558 """Creates a GenericRpcHandler from RpcMethodHandlers.
1561 service: The name of the service that is implemented by the
1563 method_handlers: A dictionary that maps method names to corresponding
1567 A GenericRpcHandler. This is typically added to the grpc.Server object
1568 with add_generic_rpc_handlers() before starting the server.
1570 from grpc import _utilities # pylint: disable=cyclic-import
1571 return _utilities.DictionaryGenericHandler(service, method_handlers)
1574 def ssl_channel_credentials(root_certificates=None,
1576 certificate_chain=None):
1577 """Creates a ChannelCredentials for use with an SSL-enabled Channel.
1580 root_certificates: The PEM-encoded root certificates as a byte string,
1581 or None to retrieve them from a default location chosen by gRPC
1583 private_key: The PEM-encoded private key as a byte string, or None if no
1584 private key should be used.
1585 certificate_chain: The PEM-encoded certificate chain as a byte string
1586 to use or or None if no certificate chain should be used.
1589 A ChannelCredentials for use with an SSL-enabled Channel.
1591 return ChannelCredentials(
1592 _cygrpc.SSLChannelCredentials(root_certificates, private_key,
1596 def metadata_call_credentials(metadata_plugin, name=None):
1597 """Construct CallCredentials from an AuthMetadataPlugin.
1600 metadata_plugin: An AuthMetadataPlugin to use for authentication.
1601 name: An optional name for the plugin.
1606 from grpc import _plugin_wrapping # pylint: disable=cyclic-import
1607 return _plugin_wrapping.metadata_plugin_call_credentials(
1608 metadata_plugin, name)
1611 def access_token_call_credentials(access_token):
1612 """Construct CallCredentials from an access token.
1615 access_token: A string to place directly in the http request
1616 authorization header, for example
1617 "authorization: Bearer <access_token>".
1622 from grpc import _auth # pylint: disable=cyclic-import
1623 from grpc import _plugin_wrapping # pylint: disable=cyclic-import
1624 return _plugin_wrapping.metadata_plugin_call_credentials(
1625 _auth.AccessTokenAuthMetadataPlugin(access_token), None)
1628 def composite_call_credentials(*call_credentials):
1629 """Compose multiple CallCredentials to make a new CallCredentials.
1632 *call_credentials: At least two CallCredentials objects.
1635 A CallCredentials object composed of the given CallCredentials objects.
1637 return CallCredentials(
1638 _cygrpc.CompositeCallCredentials(
1639 tuple(single_call_credentials._credentials
1640 for single_call_credentials in call_credentials)))
1643 def composite_channel_credentials(channel_credentials, *call_credentials):
1644 """Compose a ChannelCredentials and one or more CallCredentials objects.
1647 channel_credentials: A ChannelCredentials object.
1648 *call_credentials: One or more CallCredentials objects.
1651 A ChannelCredentials composed of the given ChannelCredentials and
1652 CallCredentials objects.
1654 return ChannelCredentials(
1655 _cygrpc.CompositeChannelCredentials(
1656 tuple(single_call_credentials._credentials
1657 for single_call_credentials in call_credentials),
1658 channel_credentials._credentials))
1661 def ssl_server_credentials(private_key_certificate_chain_pairs,
1662 root_certificates=None,
1663 require_client_auth=False):
1664 """Creates a ServerCredentials for use with an SSL-enabled Server.
1667 private_key_certificate_chain_pairs: A list of pairs of the form
1668 [PEM-encoded private key, PEM-encoded certificate chain].
1669 root_certificates: An optional byte string of PEM-encoded client root
1670 certificates that the server will use to verify client authentication.
1671 If omitted, require_client_auth must also be False.
1672 require_client_auth: A boolean indicating whether or not to require
1673 clients to be authenticated. May only be True if root_certificates
1677 A ServerCredentials for use with an SSL-enabled Server. Typically, this
1678 object is an argument to add_secure_port() method during server setup.
1680 if not private_key_certificate_chain_pairs:
1682 'At least one private key-certificate chain pair is required!')
1683 elif require_client_auth and root_certificates is None:
1685 'Illegal to require client auth without providing root certificates!'
1688 return ServerCredentials(
1689 _cygrpc.server_credentials_ssl(root_certificates, [
1690 _cygrpc.SslPemKeyCertPair(key, pem)
1691 for key, pem in private_key_certificate_chain_pairs
1692 ], require_client_auth))
1695 def ssl_server_certificate_configuration(private_key_certificate_chain_pairs,
1696 root_certificates=None):
1697 """Creates a ServerCertificateConfiguration for use with a Server.
1700 private_key_certificate_chain_pairs: A collection of pairs of
1701 the form [PEM-encoded private key, PEM-encoded certificate
1703 root_certificates: An optional byte string of PEM-encoded client root
1704 certificates that the server will use to verify client authentication.
1707 A ServerCertificateConfiguration that can be returned in the certificate
1708 configuration fetching callback.
1710 if private_key_certificate_chain_pairs:
1711 return ServerCertificateConfiguration(
1712 _cygrpc.server_certificate_config_ssl(root_certificates, [
1713 _cygrpc.SslPemKeyCertPair(key, pem)
1714 for key, pem in private_key_certificate_chain_pairs
1718 'At least one private key-certificate chain pair is required!')
1721 def dynamic_ssl_server_credentials(initial_certificate_configuration,
1722 certificate_configuration_fetcher,
1723 require_client_authentication=False):
1724 """Creates a ServerCredentials for use with an SSL-enabled Server.
1727 initial_certificate_configuration (ServerCertificateConfiguration): The
1728 certificate configuration with which the server will be initialized.
1729 certificate_configuration_fetcher (callable): A callable that takes no
1730 arguments and should return a ServerCertificateConfiguration to
1731 replace the server's current certificate, or None for no change
1732 (i.e., the server will continue its current certificate
1733 config). The library will call this callback on *every* new
1734 client connection before starting the TLS handshake with the
1735 client, thus allowing the user application to optionally
1736 return a new ServerCertificateConfiguration that the server will then
1737 use for the handshake.
1738 require_client_authentication: A boolean indicating whether or not to
1739 require clients to be authenticated.
1742 A ServerCredentials.
1744 return ServerCredentials(
1745 _cygrpc.server_credentials_ssl_dynamic_cert_config(
1746 initial_certificate_configuration,
1747 certificate_configuration_fetcher, require_client_authentication))
1751 class LocalConnectionType(enum.Enum):
1752 """Types of local connection for local credential creation.
1755 UDS: Unix domain socket connections
1756 LOCAL_TCP: Local TCP connections.
1758 UDS = _cygrpc.LocalConnectionType.uds
1759 LOCAL_TCP = _cygrpc.LocalConnectionType.local_tcp
1762 def local_channel_credentials(local_connect_type=LocalConnectionType.LOCAL_TCP):
1763 """Creates a local ChannelCredentials used for local connections.
1765 This is an EXPERIMENTAL API.
1767 Local credentials are used by local TCP endpoints (e.g. localhost:10000)
1768 also UDS connections. It allows them to create secure channel, hence
1769 transmitting call credentials become possible.
1771 It is useful for 1) eliminating insecure_channel usage; 2) enable unit
1772 testing for call credentials without setting up secrets.
1775 local_connect_type: Local connection type (either
1776 grpc.LocalConnectionType.UDS or grpc.LocalConnectionType.LOCAL_TCP)
1779 A ChannelCredentials for use with a local Channel
1781 return ChannelCredentials(
1782 _cygrpc.channel_credentials_local(local_connect_type.value))
1785 def local_server_credentials(local_connect_type=LocalConnectionType.LOCAL_TCP):
1786 """Creates a local ServerCredentials used for local connections.
1788 This is an EXPERIMENTAL API.
1790 Local credentials are used by local TCP endpoints (e.g. localhost:10000)
1791 also UDS connections. It allows them to create secure channel, hence
1792 transmitting call credentials become possible.
1794 It is useful for 1) eliminating insecure_channel usage; 2) enable unit
1795 testing for call credentials without setting up secrets.
1798 local_connect_type: Local connection type (either
1799 grpc.LocalConnectionType.UDS or grpc.LocalConnectionType.LOCAL_TCP)
1802 A ServerCredentials for use with a local Server
1804 return ServerCredentials(
1805 _cygrpc.server_credentials_local(local_connect_type.value))
1808 def channel_ready_future(channel):
1809 """Creates a Future that tracks when a Channel is ready.
1811 Cancelling the Future does not affect the channel's state machine.
1812 It merely decouples the Future from channel state machine.
1815 channel: A Channel object.
1818 A Future object that matures when the channel connectivity is
1819 ChannelConnectivity.READY.
1821 from grpc import _utilities # pylint: disable=cyclic-import
1822 return _utilities.channel_ready_future(channel)
1825 def insecure_channel(target, options=None, compression=None):
1826 """Creates an insecure Channel to a server.
1828 The returned Channel is thread-safe.
1831 target: The server address
1832 options: An optional list of key-value pairs (channel args
1833 in gRPC Core runtime) to configure the channel.
1834 compression: An optional value indicating the compression method to be
1835 used over the lifetime of the channel. This is an EXPERIMENTAL option.
1840 from grpc import _channel # pylint: disable=cyclic-import
1841 return _channel.Channel(target, ()
1842 if options is None else options, None, compression)
1845 def secure_channel(target, credentials, options=None, compression=None):
1846 """Creates a secure Channel to a server.
1848 The returned Channel is thread-safe.
1851 target: The server address.
1852 credentials: A ChannelCredentials instance.
1853 options: An optional list of key-value pairs (channel args
1854 in gRPC Core runtime) to configure the channel.
1855 compression: An optional value indicating the compression method to be
1856 used over the lifetime of the channel. This is an EXPERIMENTAL option.
1861 from grpc import _channel # pylint: disable=cyclic-import
1862 return _channel.Channel(target, () if options is None else options,
1863 credentials._credentials, compression)
1866 def intercept_channel(channel, *interceptors):
1867 """Intercepts a channel through a set of interceptors.
1869 This is an EXPERIMENTAL API.
1873 interceptors: Zero or more objects of type
1874 UnaryUnaryClientInterceptor,
1875 UnaryStreamClientInterceptor,
1876 StreamUnaryClientInterceptor, or
1877 StreamStreamClientInterceptor.
1878 Interceptors are given control in the order they are listed.
1881 A Channel that intercepts each invocation via the provided interceptors.
1884 TypeError: If interceptor does not derive from any of
1885 UnaryUnaryClientInterceptor,
1886 UnaryStreamClientInterceptor,
1887 StreamUnaryClientInterceptor, or
1888 StreamStreamClientInterceptor.
1890 from grpc import _interceptor # pylint: disable=cyclic-import
1891 return _interceptor.intercept_channel(channel, *interceptors)
1894 def server(thread_pool,
1898 maximum_concurrent_rpcs=None,
1900 """Creates a Server with which RPCs can be serviced.
1903 thread_pool: A futures.ThreadPoolExecutor to be used by the Server
1904 to execute RPC handlers.
1905 handlers: An optional list of GenericRpcHandlers used for executing RPCs.
1906 More handlers may be added by calling add_generic_rpc_handlers any time
1907 before the server is started.
1908 interceptors: An optional list of ServerInterceptor objects that observe
1909 and optionally manipulate the incoming RPCs before handing them over to
1910 handlers. The interceptors are given control in the order they are
1911 specified. This is an EXPERIMENTAL API.
1912 options: An optional list of key-value pairs (channel args in gRPC runtime)
1913 to configure the channel.
1914 maximum_concurrent_rpcs: The maximum number of concurrent RPCs this server
1915 will service before returning RESOURCE_EXHAUSTED status, or None to
1917 compression: An element of grpc.compression, e.g.
1918 grpc.compression.Gzip. This compression algorithm will be used for the
1919 lifetime of the server unless overridden. This is an EXPERIMENTAL option.
1924 from grpc import _server # pylint: disable=cyclic-import
1925 return _server.create_server(thread_pool, ()
1926 if handlers is None else handlers, ()
1927 if interceptors is None else interceptors, ()
1928 if options is None else options,
1929 maximum_concurrent_rpcs, compression)
1932 @contextlib.contextmanager
1933 def _create_servicer_context(rpc_event, state, request_deserializer):
1934 from grpc import _server # pylint: disable=cyclic-import
1935 context = _server._Context(rpc_event, state, request_deserializer)
1937 context._finalize_state() # pylint: disable=protected-access
1941 class Compression(enum.IntEnum):
1942 """Indicates the compression method to be used for an RPC.
1944 This enumeration is part of an EXPERIMENTAL API.
1947 NoCompression: Do not use compression algorithm.
1948 Deflate: Use "Deflate" compression algorithm.
1949 Gzip: Use "Gzip" compression algorithm.
1951 NoCompression = _compression.NoCompression
1952 Deflate = _compression.Deflate
1953 Gzip = _compression.Gzip
1956 ################################### __all__ #################################
1959 'FutureTimeoutError',
1960 'FutureCancelledError',
1962 'ChannelConnectivity',
1968 'ChannelCredentials',
1970 'AuthMetadataContext',
1971 'AuthMetadataPluginCallback',
1972 'AuthMetadataPlugin',
1974 'ClientCallDetails',
1975 'ServerCertificateConfiguration',
1976 'ServerCredentials',
1977 'LocalConnectionType',
1978 'UnaryUnaryMultiCallable',
1979 'UnaryStreamMultiCallable',
1980 'StreamUnaryMultiCallable',
1981 'StreamStreamMultiCallable',
1982 'UnaryUnaryClientInterceptor',
1983 'UnaryStreamClientInterceptor',
1984 'StreamUnaryClientInterceptor',
1985 'StreamStreamClientInterceptor',
1989 'HandlerCallDetails',
1990 'GenericRpcHandler',
1991 'ServiceRpcHandler',
1993 'ServerInterceptor',
1994 'unary_unary_rpc_method_handler',
1995 'unary_stream_rpc_method_handler',
1996 'stream_unary_rpc_method_handler',
1997 'stream_stream_rpc_method_handler',
1998 'method_handlers_generic_handler',
1999 'ssl_channel_credentials',
2000 'metadata_call_credentials',
2001 'access_token_call_credentials',
2002 'composite_call_credentials',
2003 'composite_channel_credentials',
2004 'local_channel_credentials',
2005 'local_server_credentials',
2006 'ssl_server_credentials',
2007 'ssl_server_certificate_configuration',
2008 'dynamic_ssl_server_credentials',
2009 'channel_ready_future',
2012 'intercept_channel',
2016 ############################### Extension Shims ################################
2018 # Here to maintain backwards compatibility; avoid using these in new code!
2021 sys.modules.update({'grpc.tools': grpc_tools})
2026 sys.modules.update({'grpc.health': grpc_health})
2030 import grpc_reflection
2031 sys.modules.update({'grpc.reflection': grpc_reflection})