Pane(feat[display_message]): add format, verbose, delay, notify, list, and style flags

why: display-message supports many useful flags for format queries and output
control that were not exposed in the Python API.
what:
- Add format_string (-F), all_formats (-a), verbose (-v), no_expand (-I),
  target_client (-c), delay (-d), notify (-N), list_formats (-l, 3.4+),
  no_style (-C, 3.6+) parameters
- Version-gate list_formats and no_style with has_gte_version
- Fix cmd argument handling: only pass when non-empty
- Add DisplayMessageCase NamedTuple parametrized tests

Author: tony

src/libtmux/pane.py

@@ -548,15 +548,49 @@ def display_message(
         self,
         cmd: str,
         get_text: t.Literal[True],
+        *,
+        format_string: str | None = ...,
+        all_formats: bool | None = ...,
+        verbose: bool | None = ...,
+        no_expand: bool | None = ...,
+        target_client: str | None = ...,
+        delay: int | None = ...,
+        notify: bool | None = ...,
+        list_formats: bool | None = ...,
+        no_style: bool | None = ...,
     ) -> list[str]: ...
 
     @t.overload
-    def display_message(self, cmd: str, get_text: t.Literal[False]) -> None: ...
+    def display_message(
+        self,
+        cmd: str,
+        get_text: t.Literal[False] = ...,
+        *,
+        format_string: str | None = ...,
+        all_formats: bool | None = ...,
+        verbose: bool | None = ...,
+        no_expand: bool | None = ...,
+        target_client: str | None = ...,
+        delay: int | None = ...,
+        notify: bool | None = ...,
+        list_formats: bool | None = ...,
+        no_style: bool | None = ...,
+    ) -> None: ...
 
     def display_message(
         self,
         cmd: str,
         get_text: bool = False,
+        *,
+        format_string: str | None = None,
+        all_formats: bool | None = None,
+        verbose: bool | None = None,
+        no_expand: bool | None = None,
+        target_client: str | None = None,
+        delay: int | None = None,
+        notify: bool | None = None,
+        list_formats: bool | None = None,
+        no_style: bool | None = None,
     ) -> list[str] | None:
         """Display message to pane.
 
@@ -569,16 +603,90 @@ def display_message(
         get_text : bool, optional
             Returns only text without displaying a message in
             target-client status line.
+        format_string : str, optional
+            Format string for output (``-F`` flag).
+        all_formats : bool, optional
+            List all format variables (``-a`` flag).
+        verbose : bool, optional
+            Show format variable types (``-v`` flag).
+        no_expand : bool, optional
+            Suppress format expansion (``-I`` flag).
+        target_client : str, optional
+            Target client (``-c`` flag).
+        delay : int, optional
+            Display time in milliseconds (``-d`` flag).
+        notify : bool, optional
+            Do not wait for input (``-N`` flag).
+        list_formats : bool, optional
+            List format variables (``-l`` flag). Requires tmux 3.4+.
+
+            .. versionadded:: 0.45
+        no_style : bool, optional
+            Suppress style output (``-C`` flag). Requires tmux 3.6+.
+
+            .. versionadded:: 0.45
 
         Returns
         -------
         list[str] | None
             Message output if get_text is True, otherwise None.
         """
+        import warnings
+
+        from libtmux.common import has_gte_version
+
+        tmux_args: tuple[str, ...] = ()
+
+        if get_text:
+            tmux_args += ("-p",)
+
+        if all_formats:
+            tmux_args += ("-a",)
+
+        if verbose:
+            tmux_args += ("-v",)
+
+        if no_expand:
+            tmux_args += ("-I",)
+
+        if notify:
+            tmux_args += ("-N",)
+
+        if list_formats:
+            if has_gte_version("3.4", tmux_bin=self.server.tmux_bin):
+                tmux_args += ("-l",)
+            else:
+                warnings.warn(
+                    "list_formats requires tmux 3.4+, ignoring",
+                    stacklevel=2,
+                )
+
+        if no_style:
+            if has_gte_version("3.6", tmux_bin=self.server.tmux_bin):
+                tmux_args += ("-C",)
+            else:
+                warnings.warn(
+                    "no_style requires tmux 3.6+, ignoring",
+                    stacklevel=2,
+                )
+
+        if target_client is not None:
+            tmux_args += ("-c", target_client)
+
+        if delay is not None:
+            tmux_args += ("-d", str(delay))
+
+        if format_string is not None:
+            tmux_args += ("-F", format_string)
+
+        if cmd:
+            tmux_args += (cmd,)
+
+        proc = self.cmd("display-message", *tmux_args)
+
         if get_text:
-            return self.cmd("display-message", "-p", cmd).stdout
+            return proc.stdout
 
-        self.cmd("display-message", cmd)
         return None
 
     def kill(

tests/test_pane.py

@@ -642,3 +642,73 @@ def test_select_pane_disable_enable_input(session: Session) -> None:
         3,
         raises=True,
     )
+
+
+class DisplayMessageCase(t.NamedTuple):
+    """Test case for display_message() flag variations."""
+
+    test_id: str
+    cmd: str
+    kwargs: dict[str, t.Any]
+    expected_in_output: str | None
+    min_tmux_version: str | None
+
+
+DISPLAY_MESSAGE_CASES: list[DisplayMessageCase] = [
+    DisplayMessageCase(
+        test_id="format_string",
+        cmd="",
+        kwargs={"get_text": True, "format_string": "#{pane_id}"},
+        expected_in_output="%",
+        min_tmux_version=None,
+    ),
+    DisplayMessageCase(
+        test_id="all_formats",
+        cmd="",
+        kwargs={"get_text": True, "all_formats": True},
+        expected_in_output="session_name",
+        min_tmux_version=None,
+    ),
+    DisplayMessageCase(
+        test_id="verbose",
+        cmd="",
+        kwargs={"get_text": True, "verbose": True, "all_formats": True},
+        expected_in_output="session_name",
+        min_tmux_version=None,
+    ),
+    DisplayMessageCase(
+        test_id="list_formats",
+        cmd="",
+        kwargs={"get_text": True, "list_formats": True},
+        expected_in_output=None,
+        min_tmux_version="3.4",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(DisplayMessageCase._fields),
+    DISPLAY_MESSAGE_CASES,
+    ids=[c.test_id for c in DISPLAY_MESSAGE_CASES],
+)
+def test_display_message_flags(
+    test_id: str,
+    cmd: str,
+    kwargs: dict[str, t.Any],
+    expected_in_output: str | None,
+    min_tmux_version: str | None,
+    session: Session,
+) -> None:
+    """Test display_message() with various flag combinations."""
+    if min_tmux_version and not has_gte_version(min_tmux_version):
+        pytest.skip(f"Requires tmux {min_tmux_version}+")
+
+    pane = session.active_window.active_pane
+    assert pane is not None
+
+    result = pane.display_message(cmd, **kwargs)
+
+    if expected_in_output is not None:
+        assert result is not None
+        output = "\n".join(result)
+        assert expected_in_output in output