Pane(feat[paste_buffer]): add paste_buffer() wrapping tmux paste-buffer

why: paste-buffer is needed for programmatically inserting buffer content
into panes, completing the buffer management API.
what:
- Add Pane.paste_buffer() with buffer_name (-b), delete_after (-d),
  no_trailing_newline (-r), bracket (-p), separator (-s) parameters
- Add test verifying buffer content appears in pane after paste

Author: tony

src/libtmux/pane.py

@@ -1139,6 +1139,57 @@ def enter(self) -> Pane:
         self.cmd("send-keys", "Enter")
         return self
 
+    def paste_buffer(
+        self,
+        *,
+        buffer_name: str | None = None,
+        delete_after: bool | None = None,
+        no_trailing_newline: bool | None = None,
+        bracket: bool | None = None,
+        separator: str | None = None,
+    ) -> None:
+        """Paste a buffer into the pane via ``$ tmux paste-buffer``.
+
+        Parameters
+        ----------
+        buffer_name : str, optional
+            Name of the buffer to paste (``-b`` flag).
+        delete_after : bool, optional
+            Delete the buffer after pasting (``-d`` flag).
+        no_trailing_newline : bool, optional
+            Do not add a trailing newline (``-r`` flag).
+        bracket : bool, optional
+            Use bracketed paste mode (``-p`` flag).
+        separator : str, optional
+            Separator between lines (``-s`` flag).
+
+        Examples
+        --------
+        >>> server.set_buffer('pasted_text')
+        >>> pane.paste_buffer()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if delete_after:
+            tmux_args += ("-d",)
+
+        if no_trailing_newline:
+            tmux_args += ("-r",)
+
+        if bracket:
+            tmux_args += ("-p",)
+
+        if buffer_name is not None:
+            tmux_args += ("-b", buffer_name)
+
+        if separator is not None:
+            tmux_args += ("-s", separator)
+
+        proc = self.cmd("paste-buffer", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def pipe(
         self,
         command: str | None = None,

tests/test_pane.py

@@ -740,6 +740,32 @@ def test_split_percentage_size_mutual_exclusion(session: Session) -> None:
         pane.split(size=10, percentage=50)
 
 
+def test_paste_buffer(session: Session) -> None:
+    """Test Pane.paste_buffer() pastes buffer content into pane."""
+    env = shutil.which("env")
+    assert env is not None
+
+    window = session.new_window(
+        window_name="test_paste",
+        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)
+
+    # Set buffer and paste it
+    session.server.set_buffer("pasted_content", buffer_name="paste_test")
+    pane.paste_buffer(buffer_name="paste_test")
+
+    # Verify content appeared in pane
+    retry_until(
+        lambda: "pasted_content" in "\n".join(pane.capture_pane()),
+        3,
+        raises=True,
+    )
+
+
 def test_pipe_pane(session: Session, tmp_path: pathlib.Path) -> None:
     """Test Pane.pipe() pipes output to a file."""
     env = shutil.which("env")