protoc-gen-grpc-py 0.0.1

No project description provided

protoc-gen-grpc-py

The gRPC code generator plugin for Protocol Buffers for Python. Learn more about the project at github.com/bufbuild/protobuf-py.

Overview

protoc-gen-grpc-py generates fully typed, idiomatic gRPC clients and servicers that use protobuf-py messages for serialization. Unlike the stock gRPC Python plugin, the generated stubs:

• are fully typed, so editors and type checkers understand every RPC method
• serialize protobuf-py messages directly, with no dependency on the _pb2 Protobuf runtime
• ship both asyncio (grpc.aio) and synchronous variants.

For each service it emits a servicer base class (with an add_to_server method) and a client, in both async and sync flavors (the sync names are suffixed with Sync). Message types are generated separately by protoc-gen-py.

Installation

The generated code requires the runtime libraries protobuf-py and grpcio. The plugin is compatible with Protocol Buffer compilers like buf and protoc.

$ uv add protobuf-py grpcio
$ uv add --dev protoc-gen-py protoc-gen-grpc-py buf-bin

Generating code

With buf

Add protoc-gen-grpc-py alongside protoc-gen-py in your buf.gen.yaml:

version: v2
inputs:
  - directory: proto
plugins:
  # Generates message types (*_pb.py).
  - local: protoc-gen-py
    out: src/gen
  # Generates gRPC service stubs (*_pb_grpc.py).
  - local: protoc-gen-grpc-py
    out: src/gen

To generate code for all Protobuf files within your project, run:

$ uv run -- buf generate

With protoc

$ uv run protoc --proto_path proto \
    --py_out src/gen \
    --grpc-py_out src/gen \
    proto/a.proto proto/b.proto proto/c.proto

A *_pb_grpc.py file is generated only for proto files that declare a service. The plugin does not emit __init__.py files; let protoc-gen-py manage those.

Plugin options

io

Controls which flavor of code is generated:

• unset (default): generate both asynchronous (grpc.aio) and synchronous (grpc) code;
• io=async: generate only asynchronous code;
• io=sync: generate only synchronous code.

For example, in buf.gen.yaml:

plugins:
  - local: protoc-gen-grpc-py
    out: src/gen
    opt: io=async

Example

See the gRPC example for a complete client and server using the generated stubs.