!squash WIP Session.cmd warning for target kw

Author: tony

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,6 +160,11 @@ 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`
@@ -170,6 +177,11 @@ def cmd(self, cmd: str, *args: t.Any) -> tmux_cmd:
         """
         # if -t is not set in any arg yet
         if not any("-t" in str(x) for x in args):
+            # warnings.warn(
+            #     "Use `target=...` instead of passing `-t` as an argument.",
+            #     category=DeprecationWarning,
+            #     stacklevel=2,
+            # )
             # insert -t immediately after 1st arg, as per tmux format
             new_args: t.Tuple[str, ...] = ()
             assert isinstance(self.session_id, str)