162 lines
4.8 KiB
ReStructuredText
162 lines
4.8 KiB
ReStructuredText
Pure-Python gRPC implementation for asyncio
|
|
===========================================
|
|
|
|
.. image:: https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/7e1631d13476f1e870af0d5605b643fc14471a6d/banner-direct-single.svg
|
|
:target: https://standforukraine.com
|
|
|
|
|project|_ |documentation|_ |version|_ |tag|_ |downloads|_ |license|_
|
|
|
|
This project is based on `hyper-h2`_ and **requires Python >= 3.7**.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
See `examples`_ directory in the project's repository for all available
|
|
examples.
|
|
|
|
Client
|
|
------
|
|
|
|
.. code-block:: python3
|
|
|
|
import asyncio
|
|
|
|
from grpclib.client import Channel
|
|
|
|
# generated by protoc
|
|
from .helloworld_pb2 import HelloRequest, HelloReply
|
|
from .helloworld_grpc import GreeterStub
|
|
|
|
|
|
async def main():
|
|
async with Channel('127.0.0.1', 50051) as channel:
|
|
greeter = GreeterStub(channel)
|
|
|
|
reply = await greeter.SayHello(HelloRequest(name='Dr. Strange'))
|
|
print(reply.message)
|
|
|
|
|
|
if __name__ == '__main__':
|
|
asyncio.run(main())
|
|
|
|
Server
|
|
------
|
|
|
|
.. code-block:: python3
|
|
|
|
import asyncio
|
|
|
|
from grpclib.utils import graceful_exit
|
|
from grpclib.server import Server
|
|
|
|
# generated by protoc
|
|
from .helloworld_pb2 import HelloReply
|
|
from .helloworld_grpc import GreeterBase
|
|
|
|
|
|
class Greeter(GreeterBase):
|
|
|
|
async def SayHello(self, stream):
|
|
request = await stream.recv_message()
|
|
message = f'Hello, {request.name}!'
|
|
await stream.send_message(HelloReply(message=message))
|
|
|
|
|
|
async def main(*, host='127.0.0.1', port=50051):
|
|
server = Server([Greeter()])
|
|
# Note: graceful_exit isn't supported in Windows
|
|
with graceful_exit([server]):
|
|
await server.start(host, port)
|
|
print(f'Serving on {host}:{port}')
|
|
await server.wait_closed()
|
|
|
|
|
|
if __name__ == '__main__':
|
|
asyncio.run(main())
|
|
|
|
Installation
|
|
~~~~~~~~~~~~
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install "grpclib[protobuf]"
|
|
|
|
Bug fixes and new features are frequently published via release candidates:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install --upgrade --pre "grpclib[protobuf]"
|
|
|
|
For the code generation you will also need a ``protoc`` compiler, which can be
|
|
installed with ``protobuf`` system package:
|
|
|
|
.. code-block:: console
|
|
|
|
$ brew install protobuf # example for macOS users
|
|
$ protoc --version
|
|
libprotoc ...
|
|
|
|
|
|
**Or** you can use ``protoc`` compiler from the ``grpcio-tools`` Python package:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install grpcio-tools
|
|
$ python3 -m grpc_tools.protoc --version
|
|
libprotoc ...
|
|
|
|
**Note:** ``grpcio`` and ``grpcio-tools`` packages are **not required in
|
|
runtime**, ``grpcio-tools`` package will be used only during code generation.
|
|
|
|
``protoc`` plugin
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
In order to use this library you will have to generate special stub files using
|
|
plugin provided, which can be used like this:
|
|
|
|
.. code-block:: console
|
|
|
|
$ python3 -m grpc_tools.protoc -I. --python_out=. --grpclib_python_out=. helloworld/helloworld.proto
|
|
^----- note -----^
|
|
|
|
This command will generate ``helloworld_pb2.py`` and ``helloworld_grpc.py``
|
|
files.
|
|
|
|
Plugin which implements ``--grpclib_python_out`` option should be available for
|
|
the ``protoc`` compiler as the ``protoc-gen-grpclib_python`` executable which
|
|
should be installed by ``pip`` into your ``$PATH`` during installation of the
|
|
``grpclib`` library.
|
|
|
|
Changed in v0.3.2: ``--python_grpc_out`` option was renamed into
|
|
``--grpclib_python_out``.
|
|
|
|
Contributing
|
|
~~~~~~~~~~~~
|
|
|
|
* Please submit an issue before working on a Pull Request
|
|
* Do not merge/squash/rebase your development branch while you work on a Pull
|
|
Request, use rebase if this is really necessary
|
|
* You may use Tox_ in order to test and lint your changes, but it is Ok to rely
|
|
on CI for this matter
|
|
|
|
.. _gRPC: http://www.grpc.io
|
|
.. _hyper-h2: https://github.com/python-hyper/hyper-h2
|
|
.. _grpcio: https://pypi.org/project/grpcio/
|
|
.. _Tox: https://tox.readthedocs.io/
|
|
.. _examples: https://github.com/vmagamedov/grpclib/tree/master/examples
|
|
.. |version| image:: https://img.shields.io/pypi/v/grpclib.svg?label=stable&color=blue
|
|
.. _version: https://pypi.org/project/grpclib/
|
|
.. |license| image:: https://img.shields.io/pypi/l/grpclib.svg?color=blue
|
|
.. _license: https://github.com/vmagamedov/grpclib/blob/master/LICENSE.txt
|
|
.. |tag| image:: https://img.shields.io/github/tag/vmagamedov/grpclib.svg?label=latest&color=blue
|
|
.. _tag: https://pypi.org/project/grpclib/#history
|
|
.. |project| image:: https://img.shields.io/badge/vmagamedov%2Fgrpclib-blueviolet.svg?logo=github&color=blue
|
|
.. _project: https://github.com/vmagamedov/grpclib
|
|
.. |documentation| image:: https://img.shields.io/badge/docs-grpclib.rtfd.io-blue.svg
|
|
.. _documentation: https://grpclib.readthedocs.io/en/latest/
|
|
.. |downloads| image:: https://static.pepy.tech/badge/grpclib/month
|
|
.. _downloads: https://pepy.tech/project/grpclib
|