Key Features

Installation

pip install connectrpc

pip install git+https://github.com/tsubakiky/hypercorn.git

Quick Start

1. Define your service

syntax="proto3";packageconnectrpc.ping.v1;messagePingRequest {stringmessage=1;}messagePingResponse {stringmessage=1;}servicePingService {rpcPing(PingRequest)returns (PingResponse);}

2. Generate Python code

# Install the code generatorgo install github.com/gaudiy/connect-python/cmd/protoc-gen-connect-python@latest# Generate Python codeprotoc --plugin=$(go env GOPATH)/bin/protoc-gen-connect-python -I. --connect-python_out=. --connect-python_opt=paths=source_relative ping.proto

3. Implement your service

fromconnectrpc.connectimportUnaryRequest,UnaryResponsefromconnectrpc.handler_contextimportHandlerContextfromconnectrpc.middlewareimportConnectMiddlewarefromstarlette.applicationsimportStarlettefromstarlette.middlewareimportMiddlewarefromping_pb2importPingRequest,PingResponsefromping_connect_pb2importPingServiceHandler,create_PingService_handlersclassPingService(PingServiceHandler):asyncdefPing(self,request:UnaryRequest[PingRequest],context:HandlerContext    )->UnaryResponse[PingResponse]:returnUnaryResponse(PingResponse(message=f"Pong:{request.message.message}")        )# Create the ASGI appapp=Starlette(middleware=[Middleware(ConnectMiddleware,create_PingService_handlers(PingService())        )    ])

4. Run your server

importasyncioimporthypercorn# Must be tsubakiky's fork!importhypercorn.asyncioif__name__=="__main__":config=hypercorn.Config()config.bind= ["localhost:8080"]asyncio.run(hypercorn.asyncio.serve(app,config))

5. Use the client

fromconnectrpc.clientimportUnaryRequestfromconnectrpc.connection_poolimportAsyncConnectionPoolfromping_pb2importPingRequestfromping_connect_pb2importPingServiceClientasyncdefmain():asyncwithAsyncConnectionPool()aspool:client=PingServiceClient(pool=pool,base_url="http://localhost:8080"        )request=UnaryRequest(PingRequest(message="Hello, Connect!"))response=awaitclient.Ping(request)print(f"Response:{response.message.message}")asyncio.run(main())

Streaming Support

# Server streamingasyncdefGetUpdates(self,request,context):# Get the single request messagemessage=awaitrequest.single()asyncdefstream_updates():foriinrange(10):yieldUpdateResponse(message=f"Update{i} for{message.name}")returnStreamResponse(stream_updates())# Client streamingasyncdefSendData(self,request,context):sentences=""asyncformessageinrequest.messages:sentences+=message.datareturnStreamResponse(SummaryResponse(content=sentences))# Bidirectional streaming (half-duplex)asyncdefChat(self,request,context):# First, consume all client messagescollected_messages= []asyncformessageinrequest.messages:collected_messages.append(message.text)# Then, generate responses based on collected messagesasyncdefecho_messages():fori,msginenumerate(collected_messages):yieldChatResponse(message=f"Echo{i+1}:{msg}")returnStreamResponse(echo_messages())

Streaming Limitations

Important

The current implementation of bidirectional streaming only supportshalf-duplex mode, where the server must fully consume the client's input stream before producing output.Full-duplex bidirectional streaming (where client and server can send messages simultaneously) is not yet supported but is planned for future releases.

Multi-Protocol Support

Examples

cd examples# Start the serverpython server.py# In another terminal, run the clientpython client.py --unary# Unary callpython client.py --server-streaming# Server streamingpython client.py --client-streaming# Client streaming

Development

Requirements

Setup

# Clone the repositorygit clone https://github.com/gaudiy/connect-python.gitcd connect-python# Install dependencies (using uv - recommended)uv sync# Run testspytest# Run conformance testscd conformance# Server conformance testsconnectconformance -vv --trace --conf ./server_config.yaml --mode server -- uv run python server_runner.py# Client conformance testsconnectconformance -vv --trace --conf ./client_config.yaml --mode client -- uv run python client_runner.py

Code Generation

Contributing

License