Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/grpc/aio/_base_channel.py: 100%
42 statements
« prev ^ index » next coverage.py v7.2.2, created at 2023-03-26 07:30 +0000
1# Copyright 2020 The gRPC Authors
2#
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
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
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"""Abstract base classes for Channel objects and Multicallable objects."""
16import abc
17from typing import Any, Optional
19import grpc
21from . import _base_call
22from ._typing import DeserializingFunction
23from ._typing import MetadataType
24from ._typing import RequestIterableType
25from ._typing import SerializingFunction
28class UnaryUnaryMultiCallable(abc.ABC):
29 """Enables asynchronous invocation of a unary-call RPC."""
31 @abc.abstractmethod
32 def __call__(
33 self,
34 request: Any,
35 *,
36 timeout: Optional[float] = None,
37 metadata: Optional[MetadataType] = None,
38 credentials: Optional[grpc.CallCredentials] = None,
39 wait_for_ready: Optional[bool] = None,
40 compression: Optional[grpc.Compression] = None
41 ) -> _base_call.UnaryUnaryCall:
42 """Asynchronously invokes the underlying RPC.
44 Args:
45 request: The request value for the RPC.
46 timeout: An optional duration of time in seconds to allow
47 for the RPC.
48 metadata: Optional :term:`metadata` to be transmitted to the
49 service-side of the RPC.
50 credentials: An optional CallCredentials for the RPC. Only valid for
51 secure Channel.
52 wait_for_ready: This is an EXPERIMENTAL argument. An optional
53 flag to enable :term:`wait_for_ready` mechanism.
54 compression: An element of grpc.compression, e.g.
55 grpc.compression.Gzip. This is an EXPERIMENTAL option.
57 Returns:
58 A UnaryUnaryCall object.
60 Raises:
61 RpcError: Indicates that the RPC terminated with non-OK status. The
62 raised RpcError will also be a Call for the RPC affording the RPC's
63 metadata, status code, and details.
64 """
67class UnaryStreamMultiCallable(abc.ABC):
68 """Enables asynchronous invocation of a server-streaming RPC."""
70 @abc.abstractmethod
71 def __call__(
72 self,
73 request: Any,
74 *,
75 timeout: Optional[float] = None,
76 metadata: Optional[MetadataType] = None,
77 credentials: Optional[grpc.CallCredentials] = None,
78 wait_for_ready: Optional[bool] = None,
79 compression: Optional[grpc.Compression] = None
80 ) -> _base_call.UnaryStreamCall:
81 """Asynchronously invokes the underlying RPC.
83 Args:
84 request: The request value for the RPC.
85 timeout: An optional duration of time in seconds to allow
86 for the RPC.
87 metadata: Optional :term:`metadata` to be transmitted to the
88 service-side of the RPC.
89 credentials: An optional CallCredentials for the RPC. Only valid for
90 secure Channel.
91 wait_for_ready: This is an EXPERIMENTAL argument. An optional
92 flag to enable :term:`wait_for_ready` mechanism.
93 compression: An element of grpc.compression, e.g.
94 grpc.compression.Gzip. This is an EXPERIMENTAL option.
96 Returns:
97 A UnaryStreamCall object.
99 Raises:
100 RpcError: Indicates that the RPC terminated with non-OK status. The
101 raised RpcError will also be a Call for the RPC affording the RPC's
102 metadata, status code, and details.
103 """
106class StreamUnaryMultiCallable(abc.ABC):
107 """Enables asynchronous invocation of a client-streaming RPC."""
109 @abc.abstractmethod
110 def __call__(
111 self,
112 request_iterator: Optional[RequestIterableType] = None,
113 timeout: Optional[float] = None,
114 metadata: Optional[MetadataType] = None,
115 credentials: Optional[grpc.CallCredentials] = None,
116 wait_for_ready: Optional[bool] = None,
117 compression: Optional[grpc.Compression] = None
118 ) -> _base_call.StreamUnaryCall:
119 """Asynchronously invokes the underlying RPC.
121 Args:
122 request_iterator: An optional async iterable or iterable of request
123 messages for the RPC.
124 timeout: An optional duration of time in seconds to allow
125 for the RPC.
126 metadata: Optional :term:`metadata` to be transmitted to the
127 service-side of the RPC.
128 credentials: An optional CallCredentials for the RPC. Only valid for
129 secure Channel.
130 wait_for_ready: This is an EXPERIMENTAL argument. An optional
131 flag to enable :term:`wait_for_ready` mechanism.
132 compression: An element of grpc.compression, e.g.
133 grpc.compression.Gzip. This is an EXPERIMENTAL option.
135 Returns:
136 A StreamUnaryCall object.
138 Raises:
139 RpcError: Indicates that the RPC terminated with non-OK status. The
140 raised RpcError will also be a Call for the RPC affording the RPC's
141 metadata, status code, and details.
142 """
145class StreamStreamMultiCallable(abc.ABC):
146 """Enables asynchronous invocation of a bidirectional-streaming RPC."""
148 @abc.abstractmethod
149 def __call__(
150 self,
151 request_iterator: Optional[RequestIterableType] = None,
152 timeout: Optional[float] = None,
153 metadata: Optional[MetadataType] = None,
154 credentials: Optional[grpc.CallCredentials] = None,
155 wait_for_ready: Optional[bool] = None,
156 compression: Optional[grpc.Compression] = None
157 ) -> _base_call.StreamStreamCall:
158 """Asynchronously invokes the underlying RPC.
160 Args:
161 request_iterator: An optional async iterable or iterable of request
162 messages for the RPC.
163 timeout: An optional duration of time in seconds to allow
164 for the RPC.
165 metadata: Optional :term:`metadata` to be transmitted to the
166 service-side of the RPC.
167 credentials: An optional CallCredentials for the RPC. Only valid for
168 secure Channel.
169 wait_for_ready: This is an EXPERIMENTAL argument. An optional
170 flag to enable :term:`wait_for_ready` mechanism.
171 compression: An element of grpc.compression, e.g.
172 grpc.compression.Gzip. This is an EXPERIMENTAL option.
174 Returns:
175 A StreamStreamCall object.
177 Raises:
178 RpcError: Indicates that the RPC terminated with non-OK status. The
179 raised RpcError will also be a Call for the RPC affording the RPC's
180 metadata, status code, and details.
181 """
184class Channel(abc.ABC):
185 """Enables asynchronous RPC invocation as a client.
187 Channel objects implement the Asynchronous Context Manager (aka. async
188 with) type, although they are not supportted to be entered and exited
189 multiple times.
190 """
192 @abc.abstractmethod
193 async def __aenter__(self):
194 """Starts an asynchronous context manager.
196 Returns:
197 Channel the channel that was instantiated.
198 """
200 @abc.abstractmethod
201 async def __aexit__(self, exc_type, exc_val, exc_tb):
202 """Finishes the asynchronous context manager by closing the channel.
204 Still active RPCs will be cancelled.
205 """
207 @abc.abstractmethod
208 async def close(self, grace: Optional[float] = None):
209 """Closes this Channel and releases all resources held by it.
211 This method immediately stops the channel from executing new RPCs in
212 all cases.
214 If a grace period is specified, this method wait until all active
215 RPCs are finshed, once the grace period is reached the ones that haven't
216 been terminated are cancelled. If a grace period is not specified
217 (by passing None for grace), all existing RPCs are cancelled immediately.
219 This method is idempotent.
220 """
222 @abc.abstractmethod
223 def get_state(self,
224 try_to_connect: bool = False) -> grpc.ChannelConnectivity:
225 """Checks the connectivity state of a channel.
227 This is an EXPERIMENTAL API.
229 If the channel reaches a stable connectivity state, it is guaranteed
230 that the return value of this function will eventually converge to that
231 state.
233 Args:
234 try_to_connect: a bool indicate whether the Channel should try to
235 connect to peer or not.
237 Returns: A ChannelConnectivity object.
238 """
240 @abc.abstractmethod
241 async def wait_for_state_change(
242 self,
243 last_observed_state: grpc.ChannelConnectivity,
244 ) -> None:
245 """Waits for a change in connectivity state.
247 This is an EXPERIMENTAL API.
249 The function blocks until there is a change in the channel connectivity
250 state from the "last_observed_state". If the state is already
251 different, this function will return immediately.
253 There is an inherent race between the invocation of
254 "Channel.wait_for_state_change" and "Channel.get_state". The state can
255 change arbitrary many times during the race, so there is no way to
256 observe every state transition.
258 If there is a need to put a timeout for this function, please refer to
259 "asyncio.wait_for".
261 Args:
262 last_observed_state: A grpc.ChannelConnectivity object representing
263 the last known state.
264 """
266 @abc.abstractmethod
267 async def channel_ready(self) -> None:
268 """Creates a coroutine that blocks until the Channel is READY."""
270 @abc.abstractmethod
271 def unary_unary(
272 self,
273 method: str,
274 request_serializer: Optional[SerializingFunction] = None,
275 response_deserializer: Optional[DeserializingFunction] = None
276 ) -> UnaryUnaryMultiCallable:
277 """Creates a UnaryUnaryMultiCallable for a unary-unary method.
279 Args:
280 method: The name of the RPC method.
281 request_serializer: Optional :term:`serializer` for serializing the request
282 message. Request goes unserialized in case None is passed.
283 response_deserializer: Optional :term:`deserializer` for deserializing the
284 response message. Response goes undeserialized in case None
285 is passed.
287 Returns:
288 A UnaryUnaryMultiCallable value for the named unary-unary method.
289 """
291 @abc.abstractmethod
292 def unary_stream(
293 self,
294 method: str,
295 request_serializer: Optional[SerializingFunction] = None,
296 response_deserializer: Optional[DeserializingFunction] = None
297 ) -> UnaryStreamMultiCallable:
298 """Creates a UnaryStreamMultiCallable for a unary-stream method.
300 Args:
301 method: The name of the RPC method.
302 request_serializer: Optional :term:`serializer` for serializing the request
303 message. Request goes unserialized in case None is passed.
304 response_deserializer: Optional :term:`deserializer` for deserializing the
305 response message. Response goes undeserialized in case None
306 is passed.
308 Returns:
309 A UnarySteramMultiCallable value for the named unary-stream method.
310 """
312 @abc.abstractmethod
313 def stream_unary(
314 self,
315 method: str,
316 request_serializer: Optional[SerializingFunction] = None,
317 response_deserializer: Optional[DeserializingFunction] = None
318 ) -> StreamUnaryMultiCallable:
319 """Creates a StreamUnaryMultiCallable for a stream-unary method.
321 Args:
322 method: The name of the RPC method.
323 request_serializer: Optional :term:`serializer` for serializing the request
324 message. Request goes unserialized in case None is passed.
325 response_deserializer: Optional :term:`deserializer` for deserializing the
326 response message. Response goes undeserialized in case None
327 is passed.
329 Returns:
330 A StreamUnaryMultiCallable value for the named stream-unary method.
331 """
333 @abc.abstractmethod
334 def stream_stream(
335 self,
336 method: str,
337 request_serializer: Optional[SerializingFunction] = None,
338 response_deserializer: Optional[DeserializingFunction] = None
339 ) -> StreamStreamMultiCallable:
340 """Creates a StreamStreamMultiCallable for a stream-stream method.
342 Args:
343 method: The name of the RPC method.
344 request_serializer: Optional :term:`serializer` for serializing the request
345 message. Request goes unserialized in case None is passed.
346 response_deserializer: Optional :term:`deserializer` for deserializing the
347 response message. Response goes undeserialized in case None
348 is passed.
350 Returns:
351 A StreamStreamMultiCallable value for the named stream-stream method.
352 """