Skip to content

unienv_interface.remote.transport

Frame transports: TCP and Unix stream sockets, WebSocket, and in-memory pairs.

Addresses are URLs: tcp://host:port, unix:///path/to.sock and ws://host:port. Port 0 picks a free port. Every transport sends one frame per :meth:Transport.send (thread-safe) and returns (json, buffers) from :meth:Transport.recv (one reader thread).

Classes:

Name Description
Transport

A reliable, ordered connection carrying whole frames.

StreamTransport

Frames over a connected stream socket; each frame goes out in one sendmsg.

MemoryTransport

In-process pair (tests); frames are copied, as on a real connection.

WebSocketTransport

One frame per binary WebSocket message (requires websockets).

Functions:

Name Description
parse_address

Return (scheme, host or path, port) for a transport URL.

connect

Open a client transport to address.

listen

Start accepting connections on address.

Frame module-attribute

Frame = Tuple[Any, List[Any]]

Transport

A reliable, ordered connection carrying whole frames.

Methods:

Name Description
send

Send the frame parts (size bytes in total). Thread-safe.

recv

Block for the next frame; raise ConnectionError once closed.

close

Close the connection, unblocking recv (idempotent).

Attributes:

Name Type Description
max_frame_size int

max_frame_size class-attribute instance-attribute

max_frame_size: int = DEFAULT_MAX_FRAME_SIZE

send

send(parts: Sequence[Any], size: int) -> None

Send the frame parts (size bytes in total). Thread-safe.

recv

recv() -> Frame

Block for the next frame; raise ConnectionError once closed.

close

close() -> None

Close the connection, unblocking recv (idempotent).

StreamTransport

StreamTransport(sock: socket, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE)

Bases: Transport

Frames over a connected stream socket; each frame goes out in one sendmsg.

Methods:

Name Description
send
recv
close

Attributes:

Name Type Description
max_frame_size int

max_frame_size class-attribute instance-attribute

max_frame_size: int = DEFAULT_MAX_FRAME_SIZE

send

send(parts: Sequence[Any], size: int) -> None

recv

recv() -> Frame

close

close() -> None

MemoryTransport

MemoryTransport(
    incoming: _Queue, outgoing: _Queue, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE
)

Bases: Transport

In-process pair (tests); frames are copied, as on a real connection.

Methods:

Name Description
pair
send
recv
close

Attributes:

Name Type Description
max_frame_size int

max_frame_size class-attribute instance-attribute

max_frame_size: int = DEFAULT_MAX_FRAME_SIZE

pair classmethod

pair(
    max_frame_size: int = DEFAULT_MAX_FRAME_SIZE,
) -> Tuple[MemoryTransport, MemoryTransport]

send

send(parts: Sequence[Any], size: int) -> None

recv

recv() -> Frame

close

close() -> None

WebSocketTransport

WebSocketTransport(connection: Any, max_frame_size: int = DEFAULT_MAX_FRAME_SIZE)

Bases: Transport

One frame per binary WebSocket message (requires websockets).

Methods:

Name Description
send
recv
close

Attributes:

Name Type Description
max_frame_size int

max_frame_size class-attribute instance-attribute

max_frame_size: int = DEFAULT_MAX_FRAME_SIZE

send

send(parts: Sequence[Any], size: int) -> None

recv

recv() -> Frame

close

close() -> None

Listener

A background accept loop; close stops accepting (open connections stay).

Methods:

Name Description
close

Attributes:

Name Type Description
address str

address instance-attribute

address: str

close

close() -> None

parse_address

parse_address(address: str) -> Tuple[str, str, Optional[int]]

Return (scheme, host or path, port) for a transport URL.

connect

connect(
    address: str,
    *,
    timeout: Optional[float] = 10.0,
    max_frame_size: int = DEFAULT_MAX_FRAME_SIZE,
) -> Transport

Open a client transport to address.

listen

listen(
    address: str,
    *,
    on_connect: Callable[[Transport], None],
    serve_connection: Callable[[Transport], None],
    max_frame_size: int = DEFAULT_MAX_FRAME_SIZE,
) -> Listener

Start accepting connections on address.

Stream connections are handed to on_connect (which must not block); WebSocket connections run serve_connection on the library's handler thread.