API Reference

Protocol & Tuning

class grpclib_transports.TransportTuning(buffer_size: int, read_chunk_size: int, write_high_water: int, write_low_water: int, http2_stream_window_size: int, http2_connection_window_size: int, http2_max_frame_size: int, transfer_chunk_size: int)

Buffer, window, and chunk size knobs for transport performance.

All values are in bytes. Create a tuned instance with from_env() or read the pre-computed DEFAULT_TUNING.

Fields:

buffer_size: OS pipe buffer size used when bumping subprocess pipes. read_chunk_size: Size of each read() call in the pump loop. write_high_water: High-water mark for write buffer limits. write_low_water: Low-water mark for write buffer limits. http2_stream_window_size: Per-stream HTTP/2 flow-control window. http2_connection_window_size: Connection-level HTTP/2 flow-control window. http2_max_frame_size: Maximum HTTP/2 frame size sent to the peer. transfer_chunk_size: Default chunk size for file/data chunk iterators.

grpclib_transports.DEFAULT_TUNING = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144)

Buffer, window, and chunk size knobs for transport performance.

All values are in bytes. Create a tuned instance with from_env() or read the pre-computed DEFAULT_TUNING.

Fields:

buffer_size: OS pipe buffer size used when bumping subprocess pipes. read_chunk_size: Size of each read() call in the pump loop. write_high_water: High-water mark for write buffer limits. write_low_water: Low-water mark for write buffer limits. http2_stream_window_size: Per-stream HTTP/2 flow-control window. http2_connection_window_size: Connection-level HTTP/2 flow-control window. http2_max_frame_size: Maximum HTTP/2 frame size sent to the peer. transfer_chunk_size: Default chunk size for file/data chunk iterators.

class grpclib_transports.PeerIdentity(transport: str, username: str | None, uid: int | None = None, gid: int | None = None, pid: int | None = None, group_ids: tuple[int, ...] | None = None, group_names: tuple[str, ...] | None = None)

Identity information about the remote peer of a transport.

Fields:

transport: Transport type ("stdio", "ssh", "unix", "unknown"). username: OS username of the peer, if available. uid: Unix user ID of the peer. gid: Unix group ID of the peer. pid: Process ID of the peer. group_ids: Supplementary group IDs. group_names: Supplementary group names (resolved from group_ids).

grpclib_transports.local_process_identity(*, transport: str) → PeerIdentity

Build a PeerIdentity for the current process.

grpclib_transports.peer_identity_from_transport(transport: Any) → PeerIdentity

Extract PeerIdentity from an asyncio transport.

Checks for a stored peer_identity extra, an SSH username, or a Unix-domain socket with SO_PEERCRED.

grpclib_transports.peer_identity_from_stream(stream: Any) → PeerIdentity

Extract PeerIdentity from a gRPC stream's underlying transport.

grpclib_transports.make_h2_config(*, client_side: bool) → H2Configuration

Build an h2 configuration with strict validation off.

Disables inbound/outbound header validation and normalization so protobuf-based headers pass through unchanged.

grpclib_transports.make_config(tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144)) → Configuration

Build a grpclib Configuration with tuned window sizes.

grpclib_transports.make_server_protocol(mapping: dict[str, Handler], *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), status_details_codec: StatusDetailsCodecBase | None = None) → H2Protocol

Build a server-side H2 protocol with the given handler mapping.

status_details_codec is what lets a handler's GRPCError.details reach the client: grpclib encodes it into the grpc-status-details-bin trailer only when a codec is configured, and drops it silently otherwise. The client's channel must be given the same codec to decode it.

grpclib_transports.init_h2_transport(protocol: H2Protocol, transport: Any, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144)) → None

Wire an H2 protocol to a transport and advertise a tuned max frame size.

grpclib_transports.build_mapping(handlers: Sequence[IServable]) → dict[str, Handler]

Merge __mapping__() from a sequence of servable handlers into one dict.

async grpclib_transports.pump(protocol: H2Protocol, reader: Any, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144)) → None

Read from a byte stream and feed data into an H2 protocol.

Blocks in a loop calling reader.read(). On EOF or error, calls protocol.connection_lost().

async grpclib_transports.serve_h2(handlers: Sequence[IServable], reader: Any, transport: Any, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), max_concurrency: int | None = None, status_details_codec: StatusDetailsCodecBase | None = None) → None

Build a server protocol, wire it to a transport, and pump frames.

grpclib_transports.pause_h2_protocol(protocol: BaseProtocol | None) → None

Pause writing on an H2 protocol, if set.

grpclib_transports.resume_h2_protocol(protocol: BaseProtocol | None) → None

Resume writing on an H2 protocol, if set.

grpclib_transports.signal_stop(stop: Future[None]) → None

Signal a stop future, guarding against duplicate completion.

grpclib_transports.install_h2_fast_receive_patch() → None

Patch h2 to skip expensive trace-logging frame reprs.

Called automatically at import time. Idempotent — subsequent calls are no-ops. Raises RuntimeError if the h2 internals have changed in a way the patch cannot handle.

Transports

class grpclib_transports.BaseCustomTransport

Bases: Transport

Base class for custom asyncio transports that wrap a reader/writer pair.

Concrete transports (StdioTransport, SshTransport) override: - write() — forward data to the underlying writer - get_extra_info() — delegate to the appropriate underlying object - get_write_buffer_size() — introspect the write buffer (for flow control) - abort() — hard reset (transport-specific) - can_write_eof() / write_eof() — EOF support (transport-specific)

Flow-control bridging (pause_writing/resume_writing forwarding to the H2Protocol) is handled by each concrete transport's own mechanism.

get_protocol() → BaseProtocol

Return the current protocol.

is_closing() → bool

Return True if the transport is closing or closed.

pause_reading() → None

Pause the receiving end.

No data will be passed to the protocol's data_received() method until resume_reading() is called.

resume_reading() → None

Resume the receiving end.

Data received will once again be passed to the protocol's data_received() method.

set_protocol(protocol: BaseProtocol) → None

Set a new protocol.

class grpclib_transports.StdioTransport(reader: StreamReader, writer: StreamWriter, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))

Bases: BaseCustomTransport

An asyncio transport that wraps a stdio subprocess pipe pair.

abort() → None

Close the transport immediately.

Buffered data will be lost. No more data will be received. The protocol's connection_lost() method will (eventually) be called with None as its argument.

can_write_eof() → bool

Return True if this transport supports write_eof(), False if not.

close() → None

Close the transport.

Buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's connection_lost() method will (eventually) be called with None as its argument.

get_extra_info(name: str, default: Any = None) → Any

Get optional transport information.

get_write_buffer_size() → int

Return the current size of the write buffer.

write(data: bytes | bytearray | memoryview) → None

Write some data bytes to the transport.

This does not block; it buffers the data and arranges for it to be sent out asynchronously.

write_eof() → None

Close the write end after flushing buffered data.

(This is like typing ^D into a UNIX program reading from stdin.)

Data may still be received.

class grpclib_transports.SshTransport(reader: Any, writer: Any, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))

Bases: BaseCustomTransport

An asyncio transport that wraps an asyncssh channel.

Forwards asyncssh session pause_writing/resume_writing callbacks to the H2 protocol for end-to-end backpressure. Restores the original session callbacks on close or abort.

abort() → None

Close the transport immediately.

Buffered data will be lost. No more data will be received. The protocol's connection_lost() method will (eventually) be called with None as its argument.

can_write_eof() → bool

Return True if this transport supports write_eof(), False if not.

close() → None

Close the transport.

Buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's connection_lost() method will (eventually) be called with None as its argument.

get_extra_info(name: str, default: Any = None) → Any

Get optional transport information.

get_write_buffer_size() → int

Return the current size of the write buffer.

set_write_buffer_limits(high: int | None = None, low: int | None = None) → None

Set the high- and low-water limits for write flow control.

These two values control when to call the protocol's pause_writing() and resume_writing() methods. If specified, the low-water limit must be less than or equal to the high-water limit. Neither value can be negative.

The defaults are implementation-specific. If only the high-water limit is given, the low-water limit defaults to an implementation-specific value less than or equal to the high-water limit. Setting high to zero forces low to zero as well, and causes pause_writing() to be called whenever the buffer becomes non-empty. Setting low to zero causes resume_writing() to be called only once the buffer is empty. Use of zero for either limit is generally sub-optimal as it reduces opportunities for doing I/O and computation concurrently.

write(data: bytes | bytearray | memoryview) → None

Write some data bytes to the transport.

This does not block; it buffers the data and arranges for it to be sent out asynchronously.

write_eof() → None

Close the write end after flushing buffered data.

(This is like typing ^D into a UNIX program reading from stdin.)

Data may still be received.

class grpclib_transports.PipeTransport(reader: StreamReader, writer: StreamWriter, *, transport_name: str = 'pipe', tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))

Bases: BaseCustomTransport

An asyncio transport that wraps a raw OS pipe pair.

Differs from StdioTransport in that it accepts arbitrary binary file objects rather than being hardwired to sys.stdin/sys.stdout.

abort() → None

Close the transport immediately.

Buffered data will be lost. No more data will be received. The protocol's connection_lost() method will (eventually) be called with None as its argument.

can_write_eof() → bool

Return True if this transport supports write_eof(), False if not.

close() → None

Close the transport.

Buffered data will be flushed asynchronously. No more data will be received. After all buffered data is flushed, the protocol's connection_lost() method will (eventually) be called with None as its argument.

get_extra_info(name: str, default: Any = None) → Any

Get optional transport information.

get_write_buffer_size() → int

Return the current size of the write buffer.

write(data: bytes | bytearray | memoryview) → None

Write some data bytes to the transport.

This does not block; it buffers the data and arranges for it to be sent out asynchronously.

write_eof() → None

Close the write end after flushing buffered data.

(This is like typing ^D into a UNIX program reading from stdin.)

Data may still be received.

Channels

class grpclib_transports.StdioChannel(reader: Any, writer: Any, *, transport: StdioTransport | None = None, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs: Any)

Bases: Channel

A gRPC channel that speaks H2 over a subprocess stdio pipe pair.

close() → None

Closes connection to the server.

class grpclib_transports.SshChannel(reader: Any, writer: Any, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs: Any)

Bases: Channel

A gRPC channel that speaks H2 over an asyncssh session.

close() → None

Closes connection to the server.

class grpclib_transports.PipeChannel(reader: Any, writer: Any, *, transport: PipeTransport | None = None, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs: Any)

Bases: Channel

A gRPC channel that speaks H2 over a raw OS pipe pair.

close() → None

Closes connection to the server.

Server

class grpclib_transports.Server(*, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144))

Bases: object

Container for multiple service endpoints and worker managers.

async grpclib_transports.serve_stdio(handlers: list[IServable], *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), max_concurrency: int | None = None, status_details_codec: StatusDetailsCodecBase | None = None) → None

Serve gRPC over the current process's stdin/stdout.

Redirects stdout to stderr before starting so that only H2 frames go over the pipe.

async grpclib_transports.serve_ssh(handlers: list[IServable], host: str = '127.0.0.1', port: int = 8022, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), max_concurrency: int | None = None, status_details_codec: StatusDetailsCodecBase | None = None) → None

Start an asyncssh server that speaks H2 on each session.

Generates an ephemeral Ed25519 key and accepts connections indefinitely. Shuts down gracefully on SIGINT or SIGTERM.

Client

grpclib_transports.connect_ssh(host: str, port: int = 22, *, username: str | None = None, password: str | None = None, known_hosts: Any = None, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), status_details_codec: StatusDetailsCodecBase | None = None, **kwargs: Any) → AsyncGenerator[SshChannel]

Connect to an SSH server and yield an SshChannel.

Use as an async context manager. The SSH session and channel are closed on exit.

grpclib_transports.connect_tcp(host: str, port: int, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), ssl: SSLContext | bool | None = None, **kwargs: Any) → Channel

Create a grpclib.client.Channel to host:port over TCP.

The channel is configured with tuned HTTP/2 window sizes from tuning. Pass ssl to enable TLS.

grpclib_transports.connect_unix(path: str | Path, *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), **kwargs: Any) → Channel

Create a grpclib.client.Channel to a Unix-domain socket at path.

The channel is configured with tuned HTTP/2 window sizes from tuning.

grpclib_transports.stdio_worker(argv: Sequence[str | Path], *, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), cwd: str | Path | None = None, env: Mapping[str, str] | None = None, stderr: Any = None, status_details_codec: StatusDetailsCodecBase | None = None) → AsyncGenerator[StdioChannel]

Spawn a subprocess and yield a StdioChannel connected to its stdin/stdout.

Use as an async context manager. The subprocess is terminated on exit.

Bidirectional RPC

class grpclib_transports.LogicalRpcPeer(*, send_frame: Callable[[LogicalFrame], Awaitable[None]], receive_frame: Callable[[], Awaitable[LogicalFrame | None]], handler: Callable[[str, Any], Awaitable[Any]] | None = None)

Bases: object

Bidirectional RPC peer over a logical frame transport.

Supports request/response (call()), one-way events (event()), and cancellation. Spawns a background reader task via start(). Close with aclose().

Parameters:

• send_frame -- Callable that sends a LogicalFrame.

• receive_frame -- Callable that returns the next LogicalFrame or None.

• handler -- Optional request/event handler (method, payload) -> result.

class grpclib_transports.LogicalFrame(id: int, kind: Literal['request', 'response', 'event', 'cancel'], method: str | None = None, payload: Any = None, error: str | None = None)

A logical RPC frame exchanged between peers.

Fields:

id: Monotonic request identifier (0 for events). kind: Frame kind: "request", "response", "event", or "cancel". method: gRPC-style method name for requests/events. payload: Arbitrary data carried in the frame. error: Error message carried in a response frame.

exception grpclib_transports.RemoteCallError

Raised when a remote peer responds with an error.

exception grpclib_transports.PeerClosedError

Raised when an operation is attempted on a closed peer.

Workers

class grpclib_transports.StdioPeerPool(argv: Sequence[str | Path], *, peer_factory: PeerFactory[PeerT], size: int = 1, tuning: TransportTuning = TransportTuning(buffer_size=8388608, read_chunk_size=8388608, write_high_water=8388608, write_low_water=4194304, http2_stream_window_size=16777216, http2_connection_window_size=67108864, http2_max_frame_size=1048576, transfer_chunk_size=262144), cwd: str | Path | None = None, env: Mapping[str, str] | None = None, stderr: Any = None)

Bases: Generic

A pool of size subprocess workers, each bridged by a LogicalRpcPeer.

Use as an async context manager. On enter, spawns size child processes via stdio_worker(), creates peers with peer_factory, and registers them in registry. On exit, closes all peers and terminates all subprocesses.

class grpclib_transports.PeerRegistry

Bases: Generic

A thread-unsafe registry of RegisteredPeer instances.

Supports len(), iteration, and snapshot via snapshot(). Broadcast calls to all registered peers with call_all().

class grpclib_transports.RegisteredPeer(id: str, peer: PeerT, metadata: Mapping[str, ~typing.Any]=<factory>)

Bases: Generic

A LogicalRpcPeer registered with an ID and optional metadata.

Delegates call() and event() to the wrapped peer.

Transfer

grpclib_transports.iter_chunks(data: bytes | bytearray | memoryview, chunk_size: int) → Iterator[bytes]

Yield chunk_size-byte slices of data.

grpclib_transports.iter_file_chunks(path: str | Path, *, chunk_size: int = 262144) → Iterator[bytes]

Yield chunk_size-byte chunks from the file at path.

Multiprocessing

class grpclib_transports.MultiprocessingPipePair(parent: MultiprocessingPipeEndpoint, child: MultiprocessingPipeEndpoint, context: Any)

Bases: object

A pair of MultiprocessingPipeEndpoint — one for parent, one for child.

class grpclib_transports.MultiprocessingPipeEndpoint(read_connection: Any, write_connection: Any, transport_name: str = 'multiprocessing')

Bases: object

One end of a multiprocessing pipe pair.

Call open_channel() to create a PipeChannel backed by the pipe file descriptors.

grpclib_transports.multiprocessing_pipe_pair(*, context: Any | None = None, preload: Sequence[str] = ()) → MultiprocessingPipePair

Create a MultiprocessingPipePair for parent-child communication.

If context is not given, calls get_forkserver_context() with preload.

grpclib_transports.get_forkserver_context(*, preload: Sequence[str] = ()) → Any

Return a multiprocessing forkserver context, optionally preloading modules.