Pure-Python gRPC implementation for asyncio

This project is based on hyper-h2 and requires Python >= 3.6.

• Example
  • Client
  • Server
• Installation
• protoc plugin
• Contributing

Example

See examples directory in the project's repository for all available examples.

Client

import asyncio

from grpclib.client import Channel

# generated by protoc
from .helloworld_pb2 import HelloRequest, HelloReply
from .helloworld_grpc import GreeterStub


async def main():
    channel = Channel('127.0.0.1', 50051)
    greeter = GreeterStub(channel)

    reply: HelloReply = await greeter.SayHello(HelloRequest(name='Dr. Strange'))
    print(reply.message)

    channel.close()


if __name__ == '__main__':
    asyncio.run(main())

Server

import asyncio

from grpclib.utils import graceful_exit
from grpclib.server import Server

# generated by protoc
from .helloworld_pb2 import HelloRequest, HelloReply
from .helloworld_grpc import GreeterBase


class Greeter(GreeterBase):

    async def SayHello(self, stream):
        request: HelloRequest = 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()])
    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

$ pip3 install grpclib protobuf

Bug fixes and new features are frequently published via release candidates:

$ pip3 install --upgrade --pre grpclib

For the code generation you will also need a protoc compiler, which can be installed with protobuf system package:

$ brew install protobuf  # example for macOS users
$ protoc --version
libprotoc ...

Or you can use protoc compiler from the grpcio-tools Python package:

$ 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:

$ python3 -m grpc_tools.protoc -I. --python_out=. --python_grpc_out=. helloworld/helloworld.proto

This command will generate helloworld_pb2.py and helloworld_grpc.py files.

Plugin, which implements --python_grpc_out option is available for protoc compiler as protoc-gen-python_grpc executable, which will be installed by pip/setuptools into your $PATH during installation of the grpclib library.

Contributing

Use Tox in order to test and lint your changes.