asyncio experiment: Wrapper method approach

docs/api/index.md

@@ -171,6 +171,7 @@ Server <libtmux.server>
 Session <libtmux.session>
 Window <libtmux.window>
 Pane <libtmux.pane>
+Async <async>
 Client <libtmux.client>
 Common <libtmux.common>
 Neo <libtmux.neo>

docs/api/libtmux.server.md

@@ -9,6 +9,17 @@
 
 tmux initializes a server automatically on first running (e.g. executing `tmux`)
 
+## Async Methods
+
+Server provides async versions of key methods for use in async applications:
+
+- {meth}`~Server.ahas_session` - Check if session exists asynchronously
+- {meth}`~Server.anew_session` - Create new session asynchronously
+
+See {ref}`async` for comprehensive async documentation.
+
+## API Reference
+
 ```{eval-rst}
 .. autoclass:: libtmux.Server
     :members:

docs/api/libtmux.session.md

@@ -6,6 +6,17 @@
 - Contain {ref}`Windows` (which contain {ref}`Panes`)
 - Identified by `$`, e.g. `$313`
 
+## Async Methods
+
+Session provides async versions of key methods for use in async applications:
+
+- {meth}`~Session.anew_window` - Create new window asynchronously
+- {meth}`~Session.arename_session` - Rename session asynchronously
+
+See {ref}`async` for comprehensive async documentation.
+
+## API Reference
+
 ```{eval-rst}
 .. autoclass:: libtmux.Session
     :members:

docs/api/libtmux.window.md

@@ -6,6 +6,16 @@
 - Contain {ref}`Panes`
 - Identified by `@`, e.g. `@313`
 
+## Async Methods
+
+Window provides async versions of key methods for use in async applications:
+
+- {meth}`~Window.akill` - Kill window asynchronously
+
+See {ref}`async` for comprehensive async documentation.
+
+## API Reference
+
 ```{module} libtmux
 :no-index:
 ```

docs/quickstart.md

@@ -12,7 +12,7 @@ from inside a live tmux session.
 
 ## Requirements
 
-- [tmux] 3.2a or newer
+- [tmux]
 - [pip] - for this handbook's examples
 
 [tmux]: https://tmux.github.io/
@@ -45,15 +45,10 @@ before general availability.
 - [pipx]\:
 
   ```console
-  $ pipx install \
-      --suffix=@next \
-      --pip-args '\--pre' \
-      --force \
-      'libtmux'
+  $ pipx install --suffix=@next 'libtmux' --pip-args '\--pre' --force
+  // Usage: libtmux@next [command]
   ```
 
-  Usage: `libtmux@next [command]`
-
 - [uv tool install][uv-tools]\:
 
   ```console
@@ -83,10 +78,7 @@ via trunk (can break easily):
 - [pipx]\:
 
   ```console
-  $ pipx install \
-      --suffix=@master \
-      --force \
-      'libtmux @ git+https://github.com/tmux-python/libtmux.git@master'
+  $ pipx install --suffix=@master 'libtmux @ git+https://github.com/tmux-python/libtmux.git@master' --force
   ```
 
 - [uv]\:
@@ -139,7 +131,7 @@ $ ptpython
 ```
 
 ```{module} libtmux
-:no-index:
+
 ```
 
 First, we can grab a {class}`~libtmux.Server`.
@@ -471,38 +463,89 @@ prevents adding it to the user's shell history. Omitting `enter=false` means the
 default behavior (sending the command) is done, without needing to use
 {meth}`pane.enter() <libtmux.Pane.enter>` after.
 
-## Working with options
+## Async Support
 
 libtmux provides a unified API for managing tmux options across
 {class}`~libtmux.Server`, {class}`~libtmux.Session`,
 {class}`~libtmux.Window`, and {class}`~libtmux.Pane` objects.
 
-### Getting options
+For async applications, libtmux provides async versions of key methods using the 'a' prefix naming convention.
+
+### Basic Async Usage
 
 ```python
->>> server.show_option('buffer-limit')
-50
+import asyncio
+from libtmux import Server
 
->>> window.show_options()  # doctest: +ELLIPSIS
-{...}
-```
+async def main():
+    server = Server()
 
-### Setting options
+    # Create session asynchronously
+    session = await server.anew_session(session_name="async_demo")
 
-```python
->>> window.set_option('automatic-rename', False)  # doctest: +ELLIPSIS
-Window(@... ...)
+    # Create window asynchronously
+    window = await session.anew_window(window_name="async_window")
 
->>> window.show_option('automatic-rename')
-False
+    # Check session exists
+    exists = await server.ahas_session("async_demo")
+    print(f"Session exists: {exists}")  # True
 
->>> window.unset_option('automatic-rename')  # doctest: +ELLIPSIS
-Window(@... ...)
+asyncio.run(main())
 ```
 
-:::{seealso}
-See {ref}`options-and-hooks` for more details on options and hooks.
-:::
+### Concurrent Operations
+
+One of the key benefits of async methods is concurrent execution:
+
+```python
+import asyncio
+
+async def setup_workspace():
+    server = Server()
+
+    # Create multiple sessions concurrently
+    frontend, backend, database = await asyncio.gather(
+        server.anew_session(
+            session_name="frontend",
+            start_directory="~/project/frontend"
+        ),
+        server.anew_session(
+            session_name="backend",
+            start_directory="~/project/backend"
+        ),
+        server.anew_session(
+            session_name="database",
+            start_directory="~/project/database"
+        ),
+    )
+
+    # Set up windows in each session concurrently
+    await asyncio.gather(
+        frontend.anew_window(window_name="editor"),
+        frontend.anew_window(window_name="server"),
+        backend.anew_window(window_name="api"),
+        backend.anew_window(window_name="tests"),
+    )
+
+    return frontend, backend, database
+```
+
+### Available Async Methods
+
+- {meth}`Server.ahas_session` - Check if session exists
+- {meth}`Server.anew_session` - Create new session
+- {meth}`Session.anew_window` - Create new window
+- {meth}`Session.arename_session` - Rename session
+- {meth}`Window.akill` - Kill window
+
+### When to Use Async
+
+Use async methods when:
+- Your application uses asyncio
+- You need to perform multiple tmux operations concurrently
+- You're integrating with async frameworks (FastAPI, aiohttp, etc.)
+
+For more details, see {ref}`async`.
 
 ## Final notes
 
@@ -521,3 +564,4 @@ and our [test suite] (see {ref}`development`.)
 :::
 
 [test suite]: https://github.com/tmux-python/libtmux/tree/master/tests
+[ptpython]: https://github.com/prompt-toolkit/ptpython

pyproject.toml

@@ -61,6 +61,7 @@ dev = [
   "typing-extensions; python_version < '3.11'",
   "gp-libs>=0.0.19",
   "pytest",
+  "pytest-asyncio",
   "pytest-rerunfailures",
   "pytest-mock",
   "pytest-watcher",
@@ -84,6 +85,7 @@ testing = [
   "typing-extensions; python_version < '3.11'",
   "gp-libs>=0.0.19",
   "pytest",
+  "pytest-asyncio",
   "pytest-rerunfailures",
   "pytest-mock",
   "pytest-watcher",

src/libtmux/common.py

@@ -7,6 +7,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import functools
 import logging
 import re
@@ -378,6 +379,149 @@ def __init__(self, *args: t.Any, tmux_bin: str | None = None) -> None:
             )
 
 
+class AsyncTmuxCmd:
+    """
+    An asyncio-compatible class for running any tmux command via subprocess.
+
+    Attributes
+    ----------
+    cmd : list[str]
+        The full command (including the "tmux" binary path).
+    stdout : list[str]
+        Lines of stdout output from tmux.
+    stderr : list[str]
+        Lines of stderr output from tmux.
+    returncode : int
+        The process return code.
+
+    Examples
+    --------
+    >>> import asyncio
+    >>>
+    >>> async def main():
+    ...     proc = await AsyncTmuxCmd.run('-V')
+    ...     if proc.stderr:
+    ...         raise exc.LibTmuxException(
+    ...             f"Error invoking tmux: {proc.stderr}"
+    ...         )
+    ...     print("tmux version:", proc.stdout)
+    ...
+    >>> asyncio.run(main())
+        tmux version: [...]
+
+    This is equivalent to calling:
+
+    .. code-block:: console
+
+        $ tmux -V
+    """
+
+    def __init__(
+        self,
+        cmd: list[str],
+        stdout: list[str],
+        stderr: list[str],
+        returncode: int,
+    ) -> None:
+        """
+        Store the results of a completed tmux subprocess run.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            The command used to invoke tmux.
+        stdout : list[str]
+            Captured lines from tmux stdout.
+        stderr : list[str]
+            Captured lines from tmux stderr.
+        returncode : int
+            Subprocess exit code.
+        """
+        self.cmd: list[str] = cmd
+        self.stdout: list[str] = stdout
+        self.stderr: list[str] = stderr
+        self.returncode: int = returncode
+
+    @classmethod
+    async def run(cls, *args: t.Any) -> AsyncTmuxCmd:
+        """
+        Execute a tmux command asynchronously and capture its output.
+
+        Parameters
+        ----------
+        *args : str
+            Arguments to be passed after the "tmux" binary name.
+
+        Returns
+        -------
+        AsyncTmuxCmd
+            An instance containing the cmd, stdout, stderr, and returncode.
+
+        Raises
+        ------
+        exc.TmuxCommandNotFound
+            If no "tmux" executable is found in the user's PATH.
+        exc.LibTmuxException
+            If there's any unexpected exception creating or communicating
+            with the tmux subprocess.
+        """
+        tmux_bin: str | None = shutil.which("tmux")
+        if not tmux_bin:
+            msg = "tmux executable not found in PATH"
+            raise exc.TmuxCommandNotFound(
+                msg,
+            )
+
+        cmd: list[str] = [tmux_bin] + [str(c) for c in args]
+
+        try:
+            process: asyncio.subprocess.Process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout_bytes, stderr_bytes = await process.communicate()
+            returncode: int = (
+                process.returncode if process.returncode is not None else -1
+            )
+
+        except Exception as e:
+            logger.exception("Exception for %s", " ".join(cmd))
+            msg = f"Exception while running tmux command: {e}"
+            raise exc.LibTmuxException(
+                msg,
+            ) from e
+
+        # Decode bytes to string with error handling
+        stdout = stdout_bytes.decode(errors="backslashreplace")
+        stderr = stderr_bytes.decode(errors="backslashreplace")
+
+        # Split on newlines and filter empty lines
+        stdout_split: list[str] = stdout.split("\n")
+        # remove trailing newlines from stdout
+        while stdout_split and stdout_split[-1] == "":
+            stdout_split.pop()
+
+        stderr_split = stderr.split("\n")
+        stderr_split = list(filter(None, stderr_split))  # filter empty values
+
+        # Workaround for tmux "has-session" command behavior
+        if "has-session" in cmd and stderr_split and not stdout_split:
+            # If `has-session` fails, it might output an error on stderr
+            # with nothing on stdout. We replicate the original logic here:
+            stdout_split = [stderr_split[0]]
+
+        logger.debug("stdout for %s: %s", " ".join(cmd), stdout_split)
+        logger.debug("stderr for %s: %s", " ".join(cmd), stderr_split)
+
+        return cls(
+            cmd=cmd,
+            stdout=stdout_split,
+            stderr=stderr_split,
+            returncode=returncode,
+        )
+
+
 class _TmuxVersionUnavailable(Exception):
     """Internal signal: this tmux predates the ``-V`` flag (pre-1.7)."""