v0.11.0

[anuraaga]

This is a large release - in fact it is so large we have renamed the repo to connect-py! There are major breaking changes so read these notes in detail. Sorry for the churn, but we hope for this to be the last big bump on the road to a stable release.

This release targets the long-awaited protobuf-py, a new Protocol Buffers runtime built from scratch to provide a complete, idiomatic, and performant experience for Python. protobuf-py is now the default, but google.protobuf is also completely supported via a compatibility layer - read through the Breaking Changes section for how to enable it.

☢️ Breaking changes

Enabling the google.protobuf compatibility shim (Existing users read this!)

Starting with this release, protoc-gen-connectrpc will default to generating stubs that target protobuf-py messages. Existing users should add the protobuf=google option to their plugin settings to instead generate stubs that target existing google.protobuf messages. There are some significant changes to the usage of messages with protobuf-py to match Python semantics better, so we recommend existing users to first enable the shim while updating connectrpc and later consider migrating to protobuf-py independently.

Before:

version: v2
plugins:
  - remote: buf.build/protocolbuffers/python
    out: src
  - remote: buf.build/protocolbuffers/pyi
    out: src
  - remote: buf.build/connectrpc/python
    out: src

After:

version: v2
plugins:
  - remote: buf.build/protocolbuffers/python
    out: src
  - remote: buf.build/protocolbuffers/pyi
    out: src
  - remote: buf.build/connectrpc/python
    out: src
    opt: protobuf=google

The shim is simply an implementation of Connect's Codec, which is provided by default by generated code when enabling that option. If you set a different codec in your code, for example to use JSON, you will need to update to the new compat codec google_protobuf_json_codec.

Before:

from connectrpc.codec import proto_json_codec
client = ElizaServiceClient("http://localhost:8081", codec=proto_json_codec())

After:

from connectrpc.compat import google_protobuf_json_codec
client = ElizaServiceClient("http://localhost:8081", codec=google_protobuf_json_codec())

ErrorDetails exposed as class instead of Any

Previously ConnectError exposed details with the google.protobuf type Any directly. We have replaced this with a dedicated ErrorDetail class that provides the same type_name and message_bytes data for manual unpacking, but also has a convenience value method to convert into a protobuf-py message.

To convert into a google.protobuf message, copy the contents to its Any before unpacking.

Before:

try:
    resp = client.say(SayMessage(sentence="Hello!"))
except ConnectError as e:
    detail = Struct()
    e.details[0].Unpack(detail)
    print(detail)

After:

from google.protobuf.any_pb2 import Any
try:
    resp = client.say(SayMessage(sentence="Hello!"))
except ConnectError as e:
    detail_any = Any(
        type_url=f"type.googleapis.com/{e.details[0].type_name}", 
        value=e.details[0].message_bytes)
    detail = Struct()
    detail_any.Unpack(detail)
    print(detail)

RequestContext and ResponseMetadata expose properties instead of getters

This will effect many interceptor implementations. If you've written them, you've probably found them to simple accessors as getter methods, which especially looks poor for accessing headers. This has been a long-time mistake in the API and we are using this large release to fix it with this significant breaking change. Attributes are now all properties instead of getter methods.

Before:

authorization = ctx.headers()["authorization"]

with ResponseMetadata() as meta:
    resp = client.say(SayMessage(sentence="Hello!"))
    print(meta.headers()["x-generated-entity"]

After:

authorization = ctx.headers["authorization"]

with ResponseMetadata() as meta:
    resp = client.say(SayMessage(sentence="Hello!"))
    print(meta.headers["x-generated-entity"]

protoc-gen-connectrpc is now written in Python

protoc-gen-connectrpc has been rewritten in Python using protobuf-py's plugin framework. This improves the output of the generated code substantially, but also means we cannot provide prebuilt binaries or a go run mechanism anymore. If needing them, consider wasilibs which runs the same plugin code via WASM.

📈 Enhancements

• Generator: emit RequestContext[Input, Output] for service handlers by @smparkes in Generator: emit RequestContext[Input, Output] for service handlers #264

New Contributors

• @smparkes made their first contribution in Generator: emit RequestContext[Input, Output] for service handlers #264

Full Changelog: v0.10.1...v0.11.0

---

This discussion was created from the release v0.11.0.