refactor!(cmd()): Explicit custom targets (#535)

See also:
- tmux-python/tmuxp#915
- #533
   - CiscoDevNet/virlutils#148

Author: tony

CHANGES

@@ -15,6 +15,19 @@ $ pip install --user --upgrade --pre libtmux
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version above -->
 
+### Breaking changes
+
+#### Command target change (#919)
+
+Commands: All `cmd()` methods using custom or overridden targets must use the keyword argument
+`target`. This avoids entanglement with inner shell values that include `-t` for
+other purposes. These methods include:
+
+- {meth}`Server.cmd()`
+- {meth}`Session.cmd()`
+- {meth}`Window.cmd()`
+- {meth}`Pane.cmd()`
+
 ## libtmux 0.33.0 (2024-03-17)
 
 ### Breaking changes

src/libtmux/pane.py

@@ -117,11 +117,16 @@ def session(self) -> "Session":
     Commands (pane-scoped)
     """
 
-    def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
+    def cmd(
+        self,
+        cmd: str,
+        *args: t.Any,
+        target: t.Optional[t.Union[str, int]] = None,
+    ) -> tmux_cmd:
         """Execute tmux subcommand within pane context.
 
-        Automatically adds ``-t`` for object's pane ID to the command. Pass ``-t``
-        in args to override.
+        Automatically binds target by adding  ``-t`` for object's pane ID to the
+        command. Pass ``target`` to keyword arguments to override.
 
         Examples
         --------
@@ -134,14 +139,19 @@ def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
         ... 'split-window', '-P', '-F#{pane_id}').stdout[0], server=pane.server)
         Pane(%... Window(@... ...:..., Session($1 libtmux_...)))
 
+        Parameters
+        ----------
+        target : str, optional
+            Optional custom target override. By default, the target is the pane ID.
+
         Returns
         -------
         :meth:`server.cmd`
         """
-        if not any("-t" in str(x) for x in args):
-            args = ("-t", self.pane_id, *args)
+        if target is None:
+            target = self.pane_id
 
-        return self.server.cmd(cmd, *args)
+        return self.server.cmd(cmd, *args, target=target)
 
     """
     Commands (tmux-like)
@@ -620,9 +630,6 @@ def split(
         if not attach:
             tmux_args += ("-d",)
 
-        if target is not None:
-            tmux_args += (f"-t{target}",)
-
         if environment:
             if has_gte_version("3.0"):
                 for k, v in environment.items():
@@ -635,7 +642,7 @@ def split(
         if shell:
             tmux_args += (shell,)
 
-        pane_cmd = self.cmd("split-window", *tmux_args)
+        pane_cmd = self.cmd("split-window", *tmux_args, target=target)
 
         # tmux < 1.7. This is added in 1.7.
         if pane_cmd.stderr:

src/libtmux/server.py

@@ -174,7 +174,12 @@ def raise_if_dead(self) -> None:
     #
     # Command
     #
-    def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
+    def cmd(
+        self,
+        cmd: str,
+        *args: t.Any,
+        target: t.Optional[t.Union[str, int]] = None,
+    ) -> tmux_cmd:
         """Execute tmux command respective of socket name and file, return output.
 
         Examples
@@ -207,6 +212,11 @@ def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
         ... 'split-window', '-P', '-F#{pane_id}').stdout[0], server=window.server)
         Pane(%... Window(@... ...:..., Session($1 libtmux_...)))
 
+        Parameters
+        ----------
+        target : str, optional
+            Optional custom target.
+
         Returns
         -------
         :class:`common.tmux_cmd`
@@ -217,22 +227,25 @@ def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
 
             Renamed from ``.tmux`` to ``.cmd``.
         """
-        cmd_args: t.List[t.Union[str, int]] = [cmd, *args]
+        svr_args: t.List[t.Union[str, int]] = [cmd]
+        cmd_args: t.List[t.Union[str, int]] = []
         if self.socket_name:
-            cmd_args.insert(0, f"-L{self.socket_name}")
+            svr_args.insert(0, f"-L{self.socket_name}")
         if self.socket_path:
-            cmd_args.insert(0, f"-S{self.socket_path}")
+            svr_args.insert(0, f"-S{self.socket_path}")
         if self.config_file:
-            cmd_args.insert(0, f"-f{self.config_file}")
+            svr_args.insert(0, f"-f{self.config_file}")
         if self.colors:
             if self.colors == 256:
-                cmd_args.insert(0, "-2")
+                svr_args.insert(0, "-2")
             elif self.colors == 88:
-                cmd_args.insert(0, "-8")
+                svr_args.insert(0, "-8")
             else:
                 raise exc.UnknownColorOption()
 
-        return tmux_cmd(*cmd_args)
+        cmd_args = ["-t", str(target), *args] if target is not None else [*args]
+
+        return tmux_cmd(*svr_args, *cmd_args)
 
     @property
     def attached_sessions(self) -> t.List[Session]:
@@ -274,7 +287,7 @@ def has_session(self, target_session: str, exact: bool = True) -> bool:
         if exact and has_gte_version("2.1"):
             target_session = f"={target_session}"
 
-        proc = self.cmd("has-session", "-t%s" % target_session)
+        proc = self.cmd("has-session", target=target_session)
 
         if not proc.returncode:
             return True
@@ -318,7 +331,7 @@ def kill_session(self, target_session: t.Union[str, int]) -> "Server":
         ------
         :exc:`exc.BadSessionName`
         """
-        proc = self.cmd("kill-session", "-t%s" % target_session)
+        proc = self.cmd("kill-session", target=target_session)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -339,7 +352,7 @@ def switch_client(self, target_session: str) -> None:
         """
         session_check_name(target_session)
 
-        proc = self.cmd("switch-client", "-t%s" % target_session)
+        proc = self.cmd("switch-client", target=target_session)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -357,12 +370,7 @@ def attach_session(self, target_session: t.Optional[str] = None) -> None:
         :exc:`exc.BadSessionName`
         """
         session_check_name(target_session)
-
-        tmux_args: t.Tuple[str, ...] = ()
-        if target_session:
-            tmux_args += ("-t%s" % target_session,)
-
-        proc = self.cmd("attach-session", *tmux_args)
+        proc = self.cmd("attach-session", target=target_session)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -456,7 +464,7 @@ def new_session(
 
             if self.has_session(session_name):
                 if kill_session:
-                    self.cmd("kill-session", "-t%s" % session_name)
+                    self.cmd("kill-session", target=session_name)
                     logger.info("session %s exists. killed it." % session_name)
                 else:
                     raise exc.TmuxSessionExists(

src/libtmux/session.py

@@ -141,11 +141,13 @@ def panes(self) -> QueryList["Pane"]:
     #
     # Command
     #
-    def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
+    def cmd(
+        self, cmd: str, *args: t.Any, target: t.Optional[t.Union[str, int]] = None
+    ) -> tmux_cmd:
         """Execute tmux subcommand within session context.
 
-        Automatically adds ``-t`` for object's session ID to the command. Pass ``-t``
-        in args to override.
+        Automatically binds target by adding  ``-t`` for object's session ID to the
+        command. Pass ``target`` to keyword arguments to override.
 
         Examples
         --------
@@ -158,28 +160,28 @@ def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
         ... 'new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
         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 -t is not set in any arg yet
-        if not any("-t" in str(x) for x in args):
-            # insert -t immediately after 1st arg, as per tmux format
-            new_args: t.Tuple[str, ...] = ()
-            assert isinstance(self.session_id, str)
-            new_args += (
-                "-t",
-                self.session_id,
-            )
-            new_args += args
-            args = new_args
-        return self.server.cmd(cmd, *args)
+        if target is None:
+            target = self.session_id
+        return self.server.cmd(cmd, *args, target=target)
 
     """
     Commands (tmux-like)
@@ -356,9 +358,9 @@ def select_window(self, target_window: t.Union[str, int]) -> "Window":
         # Note that we also provide the session ID here, since cmd()
         # will not automatically add it as there is already a '-t'
         # argument provided.
-        target = f"-t{self.session_id}:{target_window}"
+        target = f"{self.session_id}:{target_window}"
 
-        proc = self.cmd("select-window", target)
+        proc = self.cmd("select-window", target=target)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -495,7 +497,7 @@ def switch_client(self) -> "Session":
         ------
         :exc:`exc.LibTmuxException`
         """
-        proc = self.cmd("switch-client", "-t%s" % self.session_id)
+        proc = self.cmd("switch-client", target=self.session_id)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -653,9 +655,13 @@ def new_window(
                     "Direction flag ignored, requires tmux 3.1 or newer.",
                 )
 
+        target: t.Optional[str] = None
+        if window_index is not None:
+            # empty string for window_index will use the first one available
+            target = f"{self.session_id}:{window_index}"
         if target_window:
             if has_gte_version("3.2"):
-                window_args += (f"-t{target_window}",)
+                target = target_window
             else:
                 logger.warning(
                     "Window target ignored, requires tmux 3.1 or newer.",
@@ -667,7 +673,7 @@ def new_window(
         if window_shell:
             window_args += (window_shell,)
 
-        cmd = self.cmd("new-window", *window_args)
+        cmd = self.cmd("new-window", *window_args, target=target)
 
         if cmd.stderr:
             raise exc.LibTmuxException(cmd.stderr)
@@ -696,11 +702,11 @@ def kill_window(self, target_window: t.Optional[str] = None) -> None:
         """
         if target_window:
             if isinstance(target_window, int):
-                target = "-t%s:%d" % (self.window_name, target_window)
+                target = "%s:%d" % (self.window_name, target_window)
             else:
-                target = "-t%s" % target_window
+                target = "%s" % target_window
 
-        proc = self.cmd("kill-window", target)
+        proc = self.cmd("kill-window", target=target)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -797,7 +803,7 @@ def attach_session(self) -> "Session":
             category=DeprecationWarning,
             stacklevel=2,
         )
-        proc = self.cmd("attach-session", "-t%s" % self.session_id)
+        proc = self.cmd("attach-session", target=self.session_id)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
@@ -818,7 +824,7 @@ def kill_session(self) -> None:
             category=DeprecationWarning,
             stacklevel=2,
         )
-        proc = self.cmd("kill-session", "-t%s" % self.session_id)
+        proc = self.cmd("kill-session", target=self.session_id)
 
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)