Pane,Window(feat[swap]): add swap() wrapping tmux swap-pane and swap-window

why: swap-pane and swap-window are core layout manipulation commands needed
for programmatic pane and window reordering.
what:
- Add Pane.swap() with target, detach (-d), move_up (-U), move_down (-D),
  keep_zoom (-Z) parameters wrapping swap-pane
- Add Window.swap() with target, detach (-d) parameters wrapping swap-window
- Add tests verifying pane indices and window indices swap correctly

Author: tony

src/libtmux/pane.py

@@ -1139,6 +1139,61 @@ def enter(self) -> Pane:
         self.cmd("send-keys", "Enter")
         return self
 
+    def swap(
+        self,
+        target: str | Pane,
+        *,
+        detach: bool | None = None,
+        move_up: bool | None = None,
+        move_down: bool | None = None,
+        keep_zoom: bool | None = None,
+    ) -> None:
+        """Swap this pane with another via ``$ tmux swap-pane``.
+
+        Parameters
+        ----------
+        target : str or Pane
+            Target pane to swap with. Can be a pane ID string or Pane object.
+        detach : bool, optional
+            Do not change the active pane (``-d`` flag).
+        move_up : bool, optional
+            Swap with the pane above (``-U`` flag). Overrides *target*.
+        move_down : bool, optional
+            Swap with the pane below (``-D`` flag). Overrides *target*.
+        keep_zoom : bool, optional
+            Keep the window zoomed if it was zoomed (``-Z`` flag).
+
+        Examples
+        --------
+        >>> pane1 = window.active_pane
+        >>> pane2 = window.split()
+        >>> pane1_id, pane2_id = pane1.pane_id, pane2.pane_id
+        >>> pane1.swap(pane2)
+        >>> pane1.refresh()
+        >>> pane2.refresh()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if detach:
+            tmux_args += ("-d",)
+
+        if move_up:
+            tmux_args += ("-U",)
+
+        if move_down:
+            tmux_args += ("-D",)
+
+        if keep_zoom:
+            tmux_args += ("-Z",)
+
+        target_id = target.pane_id if isinstance(target, Pane) else target
+        tmux_args += ("-s", str(target_id))
+
+        proc = self.cmd("swap-pane", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def clear_history(self, *, clear_pane: bool | None = None) -> None:
         """Clear pane history buffer via ``$ tmux clear-history``.
 

src/libtmux/window.py

@@ -495,6 +495,48 @@ def select_layout(
 
         return self
 
+    def swap(
+        self,
+        target: str | Window,
+        *,
+        detach: bool | None = None,
+    ) -> None:
+        """Swap this window with another via ``$ tmux swap-window``.
+
+        Parameters
+        ----------
+        target : str or Window
+            Target window to swap with. Can be a window ID string or Window.
+        detach : bool, optional
+            Do not change the active window (``-d`` flag).
+
+        Examples
+        --------
+        >>> w1 = session.new_window(window_name='swap_a')
+        >>> w2 = session.new_window(window_name='swap_b')
+        >>> w1_idx = w1.window_index
+        >>> w2_idx = w2.window_index
+        >>> w1.swap(w2)
+        >>> w1.refresh()
+        >>> w2.refresh()
+        >>> w1.window_index == w2_idx
+        True
+        >>> w2.window_index == w1_idx
+        True
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if detach:
+            tmux_args += ("-d",)
+
+        target_id = target.window_id if isinstance(target, Window) else target
+        tmux_args += ("-s", str(target_id))
+
+        proc = self.cmd("swap-window", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def rename_window(self, new_name: str) -> Window:
         """Rename window.
 

tests/test_pane.py

@@ -740,6 +740,35 @@ def test_split_percentage_size_mutual_exclusion(session: Session) -> None:
         pane.split(size=10, percentage=50)
 
 
+def test_swap_pane(session: Session) -> None:
+    """Test Pane.swap() swaps two panes."""
+    window = session.new_window(window_name="test_swap_pane")
+    window.resize(height=40, width=80)
+    pane1 = window.active_pane
+    assert pane1 is not None
+    pane2 = pane1.split()
+
+    pane1_id = pane1.pane_id
+    pane2_id = pane2.pane_id
+
+    # Record initial indices
+    pane1.refresh()
+    pane2.refresh()
+    pane1_idx = pane1.pane_index
+    pane2_idx = pane2.pane_index
+
+    # Swap
+    pane1.swap(pane2)
+
+    # Verify indices swapped
+    pane1.refresh()
+    pane2.refresh()
+    assert pane1.pane_index == pane2_idx
+    assert pane2.pane_index == pane1_idx
+    assert pane1.pane_id == pane1_id
+    assert pane2.pane_id == pane2_id
+
+
 def test_clear_history(session: Session) -> None:
     """Test Pane.clear_history()."""
     env = shutil.which("env")

tests/test_window.py

@@ -821,6 +821,22 @@ def test_select_layout_mutual_exclusion(session: Session) -> None:
         window.select_layout("tiled", spread=True)
 
 
+def test_swap_window(session: Session) -> None:
+    """Test Window.swap() swaps two windows."""
+    w1 = session.new_window(window_name="swap_w1")
+    w2 = session.new_window(window_name="swap_w2")
+
+    w1_idx = w1.window_index
+    w2_idx = w2.window_index
+
+    w1.swap(w2)
+
+    w1.refresh()
+    w2.refresh()
+    assert w1.window_index == w2_idx
+    assert w2.window_index == w1_idx
+
+
 def test_move_window_kill_target(session: Session) -> None:
     """Test Window.move_window() with kill_target flag."""
     session.new_window(window_name="move_w1")