grpclib

0.4.9 · active · verified Sun Mar 29

grpclib is a pure-Python implementation of the gRPC protocol for asyncio, designed to give developers full control over HTTP/2 streams. It allows for building high-performance client and server applications using asynchronous Python. The current version is 0.4.9 and it requires Python 3.10 or newer. The library receives regular updates with bug fixes and new features.

Warnings

breaking Upgrading `grpclib` often requires updating your `protobuf` installation. `grpclib` regenerates its internal protobuf files, which can introduce new minimum `protobuf` runtime version requirements. For example, v0.4.6 required `protobuf>=3.20.0`. Always check the changelog for specific version bumps.
Fix: Ensure your `protobuf` package (`pip install --upgrade protobuf`) and `protoc` compiler (`brew upgrade protobuf` or similar) are up-to-date when upgrading `grpclib`.
breaking The `protoc` plugin option `--python_grpc_out` was renamed to `--grpclib_python_out` in `grpclib` v0.3.2. Build scripts using the old option will fail.
Fix: Update your `protoc` command to use `--grpclib_python_out` instead of `--python_grpc_out` for generating `grpclib` specific stubs. Example: `python3 -m grpc_tools.protoc -I. --python_out=. --grpclib_python_out=. helloworld.proto`.
deprecated The `loop` argument in public APIs (e.g., `Channel`, `Server` constructors) has been deprecated as `asyncio` automatically manages the event loop.
Fix: Remove the `loop` argument from calls to `Channel`, `Server`, and other public APIs where it was previously accepted. `asyncio.run()` will handle loop management.
gotcha The `grpclib.utils.graceful_exit` utility, used for handling server shutdown signals, is not supported on Windows operating systems.
Fix: On Windows, implement custom signal handling (e.g., using `asyncio.Event` and `signal.signal` for `SIGINT` on Python 3.8+ if available) or an alternative shutdown mechanism for your `grpclib` server.
gotcha In v0.4.0, metadata validation was fixed. This may cause exceptions if your application was previously sending invalid metadata values that did not conform to gRPC specifications (e.g., non-printable ASCII characters for text metadata or improperly encoded binary metadata).
Fix: Ensure all metadata keys and values conform to gRPC wire format specifications: keys with `-bin` suffix for binary values (bytes type), and printable ASCII for text values (str type). `grpclib` handles base64 encoding/decoding for `-bin` suffixed values automatically.

Install

pip install "grpclib[protobuf]" Basic installation with Protobuf support
pip install grpcio-tools For Protocol Buffers code generation

Imports

Channel
```
from grpclib.client import Channel
```
Server
```
from grpclib.server import Server
```
graceful_exit
```
from grpclib.utils import graceful_exit
```
Status
```
from grpclib import Status
```
GRPCError
```
from grpclib import GRPCError
```
GreeterStub
```
from .helloworld_grpc import GreeterStub
```
Example of generated client stub import (based on 'helloworld.proto')
GreeterBase
```
from .helloworld_grpc import GreeterBase
```
Example of generated server base class import (based on 'helloworld.proto')

Quickstart

This quickstart demonstrates how to set up a basic gRPC server and client using `grpclib`. First, define your service in a `.proto` file, then use `protoc` with the `grpclib` plugin to generate Python stubs. Finally, implement your server logic and client calls using the generated stubs.

# 1. Define your service in a .proto file (e.g., helloworld.proto):
# syntax = "proto3";
# package helloworld;
# message HelloRequest { string name = 1; }
# message HelloReply { string message = 1; }
# service Greeter { rpc SayHello (HelloRequest) returns (HelloReply); }

# 2. Generate Python code from the .proto file:
# python3 -m grpc_tools.protoc -I. --python_out=. --grpclib_python_out=. helloworld.proto

# 3. Server implementation (server.py)
import asyncio
from grpclib.utils import graceful_exit
from grpclib.server import Server

# Generated by protoc from helloworld.proto
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_server(*, 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()

# 4. Client implementation (client.py)
from grpclib.client import Channel

# Generated by protoc from helloworld.proto
from helloworld_pb2 import HelloRequest, HelloReply
from helloworld_grpc import GreeterStub

async def main_client():
    async with Channel('127.0.0.1', 50051) as channel:
        greeter = GreeterStub(channel)
        reply = await greeter.SayHello(HelloRequest(name='Dr. Strange'))
        print(reply.message)

# To run the server and then the client:
# if __name__ == '__main__':
#    asyncio.run(main_server())
#    # In another terminal, run:
#    # asyncio.run(main_client())

view raw JSON →