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.7, created at 2023-06-06 06:03 +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: An optional flag to enable :term:`wait_for_ready` mechanism.
53 compression: An element of grpc.compression, e.g.
54 grpc.compression.Gzip.
56 Returns:
57 A UnaryUnaryCall object.
59 Raises:
60 RpcError: Indicates that the RPC terminated with non-OK status. The
61 raised RpcError will also be a Call for the RPC affording the RPC's
62 metadata, status code, and details.
63 """
66class UnaryStreamMultiCallable(abc.ABC):
67 """Enables asynchronous invocation of a server-streaming RPC."""
69 @abc.abstractmethod
70 def __call__(
71 self,
72 request: Any,
73 *,
74 timeout: Optional[float] = None,
75 metadata: Optional[MetadataType] = None,
76 credentials: Optional[grpc.CallCredentials] = None,
77 wait_for_ready: Optional[bool] = None,
78 compression: Optional[grpc.Compression] = None
79 ) -> _base_call.UnaryStreamCall:
80 """Asynchronously invokes the underlying RPC.
82 Args:
83 request: The request value for the RPC.
84 timeout: An optional duration of time in seconds to allow
85 for the RPC.
86 metadata: Optional :term:`metadata` to be transmitted to the
87 service-side of the RPC.
88 credentials: An optional CallCredentials for the RPC. Only valid for
89 secure Channel.
90 wait_for_ready: An optional flag to enable :term:`wait_for_ready` mechanism.
91 compression: An element of grpc.compression, e.g.
92 grpc.compression.Gzip.
94 Returns:
95 A UnaryStreamCall object.
97 Raises:
98 RpcError: Indicates that the RPC terminated with non-OK status. The
99 raised RpcError will also be a Call for the RPC affording the RPC's
100 metadata, status code, and details.
101 """
104class StreamUnaryMultiCallable(abc.ABC):
105 """Enables asynchronous invocation of a client-streaming RPC."""
107 @abc.abstractmethod
108 def __call__(
109 self,
110 request_iterator: Optional[RequestIterableType] = None,
111 timeout: Optional[float] = None,
112 metadata: Optional[MetadataType] = None,
113 credentials: Optional[grpc.CallCredentials] = None,
114 wait_for_ready: Optional[bool] = None,
115 compression: Optional[grpc.Compression] = None
116 ) -> _base_call.StreamUnaryCall:
117 """Asynchronously invokes the underlying RPC.
119 Args:
120 request_iterator: An optional async iterable or iterable of request
121 messages for the RPC.
122 timeout: An optional duration of time in seconds to allow
123 for the RPC.
124 metadata: Optional :term:`metadata` to be transmitted to the
125 service-side of the RPC.
126 credentials: An optional CallCredentials for the RPC. Only valid for
127 secure Channel.
128 wait_for_ready: An optional flag to enable :term:`wait_for_ready` mechanism.
129 compression: An element of grpc.compression, e.g.
130 grpc.compression.Gzip.
132 Returns:
133 A StreamUnaryCall object.
135 Raises:
136 RpcError: Indicates that the RPC terminated with non-OK status. The
137 raised RpcError will also be a Call for the RPC affording the RPC's
138 metadata, status code, and details.
139 """
142class StreamStreamMultiCallable(abc.ABC):
143 """Enables asynchronous invocation of a bidirectional-streaming RPC."""
145 @abc.abstractmethod
146 def __call__(
147 self,
148 request_iterator: Optional[RequestIterableType] = None,
149 timeout: Optional[float] = None,
150 metadata: Optional[MetadataType] = None,
151 credentials: Optional[grpc.CallCredentials] = None,
152 wait_for_ready: Optional[bool] = None,
153 compression: Optional[grpc.Compression] = None
154 ) -> _base_call.StreamStreamCall:
155 """Asynchronously invokes the underlying RPC.
157 Args:
158 request_iterator: An optional async iterable or iterable of request
159 messages for the RPC.
160 timeout: An optional duration of time in seconds to allow
161 for the RPC.
162 metadata: Optional :term:`metadata` to be transmitted to the
163 service-side of the RPC.
164 credentials: An optional CallCredentials for the RPC. Only valid for
165 secure Channel.
166 wait_for_ready: An optional flag to enable :term:`wait_for_ready` mechanism.
167 compression: An element of grpc.compression, e.g.
168 grpc.compression.Gzip.
170 Returns:
171 A StreamStreamCall object.
173 Raises:
174 RpcError: Indicates that the RPC terminated with non-OK status. The
175 raised RpcError will also be a Call for the RPC affording the RPC's
176 metadata, status code, and details.
177 """
180class Channel(abc.ABC):
181 """Enables asynchronous RPC invocation as a client.
183 Channel objects implement the Asynchronous Context Manager (aka. async
184 with) type, although they are not supportted to be entered and exited
185 multiple times.
186 """
188 @abc.abstractmethod
189 async def __aenter__(self):
190 """Starts an asynchronous context manager.
192 Returns:
193 Channel the channel that was instantiated.
194 """
196 @abc.abstractmethod
197 async def __aexit__(self, exc_type, exc_val, exc_tb):
198 """Finishes the asynchronous context manager by closing the channel.
200 Still active RPCs will be cancelled.
201 """
203 @abc.abstractmethod
204 async def close(self, grace: Optional[float] = None):
205 """Closes this Channel and releases all resources held by it.
207 This method immediately stops the channel from executing new RPCs in
208 all cases.
210 If a grace period is specified, this method wait until all active
211 RPCs are finshed, once the grace period is reached the ones that haven't
212 been terminated are cancelled. If a grace period is not specified
213 (by passing None for grace), all existing RPCs are cancelled immediately.
215 This method is idempotent.
216 """
218 @abc.abstractmethod
219 def get_state(self,
220 try_to_connect: bool = False) -> grpc.ChannelConnectivity:
221 """Checks the connectivity state of a channel.
223 This is an EXPERIMENTAL API.
225 If the channel reaches a stable connectivity state, it is guaranteed
226 that the return value of this function will eventually converge to that
227 state.
229 Args:
230 try_to_connect: a bool indicate whether the Channel should try to
231 connect to peer or not.
233 Returns: A ChannelConnectivity object.
234 """
236 @abc.abstractmethod
237 async def wait_for_state_change(
238 self,
239 last_observed_state: grpc.ChannelConnectivity,
240 ) -> None:
241 """Waits for a change in connectivity state.
243 This is an EXPERIMENTAL API.
245 The function blocks until there is a change in the channel connectivity
246 state from the "last_observed_state". If the state is already
247 different, this function will return immediately.
249 There is an inherent race between the invocation of
250 "Channel.wait_for_state_change" and "Channel.get_state". The state can
251 change arbitrary many times during the race, so there is no way to
252 observe every state transition.
254 If there is a need to put a timeout for this function, please refer to
255 "asyncio.wait_for".
257 Args:
258 last_observed_state: A grpc.ChannelConnectivity object representing
259 the last known state.
260 """
262 @abc.abstractmethod
263 async def channel_ready(self) -> None:
264 """Creates a coroutine that blocks until the Channel is READY."""
266 @abc.abstractmethod
267 def unary_unary(
268 self,
269 method: str,
270 request_serializer: Optional[SerializingFunction] = None,
271 response_deserializer: Optional[DeserializingFunction] = None
272 ) -> UnaryUnaryMultiCallable:
273 """Creates a UnaryUnaryMultiCallable for a unary-unary method.
275 Args:
276 method: The name of the RPC method.
277 request_serializer: Optional :term:`serializer` for serializing the request
278 message. Request goes unserialized in case None is passed.
279 response_deserializer: Optional :term:`deserializer` for deserializing the
280 response message. Response goes undeserialized in case None
281 is passed.
283 Returns:
284 A UnaryUnaryMultiCallable value for the named unary-unary method.
285 """
287 @abc.abstractmethod
288 def unary_stream(
289 self,
290 method: str,
291 request_serializer: Optional[SerializingFunction] = None,
292 response_deserializer: Optional[DeserializingFunction] = None
293 ) -> UnaryStreamMultiCallable:
294 """Creates a UnaryStreamMultiCallable for a unary-stream method.
296 Args:
297 method: The name of the RPC method.
298 request_serializer: Optional :term:`serializer` for serializing the request
299 message. Request goes unserialized in case None is passed.
300 response_deserializer: Optional :term:`deserializer` for deserializing the
301 response message. Response goes undeserialized in case None
302 is passed.
304 Returns:
305 A UnarySteramMultiCallable value for the named unary-stream method.
306 """
308 @abc.abstractmethod
309 def stream_unary(
310 self,
311 method: str,
312 request_serializer: Optional[SerializingFunction] = None,
313 response_deserializer: Optional[DeserializingFunction] = None
314 ) -> StreamUnaryMultiCallable:
315 """Creates a StreamUnaryMultiCallable for a stream-unary method.
317 Args:
318 method: The name of the RPC method.
319 request_serializer: Optional :term:`serializer` for serializing the request
320 message. Request goes unserialized in case None is passed.
321 response_deserializer: Optional :term:`deserializer` for deserializing the
322 response message. Response goes undeserialized in case None
323 is passed.
325 Returns:
326 A StreamUnaryMultiCallable value for the named stream-unary method.
327 """
329 @abc.abstractmethod
330 def stream_stream(
331 self,
332 method: str,
333 request_serializer: Optional[SerializingFunction] = None,
334 response_deserializer: Optional[DeserializingFunction] = None
335 ) -> StreamStreamMultiCallable:
336 """Creates a StreamStreamMultiCallable for a stream-stream method.
338 Args:
339 method: The name of the RPC method.
340 request_serializer: Optional :term:`serializer` for serializing the request
341 message. Request goes unserialized in case None is passed.
342 response_deserializer: Optional :term:`deserializer` for deserializing the
343 response message. Response goes undeserialized in case None
344 is passed.
346 Returns:
347 A StreamStreamMultiCallable value for the named stream-stream method.
348 """