Chiebot-Mirror
/
grpc
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve the documentation based on suggestions

Browse Source
pull/21987/head
Lidi Zheng 5 years ago
parent 479651e4cf
commit 12b0ddbc2b
3 changed files with 57 additions and 34 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 34
      doc/python/sphinx/grpc_asyncio.rst
  2. 41
      src/python/grpcio/grpc/experimental/aio/_base_channel.py
  3. 16
      src/python/grpcio/grpc/experimental/aio/_base_server.py

34
doc/python/sphinx/grpc_asyncio.rst
Unescape View File

@ -7,8 +7,9 @@ Overview
--------
gRPC AsyncIO API is the **new version** of gRPC Python whose architecture is
tailored to AsyncIO. Underlying, it is using C-Core's callback API, and
replaced all IO operations with methods provided by the AsyncIO library.
tailored to AsyncIO. Underlying, it utilizes the same C-extension, gRPC C-Core,
as existing stack, and it replaces all gRPC IO operations with methods provided
by the AsyncIO library.
This stack currently is under active development. Feel free to offer
suggestions by opening issues on our GitHub repo `grpc/grpc <https://github.com/grpc/grpc>`_.
@ -26,23 +27,34 @@ created. AsyncIO doesn't provide thread safety for most of its APIs.
Module Contents
---------------
Turn-On AsyncIO Mode
^^^^^^^^^^^^^^^^^^^^
Enable AsyncIO in gRPC
^^^^^^^^^^^^^^^^^^^^^^
.. function:: init_grpc_aio
Turn-on AsyncIO mode for gRPC Python.
Enable AsyncIO for gRPC Python.
This function is idempotent, and it should be invoked before creation of
This function is idempotent and it should be invoked before creation of
AsyncIO stack objects. Otherwise, the application might deadlock.
This function enables AsyncIO IO manager and disables threading for entire
process. After this point, there should not be blocking calls unless it is
taken cared by AsyncIO.
This function configurates the gRPC C-Core to invoke AsyncIO methods for IO
operations (e.g., socket read, write). The configuration applies to the
entire process.
After invoking this function, making blocking function calls in coroutines
or in the thread running event loop will block the event loop, potentially
starving all RPCs in the process. Refer to the Python language
documentation on AsyncIO for more details (`running-blocking-code <https://docs.python.org/3/library/asyncio-dev.html#running-blocking-code>`_).
Create Client
^^^^^^^^^^^^^
Create Channel
^^^^^^^^^^^^^^
Channels are the abstraction of clients, where most of networking logic
happens, for example, managing one or more underlying connections, name
resolution, load balancing, flow control, etc.. If you are using ProtoBuf,
Channel objects works best when further encapsulate into stub objects, then the
application can invoke remote functions as if they are local functions.
.. autofunction:: insecure_channel
.. autofunction:: secure_channel

41
src/python/grpcio/grpc/experimental/aio/_base_channel.py
Unescape View File

@ -25,7 +25,7 @@ _IMMUTABLE_EMPTY_TUPLE = tuple()
class UnaryUnaryMultiCallable(abc.ABC):
"""Factory an asynchronous unary-unary RPC stub call from client-side."""
"""Enables asynchronous invocation of a unary-call RPC."""
@abc.abstractmethod
def __call__(self,
@ -53,17 +53,17 @@ class UnaryUnaryMultiCallable(abc.ABC):
grpc.compression.Gzip. This is an EXPERIMENTAL option.
Returns:
A Call object instance which is an awaitable object.
A UnaryUnaryCall object.
Raises:
RpcError: Indicating that the RPC terminated with non-OK status. The
RpcError: Indicates that the RPC terminated with non-OK status. The
raised RpcError will also be a Call for the RPC affording the RPC's
metadata, status code, and details.
"""
class UnaryStreamMultiCallable(abc.ABC):
"""Affords invoking a unary-stream RPC from client-side in an asynchronous way."""
"""Enables asynchronous invocation of a server-streaming RPC."""
@abc.abstractmethod
def __call__(self,
@ -91,12 +91,17 @@ class UnaryStreamMultiCallable(abc.ABC):
grpc.compression.Gzip. This is an EXPERIMENTAL option.
Returns:
A Call object instance which is an awaitable object.
A UnaryStreamCall object.
Raises:
RpcError: Indicates that the RPC terminated with non-OK status. The
raised RpcError will also be a Call for the RPC affording the RPC's
metadata, status code, and details.
"""
class StreamUnaryMultiCallable(abc.ABC):
"""Affords invoking a stream-unary RPC from client-side in an asynchronous way."""
"""Enables asynchronous invocation of a client-streaming RPC."""
@abc.abstractmethod
def __call__(self,
@ -123,17 +128,17 @@ class StreamUnaryMultiCallable(abc.ABC):
grpc.compression.Gzip. This is an EXPERIMENTAL option.
Returns:
A Call object instance which is an awaitable object.
A StreamUnaryCall object.
Raises:
RpcError: Indicating that the RPC terminated with non-OK status. The
RpcError: Indicates that the RPC terminated with non-OK status. The
raised RpcError will also be a Call for the RPC affording the RPC's
metadata, status code, and details.
"""
class StreamStreamMultiCallable(abc.ABC):
"""Affords invoking a stream-stream RPC from client-side in an asynchronous way."""
"""Enables asynchronous invocation of a bidirectional-streaming RPC."""
@abc.abstractmethod
def __call__(self,
@ -160,19 +165,21 @@ class StreamStreamMultiCallable(abc.ABC):
grpc.compression.Gzip. This is an EXPERIMENTAL option.
Returns:
A Call object instance which is an awaitable object.
A StreamStreamCall object.
Raises:
RpcError: Indicating that the RPC terminated with non-OK status. The
RpcError: Indicates that the RPC terminated with non-OK status. The
raised RpcError will also be a Call for the RPC affording the RPC's
metadata, status code, and details.
"""
class Channel(abc.ABC):
"""Asynchronous Channel implementation.
"""Enables asynchronous RPC invocation as a client.
A cygrpc.AioChannel-backed implementation.
Channel objects implement the Asynchronous Context Manager (aka. async
with) type, although they are not supportted to be entered and exited
multiple times.
"""
@abc.abstractmethod
@ -208,7 +215,7 @@ class Channel(abc.ABC):
@abc.abstractmethod
def get_state(self,
try_to_connect: bool = False) -> grpc.ChannelConnectivity:
"""Check the connectivity state of a channel.
"""Checks the connectivity state of a channel.
This is an EXPERIMENTAL API.
@ -228,7 +235,7 @@ class Channel(abc.ABC):
self,
last_observed_state: grpc.ChannelConnectivity,
) -> None:
"""Wait for a change in connectivity state.
"""Waits for a change in connectivity state.
This is an EXPERIMENTAL API.
@ -238,8 +245,8 @@ class Channel(abc.ABC):
There is an inherent race between the invocation of
"Channel.wait_for_state_change" and "Channel.get_state". The state can
change arbitrary times during the race, so there is no way to observe
every state transition.
change arbitrary many times during the race, so there is no way to
observe every state transition.
If there is a need to put a timeout for this function, please refer to
"asyncio.wait_for".

16
src/python/grpcio/grpc/experimental/aio/_base_server.py
Unescape View File

@ -41,6 +41,9 @@ class Server(abc.ABC):
def add_insecure_port(self, address: str) -> int:
"""Opens an insecure port for accepting RPCs.
A port is a communication endpoint that used by networking protocols,
like TCP and UDP. To date, we only support TCP.
This method may only be called before starting the server.
Args:
@ -56,6 +59,9 @@ class Server(abc.ABC):
server_credentials: grpc.ServerCredentials) -> int:
"""Opens a secure port for accepting RPCs.
A port is a communication endpoint that used by networking protocols,
like TCP and UDP. To date, we only support TCP.
This method may only be called before starting the server.
Args:
@ -102,7 +108,7 @@ class Server(abc.ABC):
@abc.abstractmethod
async def wait_for_termination(self,
timeout: Optional[float] = None) -> bool:
"""Block current coroutine until the server stops.
"""Continues current coroutine once the server stops.
This is an EXPERIMENTAL API.
@ -131,8 +137,7 @@ class ServicerContext(Generic[RequestType, ResponseType], abc.ABC):
async def read(self) -> RequestType:
"""Reads one message from the RPC.
Only one read operation is allowed simultaneously. Mixing new streaming API and old
streaming API will resulted in undefined behavior.
Only one read operation is allowed simultaneously.
Returns:
A response message of the RPC.
@ -145,8 +150,7 @@ class ServicerContext(Generic[RequestType, ResponseType], abc.ABC):
async def write(self, message: ResponseType) -> None:
"""Writes one message to the RPC.
Only one write operation is allowed simultaneously. Mixing new streaming API and old
streaming API will resulted in undefined behavior.
Only one write operation is allowed simultaneously.
Raises:
An RpcError exception if the write failed.
@ -218,7 +222,7 @@ class ServicerContext(Generic[RequestType, ResponseType], abc.ABC):
@abc.abstractmethod
def set_details(self, details: str) -> None:
"""Sets the value to be used as detail string upon RPC completion.
"""Sets the value to be used the as detail string upon RPC completion.
This method need not be called by method implementations if they have
no details to transmit.

Write Preview
Loading…
Cancel
Save