Spaces:
Running
Running
| # Copyright 2019 The gRPC Authors | |
| # | |
| # Licensed under the Apache License, Version 2.0 (the "License"); | |
| # you may not use this file except in compliance with the License. | |
| # You may obtain a copy of the License at | |
| # | |
| # http://www.apache.org/licenses/LICENSE-2.0 | |
| # | |
| # Unless required by applicable law or agreed to in writing, software | |
| # distributed under the License is distributed on an "AS IS" BASIS, | |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| # See the License for the specific language governing permissions and | |
| # limitations under the License. | |
| """Abstract base classes for client-side Call objects. | |
| Call objects represents the RPC itself, and offer methods to access / modify | |
| its information. They also offer methods to manipulate the life-cycle of the | |
| RPC, e.g. cancellation. | |
| """ | |
| from abc import ABCMeta | |
| from abc import abstractmethod | |
| from typing import Any, AsyncIterator, Generator, Generic, Optional, Union | |
| import grpc | |
| from ._metadata import Metadata | |
| from ._typing import DoneCallbackType | |
| from ._typing import EOFType | |
| from ._typing import RequestType | |
| from ._typing import ResponseType | |
| __all__ = "RpcContext", "Call", "UnaryUnaryCall", "UnaryStreamCall" | |
| class RpcContext(metaclass=ABCMeta): | |
| """Provides RPC-related information and action.""" | |
| def cancelled(self) -> bool: | |
| """Return True if the RPC is cancelled. | |
| The RPC is cancelled when the cancellation was requested with cancel(). | |
| Returns: | |
| A bool indicates whether the RPC is cancelled or not. | |
| """ | |
| def done(self) -> bool: | |
| """Return True if the RPC is done. | |
| An RPC is done if the RPC is completed, cancelled or aborted. | |
| Returns: | |
| A bool indicates if the RPC is done. | |
| """ | |
| def time_remaining(self) -> Optional[float]: | |
| """Describes the length of allowed time remaining for the RPC. | |
| Returns: | |
| A nonnegative float indicating the length of allowed time in seconds | |
| remaining for the RPC to complete before it is considered to have | |
| timed out, or None if no deadline was specified for the RPC. | |
| """ | |
| def cancel(self) -> bool: | |
| """Cancels the RPC. | |
| Idempotent and has no effect if the RPC has already terminated. | |
| Returns: | |
| A bool indicates if the cancellation is performed or not. | |
| """ | |
| def add_done_callback(self, callback: DoneCallbackType) -> None: | |
| """Registers a callback to be called on RPC termination. | |
| Args: | |
| callback: A callable object will be called with the call object as | |
| its only argument. | |
| """ | |
| class Call(RpcContext, metaclass=ABCMeta): | |
| """The abstract base class of an RPC on the client-side.""" | |
| async def initial_metadata(self) -> Metadata: | |
| """Accesses the initial metadata sent by the server. | |
| Returns: | |
| The initial :term:`metadata`. | |
| """ | |
| async def trailing_metadata(self) -> Metadata: | |
| """Accesses the trailing metadata sent by the server. | |
| Returns: | |
| The trailing :term:`metadata`. | |
| """ | |
| async def code(self) -> grpc.StatusCode: | |
| """Accesses the status code sent by the server. | |
| Returns: | |
| The StatusCode value for the RPC. | |
| """ | |
| async def details(self) -> str: | |
| """Accesses the details sent by the server. | |
| Returns: | |
| The details string of the RPC. | |
| """ | |
| async def wait_for_connection(self) -> None: | |
| """Waits until connected to peer and raises aio.AioRpcError if failed. | |
| This is an EXPERIMENTAL method. | |
| This method ensures the RPC has been successfully connected. Otherwise, | |
| an AioRpcError will be raised to explain the reason of the connection | |
| failure. | |
| This method is recommended for building retry mechanisms. | |
| """ | |
| class UnaryUnaryCall( | |
| Generic[RequestType, ResponseType], Call, metaclass=ABCMeta | |
| ): | |
| """The abstract base class of an unary-unary RPC on the client-side.""" | |
| def __await__(self) -> Generator[Any, None, ResponseType]: | |
| """Await the response message to be ready. | |
| Returns: | |
| The response message of the RPC. | |
| """ | |
| class UnaryStreamCall( | |
| Generic[RequestType, ResponseType], Call, metaclass=ABCMeta | |
| ): | |
| def __aiter__(self) -> AsyncIterator[ResponseType]: | |
| """Returns the async iterator representation that yields messages. | |
| Under the hood, it is calling the "read" method. | |
| Returns: | |
| An async iterator object that yields messages. | |
| """ | |
| async def read(self) -> Union[EOFType, ResponseType]: | |
| """Reads one message from the stream. | |
| Read operations must be serialized when called from multiple | |
| coroutines. | |
| Note that the iterator and read/write APIs may not be mixed on | |
| a single RPC. | |
| Returns: | |
| A response message, or an `grpc.aio.EOF` to indicate the end of the | |
| stream. | |
| """ | |
| class StreamUnaryCall( | |
| Generic[RequestType, ResponseType], Call, metaclass=ABCMeta | |
| ): | |
| async def write(self, request: RequestType) -> None: | |
| """Writes one message to the stream. | |
| Note that the iterator and read/write APIs may not be mixed on | |
| a single RPC. | |
| Raises: | |
| An RpcError exception if the write failed. | |
| """ | |
| async def done_writing(self) -> None: | |
| """Notifies server that the client is done sending messages. | |
| After done_writing is called, any additional invocation to the write | |
| function will fail. This function is idempotent. | |
| """ | |
| def __await__(self) -> Generator[Any, None, ResponseType]: | |
| """Await the response message to be ready. | |
| Returns: | |
| The response message of the stream. | |
| """ | |
| class StreamStreamCall( | |
| Generic[RequestType, ResponseType], Call, metaclass=ABCMeta | |
| ): | |
| def __aiter__(self) -> AsyncIterator[ResponseType]: | |
| """Returns the async iterator representation that yields messages. | |
| Under the hood, it is calling the "read" method. | |
| Returns: | |
| An async iterator object that yields messages. | |
| """ | |
| async def read(self) -> Union[EOFType, ResponseType]: | |
| """Reads one message from the stream. | |
| Read operations must be serialized when called from multiple | |
| coroutines. | |
| Note that the iterator and read/write APIs may not be mixed on | |
| a single RPC. | |
| Returns: | |
| A response message, or an `grpc.aio.EOF` to indicate the end of the | |
| stream. | |
| """ | |
| async def write(self, request: RequestType) -> None: | |
| """Writes one message to the stream. | |
| Note that the iterator and read/write APIs may not be mixed on | |
| a single RPC. | |
| Raises: | |
| An RpcError exception if the write failed. | |
| """ | |
| async def done_writing(self) -> None: | |
| """Notifies server that the client is done sending messages. | |
| After done_writing is called, any additional invocation to the write | |
| function will fail. This function is idempotent. | |
| """ | |