Python client#
pw_rpc2: Next gen, zero-copy async RPC with end-to-end backpressure
The pw_rpc2 Python package (//pw_rpc2/py:pw_rpc2) provides a host client
for pw_rpc2 servers:
Synchronous and asyncio APIs:
pw_rpc2.Clientprovides thread-safe blocking calls;pw_rpc2.aio.Clientprovides nativeasynciocoroutines over the same connection engine.Runtime service generation: Service and method clients are built at runtime from compiled
_pb2modules or protobuf descriptors—no RPC code generation step is required.Unary and streaming RPCs: Supports unary, server streaming, client streaming, and bidirectional streaming calls, with dedicated handle types for each.
For class and function signatures, see the Python API reference.
Quickstart#
Pass compiled _pb2 modules when connecting to a server, then call methods
under client.rpcs by walking the protobuf package hierarchy. The examples
below call the Echo service from the
C++ Echo example (server_coro listens on
port 8000 by default):
import pw_rpc2
from pw_transport import framed_tcp
from echo_pb import echo_pb2
with pw_rpc2.Client(
framed_tcp.connect('localhost', 8000), [echo_pb2]
) as client:
reply = client.rpcs.examples.Echo.Echo(msg='hello')
print(reply.msg)
import asyncio
from pw_rpc2 import aio
from pw_transport import framed_tcp
from echo_pb import echo_pb2
async def main() -> None:
async with await aio.Client.connect(
lambda: framed_tcp.connect('localhost', 8000), [echo_pb2]
) as client:
reply = await client.rpcs.examples.Echo.Echo(msg='hello')
print(reply.msg)
asyncio.run(main())
Connecting to a server#
Each client owns a private pw_transport.ReliableSocket connection to
a single server (see pw_transport):
pw_rpc2.Clienttakes an openReliableSocket.pw_rpc2.aio.Client.connect()takes either an openReliableSocketor a zero-argument callable returning one. A callable runs on a worker thread so opening the socket does not block the event loop. (pw_rpc2.aio.Clienthas no public constructor because connecting awaits the opening handshake.)
Handshake and lifecycle#
Before returning, the client performs the pw_rpc2
three-way handshake
(SYN → SYN_ACK → ACK). If the server sends an invalid reply, selects
an unsupported protocol version, disconnects, or does not finish within
handshake_timeout (default DEFAULT_HANDSHAKE_TIMEOUT,
5.0 seconds), the client closes the socket and raises
pw_rpc2.HandshakeError.
Closing the client—with client.close(), await client.close(), or a
with / async with block—closes the socket, joins background worker
threads, and ends any active calls locally with
pw_rpc2.RpcStatus.CLOSED without sending packets to the server.
client.closed reports whether the connection has closed.
The client’s background threads are daemon threads, so a client that is never closed does not keep the Python interpreter from exiting.
Built-in sockets#
pw_rpc2 accepts any pw_transport.ReliableSocket, including:
pw_transport.framed_tcp.connect()(//pw_transport/py:framed_tcp) for host tools and tests over TCP. It frames datagrams with a 4-byte little-endian length prefix matching C++’spw::transport::FramedTcpListenerandpw::transport::FramedTcpConnector.pw_transport.forwarding_socket.socket_pair()(//pw_transport/py:forwarding_socket) for in-process testing.Custom ReliableSocket subclasses over serial, USB, BLE, or other framed links.
client = pw_rpc2.Client(
framed_tcp.connect('127.0.0.1', 8000, timeout=5.0),
protos=[echo_pb2],
default_timeout=10.0,
handshake_timeout=5.0,
)
client = await aio.Client.connect(
lambda: framed_tcp.connect('127.0.0.1', 8000, timeout=5.0),
protos=[echo_pb2],
default_timeout=10.0,
handshake_timeout=5.0,
)
Services, descriptors, and requests#
Loading service descriptors#
The protos argument on pw_rpc2.Client,
pw_rpc2.aio.Client.connect(), and client.add_services() accepts any
iterable of pw_rpc2.ProtoSource items:
Generated
*_pb2modulesgoogle.protobuf.descriptor.FileDescriptorobjectsgoogle.protobuf.descriptor.ServiceDescriptorobjects
To load schemas built dynamically in a DescriptorPool, look up their
FileDescriptor or ServiceDescriptor objects (for example, with
pool.FindFileByName(...)) and pass them in protos. Calling
client.add_services(protos) registers more services on an open client; a
service with the same full name as an existing one replaces it without
disturbing other service clients.
Passing requests#
Method clients and streaming call.write() accept a request in either of two
forms (never mixed in the same call):
Keyword arguments for the request’s fields:
reply = client.rpcs.examples.Echo.Echo(msg='hello')
A protobuf message as a single positional argument (including a message class from another
DescriptorPoolwith the sameDESCRIPTOR.full_name):reply = client.rpcs.examples.Echo.Echo(echo_pb2.EchoMessage(msg='hello'))
Method clients and call.write() synthesize Python signatures and docstrings
from the protobuf schema, so help() and IDE tab completion display request
fields, types, and default values.
Making RPC calls#
Each RPC cardinality has a dedicated call class exposing only the operations valid for that mode:
RPC type |
Calling |
Call handle class |
|---|---|---|
Unary |
Response message ( |
|
Server streaming |
Call handle immediately |
|
Client streaming |
Call handle immediately |
|
Bidirectional streaming |
Call handle immediately |
Note
In pw_rpc2.aio, calling a unary method returns a coroutine that you
await. Calling a streaming method (or method.invoke()) never
blocks the event loop—it queues the opening packet on a sender thread and
returns the call handle directly without await.
Every call handle provides call.completed (bool), call.status
(RpcStatus, or None while active or after a local
transport/decode error), and call.cancel(). Using a call handle as a context
manager (with call: or async with call:) cancels the RPC on exit if it
is still active.
Unary RPCs#
Calling a unary method sends the request and waits for the single response. If
the wait is interrupted—by pw_rpc2.RpcTimeout,
KeyboardInterrupt, or cancelling an awaiting asyncio.Task—the client
cancels the RPC on the server before propagating the exception.
To start a unary RPC without waiting immediately, call method.invoke(...) to
get a pw_rpc2.UnaryCall (or pw_rpc2.aio.UnaryCall), then
call call.response() (or await call.response()):
echo = client.rpcs.examples.Echo
# Blocking unary call:
reply = echo.Echo(msg='hello', rpc2_timeout=2.0)
# Concurrent unary calls with .invoke():
with (
echo.Echo.invoke(msg='first') as call1,
echo.Echo.invoke(msg='second') as call2,
):
reply1 = call1.response(timeout=2.0)
reply2 = call2.response(timeout=2.0)
echo = client.rpcs.examples.Echo
# Coroutine unary call:
reply = await echo.Echo(msg='hello', rpc2_timeout=2.0)
# Concurrent unary calls with asyncio.gather:
reply1, reply2 = await asyncio.gather(
echo.Echo(msg='first'),
echo.Echo(msg='second'),
)
# Or non-blocking start with .invoke():
async with echo.Echo.invoke(msg='hello') as call:
reply = await call.response(timeout=2.0)
Server streaming RPCs#
Calling a server streaming method starts the RPC and returns a
pw_rpc2.ServerStreamingCall (or
pw_rpc2.aio.ServerStreamingCall). Iterate over the call to consume
responses until the server ends the stream, or fetch one message at a time with
call.read(timeout=...), which returns None at end-of-stream. Wrap the
call in with / async with so breaking out of the loop early cancels the
stream on the server:
with client.rpcs.examples.Echo.Repeat(msg='hi', count=3) as call:
for response in call:
print(response.msg)
async with client.rpcs.examples.Echo.Repeat(msg='hi', count=3) as call:
async for response in call:
print(response.msg)
Unlike the C++ client—which holds at most one unread message per call so slow readers apply transport backpressure—the Python client buffers incoming stream messages in memory without a fixed limit so its receiver thread keeps draining the socket. Cancel streams you no longer need so the server stops sending.
Client streaming RPCs#
Calling a client streaming method opens the stream with no initial request and
returns a pw_rpc2.ClientStreamingCall (or
pw_rpc2.aio.ClientStreamingCall). Send requests with
call.write(...), then call call.finish(timeout=...) to close the
request stream and wait for the server’s response (if the server responded
early, finish() returns that response directly):
with client.rpcs.examples.Echo.Collect() as call:
call.write(msg='one')
call.write(msg='two')
reply = call.finish(timeout=5.0)
async with client.rpcs.examples.Echo.Collect() as call:
await call.write(msg='one')
await call.write(msg='two')
reply = await call.finish(timeout=5.0)
Bidirectional streaming RPCs#
Calling a bidirectional streaming method opens the stream and returns a
pw_rpc2.BidirectionalStreamingCall (or
pw_rpc2.aio.BidirectionalStreamingCall), combining write(),
read() / iteration, and finish().
Unlike ClientStreamingCall.finish(),
BidirectionalStreamingCall.finish() takes no timeout and only half-closes
the client’s request stream; the client can keep reading server responses until
the server finishes the call.
Both streaming reader types inherit from pw_rpc2.Reader
(pw_rpc2.aio.Reader), and both streaming writer types inherit from
pw_rpc2.Writer (pw_rpc2.aio.Writer), so helper functions
that split sending and receiving across threads or tasks can annotate only the
half they use:
with client.rpcs.examples.Echo.EchoStream() as call:
call.write(msg='ping')
reply = call.read(timeout=2.0)
call.finish()
for trailing in call:
print(trailing.msg)
async with client.rpcs.examples.Echo.EchoStream() as call:
await call.write(msg='ping')
reply = await call.read(timeout=2.0)
await call.finish()
async for trailing in call:
print(trailing.msg)
Timeouts and cancellation#
Timeouts#
Timeouts are given in seconds and resolve from most specific to least specific:
Per-operation:
call.response(timeout=...),call.read(timeout=...), orClientStreamingCall.finish(timeout=...).Per-call:
method(..., rpc2_timeout=...)ormethod.invoke(..., rpc2_timeout=...). When iterating over a stream, the call’s timeout applies to each message wait individually.Client default:
client.default_timeout(set at construction or updated on the property;Nonewaits indefinitely).
Pass math.inf as rpc2_timeout or timeout to wait indefinitely when a
broader default timeout is set.
The per-call keyword is named rpc2_timeout so it does not collide with a
request field named timeout. A request field literally named
rpc2_timeout must be set via a request message when calling a method client
(call.write() takes no timeout, so all field names work as keywords there).
Timeouts apply only to waiting for server responses. Outbound writes block only
on transport backpressure (and in pw_rpc2.aio, run on a dedicated sender
thread so backpressure never stalls the event loop).
Expiring a wait raises pw_rpc2.RpcTimeout (a TimeoutError
subclass). Timing out a direct unary call method(...) cancels the RPC;
timing out call.response(), call.read(), or call.finish() leaves the
call open so you can wait again, unless the exception exits a with /
async with block.
Cancelling calls#
call.cancel() is synchronous in both pw_rpc2 and pw_rpc2.aio. It
marks the call completed with pw_rpc2.RpcStatus.CANCELLED, wakes
local waiters immediately, and queues a CANCELLED packet for the server
without blocking on transport backpressure or an in-progress write() (if a
write is in flight, the CANCELLED packet is sent immediately after it). It
returns True if the call was active, or False if it had already ended.
After cancel(), operations that were waiting on the call, and later calls to
response(), read(), write(), and ClientStreamingCall.finish(),
raise pw_rpc2.RpcError with status == RpcStatus.CANCELLED.
read() and iteration first return any responses that arrived before the
cancellation.
Starting a call in pw_rpc2.aio queues its opening packet on the sender
thread. If the call ends before that packet is sent—for example, a unary call
that times out or is cancelled while an earlier write is blocked on transport
backpressure—the client sends neither the opening packet nor a CANCELLED
packet, so the server never sees the call.
In pw_rpc2.aio, cancelling an asyncio.Task cancels the RPC only if the
task is awaiting a direct unary call (await method(...)). Cancelling a task
that is awaiting call.response(), call.read(), call.write(), or
call.finish() only stops the wait; the call stays open unless the
asyncio.CancelledError exits an async with block. A cancelled
write() or finish() may still be sent, because a packet that the sender
thread is already sending cannot be recalled, so asyncio.CancelledError does
not mean that the server did not receive the request.
Error handling#
pw_rpc2 raises distinct exceptions for RPC statuses, timeouts, and transport
or encoding failures:
pw_rpc2.RpcError: The RPC ended with a non-OKpw_rpc2.RpcStatus. Provideserr.method(method metadata:name,full_name,type,descriptor),err.status(RpcStatus), anderr.detail(str, which may be empty;str(err)formats the method, status, wire error, and detail).pw_rpc2.RpcTimeout:TimeoutErrorsubclass raised when waiting for a response expires. Exposeserr.methodanderr.timeout.pw_rpc2.HandshakeError:ConnectionErrorsubclass raised when the opening handshake fails.err.statusisDISCONNECTEDif the socket closed during the handshake, orPROTOCOL_ERRORon an invalid reply, unsupported version, or timeout.pw_transport.SocketClosed(re-exported aspw_rpc2.SocketClosed):ConnectionErrorsubclass raised when starting a call on a closed client, or byread(),response(),write(), andClientStreamingCall.finish()on a call whose socket disconnected before the call completed. Closing the client locally (client.close()) does not raiseSocketClosedon existing calls: they end withCLOSED, so those operations raisepw_rpc2.RpcErrorwithstatus == RpcStatus.CLOSED.pw_rpc2.StreamClosedError:RuntimeErrorsubclass (err.status == RpcStatus.WRITE_CLOSED) raised whenwrite()is called after the request stream was finished or the call succeeded, or whenBidirectionalStreamingCall.finish()is called on an already-closed stream or completed call. (If the call ended with an error,write()raises that error instead.)pw_rpc2.DecodeError: Raised when a wire packet header (err.status == RpcStatus.PROTOCOL_ERROR) or response protobuf payload (err.status == RpcStatus.DATA_ERROR) cannot be decoded. A malformed packet header closes the connection and causes subsequent calls on the same client to raiseDecodeError; a malformed response payload onread()drops only that message and leaves a streaming call open.TypeErrorandValueError: Raised locally for invalid request arguments or unknown fields, outbound packets larger thansocket.max_write_message_size(nothing is sent and a streaming call stays open), negative timeouts, or colliding service/method definitions.
try:
reply = client.rpcs.examples.Echo.Echo(msg='hello', rpc2_timeout=1.0)
except pw_rpc2.RpcTimeout as err:
print(f'{err.method.full_name} timed out after {err.timeout:g} s')
except pw_rpc2.RpcError as err:
print(f'RPC failed ({err.status}): {err}')
except pw_rpc2.SocketClosed:
print('Connection lost')
Status codes and wire errors#
pw_rpc2.RpcStatus and the internal ProtocolError wire enum are
generated from the same TOML definitions as C++, keeping their names and values
identical. See C++ error handling for
guidance on handling each status code, and
RPC error codes for the wire
protocol definitions. Server ProtocolError packets map to
pw_rpc2.RpcStatus just like C++’s PeerErrorToRpcStatus:
|
Wire |
Meaning |
|---|---|---|
|
(normal completion) |
Call completed normally. |
|
|
Application code on either side ended the call; do not auto-retry. |
|
(local only) |
Client was closed locally. |
|
(local only) |
Underlying socket closed during the handshake (active calls raise
|
|
(local only) |
Outbound request stream is already closed ( |
|
|
Server could not accept the call before the method ran; safe to retry. |
|
|
Server ended the call after it started; retry only if idempotent. |
|
|
Server does not offer this service or method in the expected form. |
|
|
Request or response payload could not be decoded as a protobuf message. |
|
|
Wire protocol violation or incompatible endpoint implementation. |
RpcStatus also defines END_OF_STREAM, MESSAGE_TOO_LARGE, and
RESOURCE_EXHAUSTED from the shared rpc_code.toml schema; in Python,
end-of-stream returns None from read() (or ends iteration) and oversized
packets raise ValueError.
Custom transports#
pw_rpc2 depends only on pw_transport
(//pw_transport/py:pw_transport) and operates over any
pw_transport.ReliableSocket—the Python counterpart to C++’s
transport::ReliableSocket. Each
write() sends one complete pw_rpc2 packet, and
each read() returns one complete packet.
To implement a custom transport, subclass
pw_transport.ReliableSocket and implement _read(), _write(),
closed, and close(). See Python for full
transport contract details:
import pw_transport
class CustomReliableSocket(pw_transport.ReliableSocket):
@property
def max_write_message_size(self) -> int | None:
return 1024
@property
def closed(self) -> bool:
...
def _read(self, deadline: pw_transport.Deadline) -> bytes:
# Block until the next framed packet arrives, or raise TimeoutError
# or SocketClosed.
...
def _write(self, data: bytes, deadline: pw_transport.Deadline) -> None:
# Transmit one whole framed packet, or raise TimeoutError or
# SocketClosed.
...
def close(self) -> None:
# Close the link and unblock pending read() and write() calls.
...