Synchronous Connection

Import Connection from rmote.sync or directly from rmote. Create a connection with from_local or from_ssh. Direct construction with Connection() raises TypeError.

class rmote.sync.Connection

Own a subprocess, a protocol, and a private background event loop. Use a factory and close the connection after its callers finish.

classmethod from_local(*, python='/home/runner/work/rmote/rmote/.venv/bin/python', cwd=None, env=None, stderr=-3, connect_timeout=30.0, rpc_timeout=None, close_timeout=5.0)

Start a local Python interpreter and complete its protocol handshake.

Arguments go directly to subprocess exec, without a shell. If stderr is PIPE, the connection reads and discards it until process exit.

Return type:

Self

classmethod from_ssh(host, *, user=None, port=None, identity=None, python='python3', ssh_options=None, stderr=-3, connect_timeout=30.0, rpc_timeout=None, close_timeout=5.0)

Start SSH and complete the remote Python protocol handshake.

Return type:

Self

__call__(tool, /, *args, **kwargs)

Overloads:

• self, tool (Callable[P, Coroutine[Any, Any, R]]), args (P.args), kwargs (P.kwargs) → R

• self, tool (Callable[P, R]), args (P.args), kwargs (P.kwargs) → R

Call a Tool method using the connection’s default RPC deadline.

Both synchronous and asynchronous Tool methods return their result. Every keyword argument belongs to the remote method.

call_with_timeout(timeout, tool, /, *args, **kwargs)

Overloads:

• self, timeout (float | None), tool (Callable[P, Coroutine[Any, Any, R]]), args (P.args), kwargs (P.kwargs) → R

• self, timeout (float | None), tool (Callable[P, R]), args (P.args), kwargs (P.kwargs) → R

Call a Tool with a deadline covering upload, send, and response.

None disables this call’s deadline. Timeout and KeyboardInterrupt stop local waiting. They do not stop the remote operation. A cancellation during packet transmission can make the connection unusable. After a detected transport failure, new calls raise ConnectionError with the original error as their cause. Calls already waiting for a response propagate the original transport error.

close()

Close the protocol, reap the process, and join the runtime thread.

Concurrent calls wait for the same cleanup. Repeated calls are safe. Process shutdown uses close_timeout, then terminate and kill. Cancellation and executor shutdown require cooperative local code.

Return type:

None

__enter__()

Return type:

Self

__exit__(exc_type, exc_value, traceback)

Return type:

None

Deadlines

Both factories accept these keyword-only arguments:

• connect_timeout=30.0 limits process creation, bootstrap, and handshake.

• rpc_timeout=None sets the default deadline for each Tool call.

• close_timeout=5.0 limits graceful protocol and process shutdown.

None disables a connect or RPC deadline. Numeric deadlines must be finite and positive. close_timeout must be finite and positive; it cannot be None. Invalid values raise ValueError before resource creation.

connection.call_with_timeout(timeout, tool, /, *args, **kwargs) overrides the default RPC deadline for one call. It includes the first Tool upload, packet transmission, and response. All keyword arguments go to the Tool method, including arguments named timeout or tool.

Timeout raises TimeoutError. KeyboardInterrupt propagates unchanged. Both stop local waiting; the remote operation can continue. Cancellation during packet transmission can make the connection unusable. Close it and create a new connection after a transport failure.

Ownership and concurrency

Each connection owns one subprocess, one protocol, and one private event loop in a background thread. Factories return after the handshake completes. Factory failure or interruption cleans up partially created resources.

Use with or call close() in finally. Closing rejects new calls, closes the channel, reaps the process, and joins the background thread. After close_timeout, process cleanup uses terminate, a one-second grace period, then kill and wait. This is not a fixed total limit for close(): local cancellation and executor shutdown require cooperative code.

Repeated close() calls are safe. Concurrent closes wait for the same cleanup. Nested context entry and calls after closing raise RuntimeError. Context exit preserves an exception raised by the body; cleanup errors are logged when a body exception already exists.

Multiple caller threads can share an open connection. Remote log records run local logging handlers in the background loop thread. Handlers must be thread safe and must not call this connection’s synchronous methods. Calls from its own loop thread raise RuntimeError.

In async applications, use Protocol or move the complete synchronous lifecycle into asyncio.to_thread. A direct synchronous call blocks the calling event loop. Shared runtimes, automatic reconnect, and remote cancellation are not supported.

See Quickstart, Work with Multiple Hosts, and Writing Tools for executable examples and Tool definitions.