Rework execnet onto a trio-native core (sync facade, uv-provisioned workers, execnet.trio)

[RonnyPfannschmidt]

What this is

A ground-up rework of execnet onto Trio, replacing the thread-per-gateway receiver/writer architecture and the source-shipping bootstrap. This is execnet 3.0: the launch contract, the default transport and the ownership of a worker's stdio all change.

The blocking API is preserved as a facade over the new core, and released pytest-xdist keeps working against it unmodified — that is a hard constraint on this branch, checked in CI.

One protocol engine, four surfaces

AsyncGateway (_trio_gateway.py) is the single protocol engine: one serve task per gateway running a reader (stream → sans-IO FrameDecoder → dispatch) and a writer draining an outbound queue. Everything else layers on it. There is now one namespace per concurrency library you drive execnet from:

namespace	what it is
execnet / execnet.sync	today's blocking API, unchanged; the top level aliases into sync
execnet.trio	trio-native AsyncGroup/AsyncGateway/AsyncChannel, awaited inside your own trio.run — no host thread
execnet.aio	the same surface for asyncio, bridged per call onto the host loop
execnet.gevent	the sync surface, with waits that park a greenlet rather than a thread

trio/aio/gevent load lazily, so import execnet still does not import an event loop. The blocking surfaces run their IO on a Host — one thread, one Trio loop, shared per process — and a blocking call made from inside a running event loop now raises and names the surface you wanted.

Underneath the serialized channel sits a two-level model: RawChannel carries id-routed verbatim byte payloads, which is what makes the via= tunnel frame-native instead of double-framed.

No source shipping, and a real launch contract

Nothing is bootstrapped over the wire. Workers import an installed execnet + trio, launched through a CLI that is now the contract between coordinator and worker:

execnet worker  --protocol-stdio | --protocol-fd FD[,FD]
                | --protocol-connect ADDR | --protocol-listen ADDR
                | --protocol-share
                --config JSON | --config-fd FD | --config-file PATH
                --stdin/--stdout/--stderr DISPOSITION
execnet server  [HOST:PORT] [--once]
execnet info

Foreign interpreters (python=) and ssh/vagrant remotes are provisioned on demand via uv; a dev coordinator builds and ships a wheel, cached remotely. execnet info answers JSON, so provisioning learns a remote's version before connecting.

The protocol is no longer the worker's stdin/stdout

A new transport=socket|stdio spec key selects, and socket is the default for every worker execnet spawns: an inherited socketpair on POSIX, a socket duplicated with socket.share() on Windows, and an ssh -R-forwarded unix socket the worker dials back on for ssh.

Two things fall out of that, both of them user-visible fixes:

• A worker's stdio belongs to the code it runs. It used to be pointed at the null device, so a remote print() went nowhere at all. New stdin=/stdout=/stderr= spec keys override.
• The worker config no longer travels in a remote argv, which closes an exposure: it carries env: values, and ps is readable by every user on the host.

Windows is supported and tested for the first time; ssh there stays on stdio, because CPython has never exposed AF_UNIX on Windows and Win32-OpenSSH has no StreamLocal forwarding.

Worker profiles

execmodel= is now spelled profile= (the old spelling stays as a permanent alias) and selects where exec'd code runs relative to the worker's protocol loop:

profile	exec'd code runs
thread (default)	the classic hybrid: the first remote_exec claims the worker's main thread, further ones overflow to pool threads
trio (new)	async sources as tasks — one thread in the whole worker
gevent (revived)	a greenlet per remote_exec on a main-thread hub

main_thread_only is deprecated and aliases to thread, which already gives the first remote_exec the real main thread — the GUI/signal property it existed for.

pytest-xdist

Released xdist must drive a 3.0 coordinator with no changes on its side, so the deprecated shims it reaches for (execnet.gateway_base.ExecModel, execnet.dumps, Group(execmodel=...), the execmodel= spec key) ship in 3.0. They go later in the 3.x series, once consumers have released without them.

CI runs xdist's own test suite against this execnet, in a pinned release variant that blocks and a floating default-branch variant that warns. Doing that for the first time found 16 real regressions our own suite structurally could not see — it uses xdist as a tool, which exercises none of the crash-replacement or report-serialization paths. Both are green now, with one deselect (test_remote_inner_argv asserts sys.argv == ["-c"], which the no-source-shipping launch deliberately changed; it needs an xdist PR).

Breaking changes

• Remote environments must have execnet installed, or be reachable by uv provisioning; the zero-install source bootstrap is gone.
• Trio is a hard runtime dependency.
• execnet.dump/load/loads and execnet.script.* are gone; can_send replaces probing with dumps/DumpError.
• The pre-Trio module names (execnet.gateway_base, gateway, multi, rsync, rsync_remote, xspec) warn and forward; gateway_bootstrap, gateway_io and gateway_socket are simply gone.
• A blocking call inside a running event loop raises instead of hanging; a killed worker is uniformly EOFError; worker stdio is no longer swallowed.
• eventlet is removed. The EXECNET_TRIO_HOST escape hatch and the legacy bootstrap stack are gone.

Semantics deliberately kept

• Sends from non-loop threads block until the frame reached the OS write (120s → OSError), so an abrupt os._exit cannot drop already-"sent" data.
• remote_exec admission order == message arrival order.
• Group.terminate(timeout) is bounded (~2× timeout) even when a kill sticks.
• Blocking waits stay KeyboardInterrupt-interruptible.
• Channel callbacks preserve per-channel order, and waitclose() still returns only after every callback including the endmarker — they now run off the loop thread, so a slow callback no longer blocks the reader.

Still open before release

Tracked in ROADMAP-3.0.md in the repo root (with HANDOFF.md for the current state and handoff-history.md for the record):

• a neutral capability key in execnet info — the one item that cannot be changed after release, since it is a cross-version probe contract that currently names our engine;
• small surface cleanups (deprecated names out of __all__, underscoring two engine methods on trio.AsyncGateway);
• provisioning and workspaces, so the next pytest-xdist can stop hand-rolling deployment: uv-bootstrap a remote python with the project under test installed, rsync the tests, and get back a local→remote path mapping;
• driving test runs across Kubernetes pods over the protocol — the same problem with a shorter-lived remote;
• deferred: an anyio/asyncio core (the engine sticks to portable idioms — neutral ByteStream, sans-IO frame decoding — to keep that cheap).

Test status

uv run pytest testing/: 552 passed, 66 skipped, sequentially and under -n 12. pre-commit run -a clean. tox -e docs builds with -W and runs the documentation examples as doctests. ssh paths are covered by a real local harness (testing/test_ssh_local.py, asyncssh server + system ssh client).

🤖 Generated with Claude Code