Server,Session,Window: Add .acmd

Author: tony

src/libtmux/server.py

@@ -276,7 +276,7 @@ async def acmd(
         Output of `tmux -L ... new-window -P -F#{window_id}` to a `Window` object:
 
         >>> async def test_new_window():
-        ...     result = await server.acmd('new-window', '-P', '-F#{window_id}')
+        ...     result = await session.acmd('new-window', '-P', '-F#{window_id}')
         ...     window_id = result.stdout[0]
         ...     window = Window.from_window_id(window_id=window_id, server=server)
         ...     print(window)
@@ -294,7 +294,7 @@ async def acmd(
         Output of `tmux -L ... split-window -P -F#{pane_id}` to a `Pane` object:
 
         >>> async def test_pane():
-        ...     result = await server.acmd('split-window', '-P', '-F#{pane_id}')
+        ...     result = await window.acmd('split-window', '-P', '-F#{pane_id}')
         ...     pane_id = result.stdout[0]
         ...     pane = Pane.from_pane_id(pane_id=pane_id, server=server)
         ...     print(pane)

src/libtmux/session.py

@@ -21,6 +21,7 @@
 
 from . import exc
 from .common import (
+    AsyncTmuxCmd,
     EnvironmentMixin,
     WindowDict,
     handle_option_error,
@@ -186,6 +187,62 @@ def cmd(
             target = self.session_id
         return self.server.cmd(cmd, *args, target=target)
 
+    async def acmd(
+        self,
+        cmd: str,
+        *args: t.Any,
+        target: t.Optional[t.Union[str, int]] = None,
+    ) -> AsyncTmuxCmd:
+        """Execute tmux subcommand within session context.
+
+        Automatically binds target by adding  ``-t`` for object's session ID to the
+        command. Pass ``target`` to keyword arguments to override.
+
+        Examples
+        --------
+        >>> import asyncio
+        >>> async def test_acmd():
+        ...     result = await session.acmd('new-window', '-P')
+        ...     print(result.stdout[0])
+        >>> asyncio.run(test_acmd())
+        libtmux...:....0
+
+        From raw output to an enriched `Window` object:
+
+        >>> async def test_from_window():
+        ...     window_id_result = await session.acmd(
+        ...         'new-window', '-P', '-F#{window_id}'
+        ...     )
+        ...     return Window.from_window_id(
+        ...         window_id=window_id_result.stdout[0],
+        ...         server=session.server
+        ...     )
+        >>> asyncio.run(test_from_window())
+        Window(@... ...:..., Session($1 libtmux_...))
+
+        Parameters
+        ----------
+        target : str, optional
+            Optional custom target override. By default, the target is the session ID.
+
+        Returns
+        -------
+        :meth:`server.cmd`
+
+        Notes
+        -----
+        .. versionchanged:: 0.34
+
+           Passing target by ``-t`` is ignored. Use ``target`` keyword argument instead.
+
+        .. versionchanged:: 0.8
+
+            Renamed from ``.tmux`` to ``.cmd``.
+        """
+        if target is None:
+            target = self.session_id
+        return await self.server.acmd(cmd, *args, target=target)
+
     """
     Commands (tmux-like)
     """

src/libtmux/window.py

@@ -23,7 +23,7 @@
 from libtmux.pane import Pane
 
 from . import exc
-from .common import PaneDict, WindowOptionDict, handle_option_error
+from .common import AsyncTmuxCmd, PaneDict, WindowOptionDict, handle_option_error
 
 if t.TYPE_CHECKING:
     from .server import Server
@@ -175,6 +175,55 @@ def cmd(
 
         return self.server.cmd(cmd, *args, target=target)
 
+    async def acmd(
+        self,
+        cmd: str,
+        *args: t.Any,
+        target: t.Optional[t.Union[str, int]] = None,
+    ) -> AsyncTmuxCmd:
+        """Execute tmux subcommand within window context.
+
+        Automatically binds target by adding  ``-t`` for object's window ID to the
+        command. Pass ``target`` to keyword arguments to override.
+
+        Examples
+        --------
+        Create a pane from a window:
+
+        >>> import asyncio
+        >>> async def test_acmd():
+        ...     result = await window.acmd('split-window', '-P', '-F#{pane_id}')
+        ...     print(result.stdout[0])
+        >>> asyncio.run(test_acmd())
+        %...
+
+        Magic, directly to a `Pane`:
+
+        >>> async def test_from_pane():
+        ...     pane_id_result = await session.acmd(
+        ...         'split-window', '-P', '-F#{pane_id}'
+        ...     )
+        ...     return Pane.from_pane_id(
+        ...         pane_id=pane_id_result.stdout[0],
+        ...         server=session.server
+        ...     )
+        >>> asyncio.run(test_from_pane())
+        Pane(%... Window(@... ...:..., Session($1 libtmux_...)))
+
+        Parameters
+        ----------
+        target : str, optional
+            Optional custom target override. By default, the target is the window ID.
+
+        Returns
+        -------
+        :meth:`server.cmd`
+        """
+        if target is None:
+            target = self.window_id
+
+        return await self.server.acmd(cmd, *args, target=target)
+
     """
     Commands (tmux-like)
     """