Pane(feat[send_keys]): add reset, copy-mode, repeat, hex, format, client, key-name flags

why: send-keys has many useful flags (reset terminal, hex input, repeat count,
format expansion, copy-mode commands) that were not exposed in the Python API.
what:
- Add reset (-R), copy_mode_cmd (-X), repeat (-N), expand_formats (-F),
  hex_keys (-H), target_client (-c, 3.4+), key_name (-K, 3.4+) parameters
- Version-gate target_client and key_name with has_gte_version("3.4")
- Add SendKeysCase NamedTuple parametrized tests for all new flags

Author: tony

src/libtmux/pane.py

@@ -426,6 +426,13 @@ def send_keys(
         enter: bool | None = True,
         suppress_history: bool | None = False,
         literal: bool | None = False,
+        reset: bool | None = None,
+        copy_mode_cmd: str | None = None,
+        repeat: int | None = None,
+        expand_formats: bool | None = None,
+        hex_keys: bool | None = None,
+        target_client: str | None = None,
+        key_name: bool | None = None,
     ) -> None:
         r"""``$ tmux send-keys`` to the pane.
 
@@ -446,6 +453,29 @@ def send_keys(
                Default changed from True to False.
         literal : bool, optional
             Send keys literally, default False.
+        reset : bool, optional
+            Reset terminal state before sending keys (``-R`` flag).
+        copy_mode_cmd : str, optional
+            Send a command to copy mode instead of keys (``-X`` flag).
+            When set, *cmd* is ignored.
+        repeat : int, optional
+            Repeat count for the key (``-N`` flag).
+        expand_formats : bool, optional
+            Expand tmux format strings in keys (``-F`` flag).
+
+            .. versionadded:: 0.45
+        hex_keys : bool, optional
+            Send keys as hex values (``-H`` flag).
+
+            .. versionadded:: 0.45
+        target_client : str, optional
+            Specify a target client (``-c`` flag). Requires tmux 3.4+.
+
+            .. versionadded:: 0.45
+        key_name : bool, optional
+            Handle keys as key names (``-K`` flag). Requires tmux 3.4+.
+
+            .. versionadded:: 0.45
 
         Examples
         --------
@@ -463,14 +493,54 @@ def send_keys(
         Hello world
         $
         """
+        import warnings
+
+        from libtmux.common import has_gte_version
+
         prefix = " " if suppress_history else ""
 
+        tmux_args: tuple[str, ...] = ()
+
+        if reset:
+            tmux_args += ("-R",)
+
+        if expand_formats:
+            tmux_args += ("-F",)
+
+        if hex_keys:
+            tmux_args += ("-H",)
+
+        if key_name:
+            if has_gte_version("3.4", tmux_bin=self.server.tmux_bin):
+                tmux_args += ("-K",)
+            else:
+                warnings.warn(
+                    "key_name requires tmux 3.4+, ignoring",
+                    stacklevel=2,
+                )
+
         if literal:
-            self.cmd("send-keys", "-l", prefix + cmd)
+            tmux_args += ("-l",)
+
+        if repeat is not None:
+            tmux_args += ("-N", str(repeat))
+
+        if target_client is not None:
+            if has_gte_version("3.4", tmux_bin=self.server.tmux_bin):
+                tmux_args += ("-c", target_client)
+            else:
+                warnings.warn(
+                    "target_client requires tmux 3.4+, ignoring",
+                    stacklevel=2,
+                )
+
+        if copy_mode_cmd is not None:
+            tmux_args += ("-X",)
+            self.cmd("send-keys", *tmux_args, copy_mode_cmd)
         else:
-            self.cmd("send-keys", prefix + cmd)
+            self.cmd("send-keys", *tmux_args, prefix + cmd)
 
-        if enter:
+        if enter and copy_mode_cmd is None:
             self.enter()
 
     @t.overload

tests/test_pane.py

@@ -9,6 +9,7 @@
 
 import pytest
 
+from libtmux.common import has_gte_version
 from libtmux.constants import PaneDirection, ResizeAdjustmentDirection
 from libtmux.test.retry import retry_until
 
@@ -443,3 +444,103 @@ def test_split_start_directory_pathlib(
     actual_path = str(pathlib.Path(new_pane.pane_current_path).resolve())
     expected_path = str(user_path.resolve())
     assert actual_path == expected_path
+
+
+class SendKeysCase(t.NamedTuple):
+    """Test case for send_keys() flag variations."""
+
+    test_id: str
+    key: str
+    kwargs: dict[str, t.Any]
+    expected_in_capture: str | None
+    not_expected_in_capture: str | None
+    min_tmux_version: str | None
+
+
+SEND_KEYS_CASES: list[SendKeysCase] = [
+    SendKeysCase(
+        test_id="reset_terminal",
+        key="",
+        kwargs={"reset": True, "enter": False},
+        expected_in_capture=None,
+        not_expected_in_capture=None,
+        min_tmux_version=None,
+    ),
+    SendKeysCase(
+        test_id="repeat_count",
+        key="a",
+        kwargs={"repeat": 3, "literal": True, "enter": False},
+        expected_in_capture="aaa",
+        not_expected_in_capture=None,
+        min_tmux_version=None,
+    ),
+    SendKeysCase(
+        test_id="hex_key_A",
+        key="41",
+        kwargs={"hex_keys": True, "enter": False},
+        expected_in_capture="A",
+        not_expected_in_capture=None,
+        min_tmux_version=None,
+    ),
+    SendKeysCase(
+        test_id="expand_formats",
+        key="a",
+        kwargs={"expand_formats": True, "repeat": 2, "enter": False},
+        expected_in_capture="aa",
+        not_expected_in_capture=None,
+        min_tmux_version=None,
+    ),
+    SendKeysCase(
+        test_id="key_name_flag",
+        key="a",
+        kwargs={"key_name": True, "enter": False},
+        expected_in_capture=None,
+        not_expected_in_capture=None,
+        min_tmux_version="3.4",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(SendKeysCase._fields),
+    SEND_KEYS_CASES,
+    ids=[c.test_id for c in SEND_KEYS_CASES],
+)
+def test_send_keys_flags(
+    test_id: str,
+    key: str,
+    kwargs: dict[str, t.Any],
+    expected_in_capture: str | None,
+    not_expected_in_capture: str | None,
+    min_tmux_version: str | None,
+    session: Session,
+) -> None:
+    """Test send_keys() with various flag combinations."""
+    if min_tmux_version and not has_gte_version(min_tmux_version):
+        pytest.skip(f"Requires tmux {min_tmux_version}+")
+
+    env = shutil.which("env")
+    assert env is not None, "Cannot find usable `env` in PATH."
+
+    window = session.new_window(
+        window_name=f"sk_{test_id[:15]}",
+        window_shell=f"{env} PS1='$ ' sh",
+    )
+    pane = window.active_pane
+    assert pane is not None
+
+    retry_until(lambda: "$" in "\n".join(pane.capture_pane()), 2, raises=True)
+
+    pane.send_keys(key, **kwargs)
+
+    if expected_in_capture is not None:
+        retry_until(
+            lambda: expected_in_capture in "\n".join(pane.capture_pane()),
+            3,
+            raises=True,
+        )
+
+    if not_expected_in_capture is not None:
+        # Give a brief moment then verify absence
+        contents = "\n".join(pane.capture_pane())
+        assert not_expected_in_capture not in contents