Pane(fix[swap]): make target optional when move_up/move_down is set

why: pane.swap(move_up=True) raised TypeError because target was
     positionally required, contradicting the docstring claim that
     move_up/move_down "overrides target". The body also emitted
     -s <target> unconditionally even with -U/-D.

what:
- Make target optional with default None
- Raise LibTmuxException for missing/conflicting flag combinations
  (no flags, both move flags, target combined with a move flag)
- Skip -s <target> when target is None
- Update docstring: "Mutually exclusive with target" + versionchanged 0.56
- Add tests covering move_up/move_down happy path and three invalid
  argument combinations

Author: tony

src/libtmux/pane.py

@@ -2030,7 +2030,7 @@ def break_pane(
 
     def swap(
         self,
-        target: str | Pane,
+        target: str | Pane | None = None,
         *,
         detach: bool | None = None,
         move_up: bool | None = None,
@@ -2041,14 +2041,21 @@ def swap(
 
         Parameters
         ----------
-        target : str or Pane
+        target : str or Pane, optional
             Target pane to swap with. Can be a pane ID string or Pane object.
+            Mutually exclusive with *move_up* / *move_down*.
+
+            .. versionchanged:: 0.56
+               Now optional; required only when *move_up* / *move_down* are
+               not set.
         detach : bool, optional
             Do not change the active pane (``-d`` flag).
         move_up : bool, optional
-            Swap with the pane above (``-U`` flag). Overrides *target*.
+            Swap with the pane above (``-U`` flag). Mutually exclusive with
+            *target* and *move_down*.
         move_down : bool, optional
-            Swap with the pane below (``-D`` flag). Overrides *target*.
+            Swap with the pane below (``-D`` flag). Mutually exclusive with
+            *target* and *move_up*.
         keep_zoom : bool, optional
             Keep the window zoomed if it was zoomed (``-Z`` flag).
 
@@ -2061,6 +2068,18 @@ def swap(
         >>> pane1.refresh()
         >>> pane2.refresh()
         """
+        if move_up and move_down:
+            msg = "move_up and move_down are mutually exclusive"
+            raise exc.LibTmuxException(msg)
+
+        if target is not None and (move_up or move_down):
+            msg = "target is mutually exclusive with move_up/move_down"
+            raise exc.LibTmuxException(msg)
+
+        if target is None and not move_up and not move_down:
+            msg = "swap requires target or move_up=True or move_down=True"
+            raise exc.LibTmuxException(msg)
+
         tmux_args: tuple[str, ...] = ()
 
         if detach:
@@ -2075,8 +2094,9 @@ def swap(
         if keep_zoom:
             tmux_args += ("-Z",)
 
-        target_id = target.pane_id if isinstance(target, Pane) else target
-        tmux_args += ("-s", str(target_id))
+        if target is not None:
+            target_id = target.pane_id if isinstance(target, Pane) else target
+            tmux_args += ("-s", str(target_id))
 
         proc = self.cmd("swap-pane", *tmux_args)
 

tests/test_pane.py

@@ -9,6 +9,7 @@
 
 import pytest
 
+from libtmux import exc
 from libtmux.common import has_gte_version
 from libtmux.constants import PaneDirection, ResizeAdjustmentDirection
 from libtmux.test.retry import retry_until
@@ -1180,6 +1181,54 @@ def test_swap_pane(session: Session) -> None:
     assert pane2.pane_id == pane2_id
 
 
+def test_swap_pane_move_up_down(session: Session) -> None:
+    """Pane.swap(move_up=True) / (move_down=True) work without a target."""
+    window = session.new_window(window_name="test_swap_move")
+    window.resize(height=40, width=80)
+    pane1 = window.active_pane
+    assert pane1 is not None
+    pane2 = pane1.split()
+
+    pane1.refresh()
+    pane2.refresh()
+    pane1_idx = pane1.pane_index
+    pane2_idx = pane2.pane_index
+
+    # move_down on pane1: swap with the next pane (pane2)
+    pane1.swap(move_down=True)
+    pane1.refresh()
+    pane2.refresh()
+    assert pane1.pane_index == pane2_idx
+    assert pane2.pane_index == pane1_idx
+
+    # move_up on pane1: swap back to the original layout
+    pane1.swap(move_up=True)
+    pane1.refresh()
+    pane2.refresh()
+    assert pane1.pane_index == pane1_idx
+    assert pane2.pane_index == pane2_idx
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "match"),
+    [
+        ({}, "target or move_up"),
+        ({"move_up": True, "move_down": True}, "mutually exclusive"),
+        ({"move_up": True, "target": "%0"}, "mutually exclusive"),
+    ],
+)
+def test_swap_pane_invalid_args(
+    session: Session,
+    kwargs: dict[str, t.Any],
+    match: str,
+) -> None:
+    """Pane.swap() rejects missing or conflicting arguments."""
+    pane = session.active_window.active_pane
+    assert pane is not None
+    with pytest.raises(exc.LibTmuxException, match=match):
+        pane.swap(**kwargs)
+
+
 def test_clear_history(session: Session) -> None:
     """Test Pane.clear_history()."""
     env = shutil.which("env")