Connect for Python

Connect is the easiest way to build modern APIs.

Docs • Example • New to Connect?

Why Connect?

Building an API usually means writing the same types at least twice: once on the server, and once in every client. Connect makes this simple - define your API schema using Protobuf, and Connect generates type-safe server stubs and idiomatic client libraries in every major language, including for your frontend. All that's left to write is your business logic, in plain Python.

Connect already works with your current tech stack:

• Connect is built on top of HTTP and speaks both Protobuf and JSON, so curl works out of the box.
• It interoperates seamlessly with gRPC and gRPC-Web, and supports streaming as a first-class feature.
• It runs on WSGI/ASGI. Build Connect APIs alongside your current API framework - all in the same app.

Features

• Servers: WSGI and ASGI-ready, use with any compatible server
• Clients: Lightweight sync and async clients, backed by pyqwest
• Protocols: Supports Connect, gRPC, and gRPC-Web (HTTP/1.1 and HTTP/2)
• Type safety: Fully type-annotated generated code
• Streaming: Full support for server, client, and bidirectional streaming
• Compression: Built-in support for gzip, brotli, and zstd
• Middleware: Server- and client-side interceptors for telemetry, logging, etc.
• Compliant: Verified using the official Connect conformance test suite

Getting started

Install the runtime library:

uv add connectrpc

For codegen, install buf and create buf.gen.yaml:

version: v2plugins:
- remote: buf.build/bufbuild/pyout: gen
- remote: buf.build/connectrpc/pyout: gen

Local plugin setup

The example above uses a Buf-hosted plugin server. To generate code entirely locally, install the relevant plugins:

uv add --dev protoc-gen-py protoc-gen-connectrpc

Now edit your buf.gen.yaml:

version: v2plugins:
- local: .venv/bin/protoc-gen-pyout: gen
- local: .venv/bin/protoc-gen-connectrpcout: gen

Compatibility with google-protobuf

Connect defaults to targeting protobuf-py as the Protocol Buffers implementation, but it also supports Google's Protocol Buffers for Python. Pass protobuf=google to the codegen plugin to use it.

version: v2plugins:
- remote: buf.build/protocolbuffers/pythonout: .
- remote: buf.build/protocolbuffers/pyiout: .
- remote: buf.build/connectrpc/pyout: .opt: protobuf=google

If configuring a client for JSON codec, make sure to pass connectrpc.compat.google_protobuf_json_codec instead of connectrpc.codec.proto_json_codec.

Usage

A basic Connect server is easy to set up. Just import the stubs, subclass the generated service, and serve:

fromconnectrpc.requestimportRequestContextfromyour_service_pbimportHelloRequest, HelloResponsefromyour_service_connectimportHelloService, HelloServiceASGIApplicationclassMyHelloService(HelloService):
asyncdefsay_hello(
self, request: HelloRequest, ctx: RequestContext
) ->HelloResponse:
returnHelloResponse(message=f"Hello, {request.name}!")
# Create ASGI appapp=HelloServiceASGIApplication(MyHelloService())
# Run with any ASGI server, e.g. uvicorn:# uvicorn server:app --port 8080

Client libraries are automatically generated for you. Here's what the async client looks like:

fromyour_service_pbimportHelloRequest, HelloResponsefromyour_service_connectimportHelloServiceClientasyncdefmain():
# Create async clientasyncwithHelloServiceClient("https://api.example.com") asclient:
response=awaitclient.say_hello(HelloRequest(name="World"))
print(response.message) # "Hello, World!"

And the sync client:

fromyour_service_pbimportHelloRequestfromyour_service_connectimportHelloServiceClientSyncdefmain():
# Create sync clientwithHelloServiceClientSync("https://api.example.com") asclient:
response=client.say_hello(HelloRequest(name="World"))
print(response.message) # "Hello, World!"if__name__=="__main__":
main()

Check out the docs for more detailed usage.

• Streaming: Connect supports server-side, client-side, and bidirectional streaming.
• Interceptors: Set up middleware for logging, observability, and metrics.
• Other languages: Generate clients for use in other languages.