Docs

Asyncio

• https://docs.python.org/3/library/asyncio.html

Adding Asyncio Support to libtmux (Python 3.9+)

Key Functions Requiring Asynchronous Execution

Several core functions in libtmux currently execute tmux commands synchronously (blocking the main thread). These need refactoring for async operation:

• libtmux.common.tmux_cmd – This helper (class/function) runs tmux commands via subprocess.Popen and waits for completion. It blocks while reading tmux’s output, so making it async is crucial.
• libtmux.neo module – Helper functions (e.g. fetch_obj, list/query functions for sessions, windows, panes) call tmux’s list-* commands and parse results synchronously, blocking the thread. These should be awaitable to avoid blocking.
• libtmux.server.Server methods – Methods like Server.cmd(...), Server.new_session(...), Server.attach_session(...), and Server.kill_server() execute tmux commands synchronously. These must be adapted for asynchronous operation.
• libtmux.session.Session methods – Methods such as Session.new_window(...), Session.rename_session(...), and Session.kill_session() invoke synchronous tmux commands internally and should provide async equivalents or become fully non-blocking.

By identifying these functions, we can target them for asyncio integration so managing tmux sessions and windows no longer halts the main thread.

Approach 1: Using asyncio.subprocess for Non-Blocking Tmux Calls

Python’s asyncio provides native support for spawning subprocesses without blocking the event loop. This would involve rewriting libtmux’s command execution to an async def style. For example:

import asyncio

async def run_tmux_command(args:list[str]) -> list[str]:
    proc = await asyncio.create_subprocess_exec(
        "tmux", *args,
        stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
    )
    stdout, stderr = await proc.communicate()
    if proc.returncode != 0:
        err_msg = stderr.decode().strip()
        raise RuntimeError(f"tmux error: {err_msg}")
    return stdout.decode().splitlines()

In a Server class, we could add an async method:

class Server:
    async def cmd_async(self, *args: str) -> list[str]:
        cmd_args = [] 
        if self.socket_name:
            cmd_args += ["-L", self.socket_name]
        cmd_args += args
        return await run_tmux_command(cmd_args)

Using this async API, multiple tmux commands can run concurrently without blocking:

sessions_task = asyncio.create_task(server.cmd_async("list-sessions"))
new_session_task = asyncio.create_task(server.cmd_async("new-session", "-s", "test"))
await asyncio.gather(sessions_task, new_session_task)

Pros:

• Simple, idiomatic asyncio code
• High-level concurrency

Cons:

• May require new async methods, potentially breaking backward compatibility
• Process creation overhead for frequent commands

Approach 2: Async Wrappers using Threads or Process Pools

Maintain existing synchronous implementations, adding asynchronous wrappers via threads (asyncio.to_thread) or executors:

Example (Pane.send_keys adapted to async):

class Pane:
    def send_keys(self, keys: str):
        # blocking call that runs `tmux send-keys`
        ...

    async def asend_keys(self, keys: str):
        await asyncio.to_thread(self.send_keys, keys)

Now, await pane.asend_keys("ls -la") executes asynchronously, without blocking the event loop.

Pros:

• Easy, incremental implementation
• Preserves backward compatibility
• Low risk; uses existing code

Cons:

• Thread overhead (usually minimal for tmux)
• Potential thread-safety issues if shared state is mutated

Approach 3: Persistent Tmux Session with Async I/O (Control Mode)

Use tmux’s control mode (tmux -C) to maintain a persistent process for asynchronous command execution:

proc = await asyncio.create_subprocess_exec(
    "tmux", "-C", "attach-session", "-t", "my_session",
    stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE
)

# Async send command example
proc.stdin.write(b"list-windows -t my_session\n")
await proc.stdin.drain()
response = await proc.stdout.readline()
print("Tmux replied:", response.decode().strip())

Pros:

• Minimal overhead per command after initial setup
• Enables high-throughput and event-driven communication

Cons:

• Most complex implementation
• Requires robust parsing and command-response correlation logic
• Higher maintenance burden

Trade-Offs Between Approaches

Recommendation

A combined approach might be ideal:

• Threads/Executors (Approach 2): Quick win for async compatibility with minimal effort and backward compatibility. Good starting point for incremental asyncio support.
• Asyncio Subprocess (Approach 1): Longer-term solution providing clean, idiomatic async APIs, facilitating future concurrency benefits.
• Persistent Control Mode (Approach 3): Ideal if high-performance or real-time event handling is required, albeit with significantly more complexity and maintenance overhead.

Each option involves trade-offs between performance, implementation complexity, and compatibility. Selection depends on libtmux’s roadmap priorities.

Sources

• Python asyncio subprocess documentation:
  https://docs.python.org/3/library/asyncio-subprocess.html

• Running blocking functions asynchronously with executors:
  https://docs.python.org/3/library/asyncio-eventloop.html#running-in-executor

• Tmux control mode documentation:
  https://github.com/tmux/tmux/wiki/Control-Mode

• Current synchronous implementation in libtmux:
  https://github.com/tmux-python/libtmux

See also

• pytest-asyncio incompatibility
  • pytest-asyncio incompatibility git-pull/gp-libs#43
  • Not compatible with --doctest-modules --doctest-ignore-import-errors pytest-dev/pytest-asyncio#797

Summary by Sourcery

Introduce asynchronous support for libtmux using asyncio.

New Features:

• Add AsyncTmuxCmd to run tmux commands asynchronously.
• Add acmd method to Server, Session, Window, and Pane objects for asynchronous command execution.

Tests:

• Add tests for asynchronous operations.