Skip to content

API Reference

connectrpc.client

ConnectClient

An asynchronous client for the Connect protocol.

Parameters:

Name Type Description Default
address str

The address of the server to connect to, including scheme.

 required
codec Codec | None

The Codec to use for requests. If unset, defaults to binary protobuf. For JSON encoding, use proto_json_codec.

 None
protocol ProtocolType

The ProtocolType to use for requests.

 CONNECT
accept_compression Iterable[Compression] | None

Compression algorithms to accept from the server. If unset, defaults to gzip. If set to empty, disables response compression.

 None
send_compression Compression | None

Compression algorithm to use for sending requests. If unset, defaults to gzip. If set to None, disables request compression.

 _gzip
timeout_ms int | None

The timeout for requests in milliseconds.

 None
read_max_bytes int | None

The maximum number of bytes to read from the response.

 None
interceptors Iterable[Interceptor]

A list of interceptors to apply to requests.

 ()
http_client Client | None

A pyqwest Client to use for requests.

 None

close async

Close the HTTP client. After closing, the client cannot be used to make requests.

ConnectClientSync

A synchronous client for the Connect protocol.

Parameters:

Name Type Description Default
address str

The address of the server to connect to, including scheme.

 required
codec Codec | None

The Codec to use for requests. If unset, defaults to binary protobuf. For JSON encoding, use proto_json_codec.

 None
protocol ProtocolType

The ProtocolType to use for requests.

 CONNECT
accept_compression Iterable[Compression] | None

Compression algorithms to accept from the server. If unset, defaults to gzip. If set to empty, disables response compression.

 None
send_compression Compression | None

Compression algorithm to use for sending requests. If unset, defaults to gzip. If set to None, disables request compression.

 _gzip
timeout_ms int | None

The timeout for requests in milliseconds.

 None
read_max_bytes int | None

The maximum number of bytes to read from the response.

 None
interceptors Iterable[InterceptorSync]

A list of interceptors to apply to requests.

 ()
http_client SyncClient | None

A pyqwest SyncClient to use for requests.

 None

close

Close the HTTP client. After closing, the client cannot be used to make requests.

ResponseMetadata

Response metadata separate from the message payload.

Commonly, RPC client invocations only need the message payload and do not need to directly read other data such as headers or trailers. In cases where they are needed, initialize this class in a context manager to access the response headers and trailers for the invocation made within the context.

Example 
with ResponseMetadata() as resp_data:
    resp = client.MakeHat(Size(inches=10))
    do_something_with_response_payload(resp)
    check_response_headers(resp_data.headers())
    check_response_trailers(resp_data.trailers())

headers

Returns the response headers.

trailers

Returns the response trailers.

connectrpc.server

ConnectASGIApplication

Bases: ABC, Generic[_SVC]

An ASGI application for the Connect protocol.

Parameters:

Name Type Description Default
service _SVC | AsyncGenerator[_SVC]

The service instance or async generator that yields the service during lifespan.

 required
endpoints Callable[[_SVC], Mapping[str, Endpoint]]

A callable that takes the service instance and returns a mapping of URL paths to endpoints. Typically provided directly by generated code from the Connect Python plugin.

 required
interceptors Iterable[Interceptor]

A sequence of interceptors to apply to the endpoints.

 ()
read_max_bytes int | None

Maximum size of request messages.

 None
compressions Iterable[Compression] | None

Supported compression algorithms. If unset, defaults to gzip. If set to empty, disables compression.

 None
codecs Iterable[Codec] | None

The codecs supported by the server. If unset, defaults to Protocol Buffers binary and JSON codecs.

 None

Endpoint dataclass

Bases: Generic[REQ, RES]

Represents an endpoint in a service.

Attributes:

Name Type Description
method MethodInfo[REQ, RES]

The method to map to the RPC function.

EndpointSync dataclass

Bases: Generic[REQ, RES]

Represents a sync endpoint in a service.

Attributes:

Name Type Description
method MethodInfo[REQ, RES]

The method to map to the RPC function.

ConnectWSGIApplication

Bases: ABC

A WSGI application for the Connect protocol.

Parameters:

Name Type Description Default
endpoints Mapping[str, EndpointSync]

A mapping of URL paths to endpoints. Typically provided directly by generated code from the Connect Python plugin.

 required
interceptors Iterable[InterceptorSync]

A sequence of interceptors to apply to the endpoints.

 ()
read_max_bytes int | None

Maximum size of request messages.

 None
compressions Iterable[Compression] | None

Supported compression algorithms. If unset, defaults to gzip. If set to empty, disables compression.

 None
codecs Iterable[Codec] | None

The codecs supported by the server. If unset, defaults to Protocol Buffers binary and JSON codecs.

 None

connectrpc.code

Code

Bases: Enum

Enumeration of Connect error codes.

CANCELED = 'canceled' class-attribute instance-attribute

RPC canceled, usually by the caller.

UNKNOWN = 'unknown' class-attribute instance-attribute

Catch-all for errors of unclear origin and errors without a more appropriate code.

INVALID_ARGUMENT = 'invalid_argument' class-attribute instance-attribute

Request is invalid, regardless of system state.

DEADLINE_EXCEEDED = 'deadline_exceeded' class-attribute instance-attribute

Deadline expired before RPC could complete or before the client received the response.

NOT_FOUND = 'not_found' class-attribute instance-attribute

User requested a resource (for example, a file or directory) that can't be found.

ALREADY_EXISTS = 'already_exists' class-attribute instance-attribute

Caller attempted to create a resource that already exists.

PERMISSION_DENIED = 'permission_denied' class-attribute instance-attribute

Caller isn't authorized to perform the operation.

RESOURCE_EXHAUSTED = 'resource_exhausted' class-attribute instance-attribute

Operation can't be completed because some resource is exhausted. Use unavailable if the server is temporarily overloaded and the caller should retry later.

FAILED_PRECONDITION = 'failed_precondition' class-attribute instance-attribute

Operation can't be completed because the system isn't in the required state.

ABORTED = 'aborted' class-attribute instance-attribute

The operation was aborted, often because of concurrency issues like a database transaction abort.

OUT_OF_RANGE = 'out_of_range' class-attribute instance-attribute

The operation was attempted past the valid range.

UNIMPLEMENTED = 'unimplemented' class-attribute instance-attribute

The operation isn't implemented, supported, or enabled.

INTERNAL = 'internal' class-attribute instance-attribute

An invariant expected by the underlying system has been broken. Reserved for serious errors.

UNAVAILABLE = 'unavailable' class-attribute instance-attribute

The service is currently unavailable, usually transiently. Clients should back off and retry idempotent operations.

DATA_LOSS = 'data_loss' class-attribute instance-attribute

Unrecoverable data loss or corruption.

UNAUTHENTICATED = 'unauthenticated' class-attribute instance-attribute

Caller doesn't have valid authentication credentials for the operation.

connectrpc.errors

ConnectError

Bases: Exception

An exception in a Connect RPC.

If a server raises a ConnectError, the same exception content will be raised on the client as well. Errors surfacing on the client side such as timeouts will also be raised as a ConnectError with an appropriate Code.

Parameters:

Name Type Description Default
code Code

The error code.

 required
message str

The error message.

 required
details Iterable[Message]

Additional details about the error.

 ()

connectrpc.method

IdempotencyLevel

Bases: Enum

The level of idempotency of an RPC method.

This value can affect RPC behaviors, such as determining whether it is safe to retry a request, or what kinds of request modalities are allowed for a given procedure.

UNKNOWN = enum.auto() class-attribute instance-attribute

The default idempotency level.

A method with this idempotency level may not be idempotent. This is appropriate for any kind of method.

NO_SIDE_EFFECTS = enum.auto() class-attribute instance-attribute

The idempotency level that specifies that a given call has no side-effects.

This is equivalent to RFC 9110 § 9.2.1 "safe" methods in terms of semantics. This procedure should not mutate any state. This idempotency level is appropriate for queries, or anything that would be suitable for an HTTP GET request. In addition, due to the lack of side-effects, such a procedure would be suitable to retry and expect that the results will not be altered by preceding attempts.

IDEMPOTENT = enum.auto() class-attribute instance-attribute

The idempotency level that specifies that a given call is "idempotent", such that multiple instances of the same request to this procedure would have the same side-effects as a single request.

This is equivalent to RFC 9110 § 9.2.2 "idempotent" methods. This level is a subset of the previous level. This idempotency level is appropriate for any procedure that is safe to retry multiple times and be guaranteed that the response and side-effects will not be altered as a result of multiple attempts, for example, entity deletion requests.

MethodInfo dataclass

Bases: Generic[REQ, RES]

Information about a RPC method within a service.

name instance-attribute

The name of the method within the service.

service_name instance-attribute

The fully qualified service name containing the method.

input instance-attribute

The input message type of the method.

output instance-attribute

The output message type of the method.

idempotency_level instance-attribute

The IdempotencyLevel of the method.

connectrpc.request

Headers

Bases: MutableMapping[str, str]

Container of HTTP headers.

This class behaves like a dictionary with case-insensitive keys and string values. It additionally can be used to store multiple values for the same key by using the add method, and retrieve a view including duplicates using allitems.

add

Add a header, appending to existing values without overwriting.

To overwrite an existing value, use self[key] = value instead.

clear

Clear all headers.

getall

Get all values for a header key, including duplicates.

allitems

Return an iterable view of all header items, including duplicates.

items

Return an iterable view of the headers, without duplicates.

keys

Return an iterable view of the header keys.

values

Return an iterable view of the header values, without duplicates.

RequestContext

Bases: Generic[REQ, RES]

Additional context for an RPC request message.

method

Returns information about the RPC method being invoked.

http_method

Returns the HTTP method for this request.

This is nearly always POST, but side-effect-free unary RPCs could be made via GET.

request_headers

Returns the request headers associated with the context.

response_headers

Returns the response headers that will be sent before the response.

response_trailers

Returns the response trailers that will be sent after the response.

timeout_ms

Returns the remaining time until the timeout in milliseconds, or None if no timeout is set.

server_address

Returns the server address for this request, if available, as a "address:port" string.

  • On the client, this is components from the URL configured when constructing the client.
  • On the server, this is determined from the Host header and scheme of the request.

client_address

Returns the client address for this request, if available, as a "address:port" string.

  • On the client, this is never populated.
  • On the server, this is the value provided by the server implementation, generally the IP address and ephemeral port of the client.

connectrpc.interceptor

Interceptor = UnaryInterceptor | ClientStreamInterceptor | ServerStreamInterceptor | BidiStreamInterceptor | MetadataInterceptor module-attribute

An interceptor to apply to an asynchronous RPC server or client.

InterceptorSync = UnaryInterceptorSync | ClientStreamInterceptorSync | ServerStreamInterceptorSync | BidiStreamInterceptorSync | MetadataInterceptorSync module-attribute

An interceptor to apply to a synchronous RPC server or client.

BidiStreamInterceptor

Bases: Protocol

An interceptor of an asynchronous bidirectional-streaming RPC method.

intercept_bidi_stream

Intercepts a bidirectional-streaming RPC.

Parameters:

Name Type Description Default
call_next Callable[[AsyncIterator[REQ], RequestContext], AsyncIterator[RES]]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request AsyncIterator[REQ]

The request message iterator.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
AsyncIterator[RES]

The response message iterator.

ClientStreamInterceptor

Bases: Protocol

An interceptor of an asynchronous client-streaming RPC method.

intercept_client_stream async

Intercepts a client-streaming RPC.

Parameters:

Name Type Description Default
call_next Callable[[AsyncIterator[REQ], RequestContext], Awaitable[RES]]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request AsyncIterator[REQ]

The request message iterator.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
RES

The response message.

MetadataInterceptor

Bases: Protocol[T]

An interceptor that can be applied to any type of method, only having access to metadata such as headers and trailers.

To access request and response bodies of a method, instead use an interceptor corresponding to the type of method such as UnaryInterceptor.

on_start async

Called when the RPC starts. The return value will be passed to on_end as-is. For example, if measuring RPC invocation time, on_start may return the current time. If a return value isn't needed or on_end won't be used, return None.

on_end async

Called when the RPC ends.

ServerStreamInterceptor

Bases: Protocol

An interceptor of an asynchronous server-streaming RPC method.

intercept_server_stream

Intercepts a server-streaming RPC.

Parameters:

Name Type Description Default
call_next Callable[[REQ, RequestContext], AsyncIterator[RES]]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request REQ

The request message.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
AsyncIterator[RES]

The response message iterator.

UnaryInterceptor

Bases: Protocol

An interceptor of an asynchronous unary RPC method.

intercept_unary async

Intercepts a unary RPC.

Parameters:

Name Type Description Default
call_next Callable[[REQ, RequestContext], Awaitable[RES]]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request REQ

The request message.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
RES

The response message.

BidiStreamInterceptorSync

Bases: Protocol

An interceptor of a synchronous bidirectional-streaming RPC method.

intercept_bidi_stream_sync

Intercepts a bidirectional-streaming RPC.

Parameters:

Name Type Description Default
call_next Callable[[Iterator[REQ], RequestContext], Iterator[RES]]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request Iterator[REQ]

The request message iterator.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
Iterator[RES]

The response message iterator.

ClientStreamInterceptorSync

Bases: Protocol

An interceptor of a synchronous client-streaming RPC method.

intercept_client_stream_sync

Intercepts a client-streaming RPC.

Parameters:

Name Type Description Default
call_next Callable[[Iterator[REQ], RequestContext], RES]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request Iterator[REQ]

The request message iterator.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
RES

The response message.

MetadataInterceptorSync

Bases: Protocol[T]

An interceptor that can be applied to any type of method, only having access to metadata such as headers and trailers.

To access request and response bodies of a method, instead use an interceptor corresponding to the type of method such as UnaryInterceptorSync.

on_start_sync

Called when the RPC starts. The return value will be passed to on_end_sync as-is. For example, if measuring RPC invocation time, on_start_sync may return the current time. If a return value isn't needed or on_end_sync won't be used, return None.

on_end_sync

Called when the RPC ends.

ServerStreamInterceptorSync

Bases: Protocol

An interceptor of a synchronous server-streaming RPC method.

intercept_server_stream_sync

Intercepts a server-streaming RPC.

Parameters:

Name Type Description Default
call_next Callable[[REQ, RequestContext], Iterator[RES]]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request REQ

The request message.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
Iterator[RES]

The response message iterator.

UnaryInterceptorSync

Bases: Protocol

An interceptor of a synchronous unary RPC method.

intercept_unary_sync

Intercepts a unary RPC.

Parameters:

Name Type Description Default
call_next Callable[[REQ, RequestContext], RES]

A callable to invoke to continue processing, either to another interceptor or the actual RPC. Generally will be called with the same request the interceptor received but the request can be replaced as needed. Can be skipped if returning a response from the interceptor directly.

 required
request REQ

The request message.

 required
ctx RequestContext

The request context.

 required

Returns:

Type Description
RES

The response message.

connectrpc.codec

Codec

Bases: Protocol[T_contra, U]

name

Returns the name of the codec.

This corresponds to the content-type used in requests.

encode

Marshals the given message.

decode

Unmarshals the given message.

proto_binary_codec

Returns the Protocol Buffers binary codec.

proto_json_codec

Returns the Protocol Buffers JSON codec.

connectrpc.protocol

ProtocolType

Bases: Enum

A protocol supported by Connect.

CONNECT = 1 class-attribute instance-attribute

The Connect protocol.

GRPC = 2 class-attribute instance-attribute

The gRPC protocol.

GRPC_WEB = 3 class-attribute instance-attribute

The gRPC-Web protocol.

connectrpc.compression

Compression

Bases: Protocol

Protocol for compression methods.

By default, gzip compression is used. Other compression methods can be used by specifying implementations of this protocol. We provide standard implementations for:

name

Returns the name of the compression method. This value is used in HTTP headers to indicate accepted and used compression.

compress

Compress the given data.

decompress

Decompress the given data.

connectrpc.compression.brotli

BrotliCompression

Bases: Compression

Compression implementation using Brotli.

Parameters:

Name Type Description Default
quality int

Compression quality to use.

 3

connectrpc.compression.gzip

GzipCompression

Bases: Compression

Compression implementation using GZip.

Parameters:

Name Type Description Default
level int

Compression level to use.

 6

connectrpc.compression.zstd

ZstdCompression

Bases: Compression

Compression implementation using Zstandard.

Parameters:

Name Type Description Default
level int

Compression level to use.

 3