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.
pip install "grpclib[protobuf]"Verified import paths — ran on the pinned version, not inferred.
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.
Ensure your `protobuf` package (`pip install --upgrade protobuf`) and `protoc` compiler (`brew upgrade protobuf` or similar) are up-to-date when upgrading `grpclib`.
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`.
Remove the `loop` argument from calls to `Channel`, `Server`, and other public APIs where it was previously accepted. `asyncio.run()` will handle loop management.
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.
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.
Run the `protoc` compiler with the `grpclib` plugin to generate stubs for your `.proto` files. Example: `python3 -m grpc_tools.protoc -I. --python_out=. --grpclib_python_out=. your_service.proto`. Ensure the generated files are placed in a location discoverable by your Python application (e.g., in the same directory as your Python script or added to `PYTHONPATH`).
On the client, catch `GRPCError` and inspect `error.status` and `error.message` to handle specific gRPC status codes. On the server, raise `GRPCError` with an appropriate `Status` enum value and an optional message to signal specific failures to the client.
Ensure both client and server applications handle stream closures gracefully; clients should call `stream.end()` for streaming calls, and servers should handle `asyncio.CancelledError` in request handlers during shutdown. Consider enabling `grpclib` debugging logs for more insights into the HTTP/2 frames.
Ensure `__init__.py` files exist in all directories forming the Python package structure. Generate the protobuf files using the `protoc` command with correct `-I` (proto import path) and output (`--python_out`, `--grpclib_python_out`) arguments, relative to the root of your Python package. Adjust Python import statements to reflect the correct package structure (e.g., `from . import your_service_pb2`).
If you intend to use `grpcio`'s async API, ensure `grpcio` is installed and updated to a version that supports `grpc.aio`. If you are using `grpclib`, use its native asynchronous components like `grpclib.client.Channel` and `grpclib.server.Server` instead of `grpc.aio` constructs.
This error often points to deeper issues. Review full tracebacks for details. Check for misconfigured proxies, load balancers, or firewalls that might be interfering with HTTP/2 traffic. Ensure `grpclib` versions are compatible across client and server if possible, and that both sides are handling HTTP/2 streams according to the gRPC protocol.