connectrpc / connect-python

connect-python A Python implementation of Connect: Protobuf RPC that works. This repo provides a Python implementation of Connect, including both client and server support. It includes a protoc plugin that generates typed client stubs and server interfaces from your files, along with runtime libraries for both synchronous and asynchronous code. Features • **Clients**: Both synchronous and asynchronous clients backed by pyqwest • **Servers**: WSGI and ASGI server implementations for use with any Python app server • **Type Safety**: Fully type-annotated, including the generated code • **Compression**: Built-in support for gzip, brotli, and zstd compression • **Interceptors**: Server-side and client-side interceptors for cross-cutting concerns • **Streaming**: Full support for server, client, and bidirectional streaming • **Standards Compliant**: Verified implementation using the official Connect conformance test suite Installation Install the runtime library Or with your preferred package manager: Install the code generator With a protobuf definition in hand, you can generate stub code. This is easiest using buf, but you can also use protoc if you're feeling masochistic. A reasonable : Or, you can install the compiler (e.g. ), and it can be referenced as . Then, you can use as a local plugin: Alternatively, download a precompiled binary from the releases. is only needed for code generation. Your actual application should include as a dependency for the runtime component. Basic Client Usage Basic Server Usage Basic Client Usage (Synchronous) Check out the docs for more detailed usage including streaming, interceptors, and other advanced features. Streaming Support connect-python supports all RPC streaming types: • **Unary**: Single request, single response • **Server Streaming**: Single request, multiple responses • **Client Streaming**: Multiple requests, single response • **Bidirectional Streaming**: Multiple requests, multiple responses Server Streaming Single request, multiple responses: Client Streaming Multiple requests, single response: Bidirectional Streaming Multiple requests and responses: Streaming Notes • **HTTP/2 ASGI servers** (Hypercorn, Daphne): Support all streaming types including full-duplex bidirectional • **HTTP/1.1 servers**: Support half-duplex bidirectional streaming only • **WSGI servers**: Support streaming but not full-duplex bidirectional due to protocol limitations • **Clients**: Support half-duplex bidirectional streaming only Examples The directory contains complete working examples demonstrating all features: • **Eliza Chatbot**: A Connect implementation of the classic ELIZA psychotherapist chatbot • - Async ASGI server implementation • - Synchronous WSGI server implementation • - Async client example • - Synchronous client example • **All streaming patterns**: Unary, server streaming, client streaming, and bidirectional • **Integration examples**: Starlette, Flask, and other frameworks Run the Eliza example: Supported Protocols • ✅ Connect Protocol over HTTP/1.1 and HTTP/2 • ✅ gRPC Protocol support • 🚧 gRPC-Web Protocol support is not available Server Runtime Options For ASGI servers: • Uvicorn - Lightning-fast ASGI server • Daphne - Django Channels' ASGI server with HTTP/2 support • Hypercorn - ASGI server with HTTP/2 and HTTP/3 support For WSGI servers: • Gunicorn - Python WSGI HTTP Server • uWSGI - Full-featured application server • Any WSGI-compliant server For testing, you'll need the buf CLI for running conformance tests. WSGI Support connect-python provides full WSGI support via for synchronous Python applications. This enables integration with traditional WSGI servers like Gunicorn and uWSGI. Compression Support connect-python supports multiple compression algorithms: • **gzip**: Built-in support, always available • **brotli**: Available when package is installed • **zstd**: Available when package is installed Compression is automatically negotiated between client and server based on the and headers. Interceptors Server-Side Interceptors Interceptors allow you to add cross-cutting concerns like authentication, logging, and metrics: Client-Side Interceptors Clients also support interceptors for request/response processing: Advanced Features Connect GET Support connect-python automatically enables GET request support for methods marked with in your proto files: Clients can use GET requests automatically: CORS Support connect-python works with any ASGI CORS middleware. For example, using Starlette: Message Size Limits Protect against resource exhaustion by limiting message sizes: When exceeded, returns error. Proto Editions Support supports up to Protobuf Editions 2024: Development We use for linting and formatting, and for type checking. We rely on the conformance test suit (in ./conformance) to verify behavior. Set up a virtual env: Then, use to do development checks, or check out for other targets. is run via as a development dependency, but you can also install it globally and omit the from the commands. Status This project is in beta and is being actively developed. 1.0 will include a new Protobuf implementation built from scratch by Buf, which may introduce breaking changes. Join us on [Slack][] if you have questions or feedback. Legal Offered under the Apache 2 license. [slack]: https://buf.build/links/slack