Server(feat): add lock_server, lock_client, refresh_client, suspend_client, server_access

why: Complete coverage of remaining server-level commands that work with
a control-mode client.
what:
- Add Server.lock_server() wrapping lock-server
- Add Server.lock_client() wrapping lock-client with target_client (-t)
- Add Server.refresh_client() wrapping refresh-client with target_client (-t)
- Add Server.suspend_client() wrapping suspend-client with target_client (-t)
- Add Server.server_access() wrapping server-access with allow (-a),
  deny (-d), list_access (-l) parameters
- All client-dependent tests use ControlMode context manager

Author: tony

src/libtmux/server.py

@@ -673,6 +673,145 @@ def list_commands(self, *, command_name: str | None = None) -> list[str]:
 
         return proc.stdout
 
+    def lock_server(self) -> None:
+        """Lock the tmux server via ``$ tmux lock-server``.
+
+        Requires an attached client.
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     server.lock_server()
+        """
+        proc = self.cmd("lock-server")
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def server_access(
+        self,
+        *,
+        allow: str | None = None,
+        deny: str | None = None,
+        list_access: bool | None = None,
+    ) -> list[str] | None:
+        """Manage server access control via ``$ tmux server-access``.
+
+        Parameters
+        ----------
+        allow : str, optional
+            Allow a user (``-a`` flag).
+        deny : str, optional
+            Deny a user (``-d`` flag).
+        list_access : bool, optional
+            List access rules (``-l`` flag).
+
+        Returns
+        -------
+        list[str] | None
+            Access list when *list_access* is True, None otherwise.
+
+        Examples
+        --------
+        >>> result = server.server_access(list_access=True)
+        >>> isinstance(result, list)
+        True
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if allow is not None:
+            tmux_args += ("-a", allow)
+
+        if deny is not None:
+            tmux_args += ("-d", deny)
+
+        if list_access:
+            tmux_args += ("-l",)
+
+        proc = self.cmd("server-access", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        if list_access:
+            return proc.stdout
+        return None
+
+    def refresh_client(self, *, target_client: str | None = None) -> None:
+        """Refresh a client's display via ``$ tmux refresh-client``.
+
+        Requires an attached client.
+
+        Parameters
+        ----------
+        target_client : str, optional
+            Target client (``-t`` flag).
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     server.refresh_client()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if target_client is not None:
+            tmux_args += ("-t", target_client)
+
+        proc = self.cmd("refresh-client", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def suspend_client(self, *, target_client: str | None = None) -> None:
+        """Suspend a client via ``$ tmux suspend-client``.
+
+        Requires an attached client.
+
+        Parameters
+        ----------
+        target_client : str, optional
+            Target client (``-t`` flag).
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     server.suspend_client()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if target_client is not None:
+            tmux_args += ("-t", target_client)
+
+        proc = self.cmd("suspend-client", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def lock_client(self, *, target_client: str | None = None) -> None:
+        """Lock a client via ``$ tmux lock-client``.
+
+        Requires an attached client.
+
+        Parameters
+        ----------
+        target_client : str, optional
+            Target client (``-t`` flag).
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     server.lock_client()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if target_client is not None:
+            tmux_args += ("-t", target_client)
+
+        proc = self.cmd("lock-client", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def start_server(self) -> None:
         """Start the tmux server if not already running.
 

tests/test_server.py

@@ -461,6 +461,49 @@ def test_tmux_bin_invalid_path_raise_if_dead() -> None:
         s.raise_if_dead()
 
 
+def test_lock_server(
+    control_mode: t.Callable[..., t.Any],
+    server: Server,
+) -> None:
+    """Test Server.lock_server() runs without error."""
+    with control_mode():
+        server.lock_server()
+
+
+def test_lock_client(
+    control_mode: t.Callable[..., t.Any],
+    server: Server,
+) -> None:
+    """Test Server.lock_client() runs without error."""
+    with control_mode():
+        server.lock_client()
+
+
+def test_refresh_client(
+    control_mode: t.Callable[..., t.Any],
+    server: Server,
+) -> None:
+    """Test Server.refresh_client() runs without error."""
+    with control_mode():
+        server.refresh_client()
+
+
+def test_suspend_client(
+    control_mode: t.Callable[..., t.Any],
+    server: Server,
+) -> None:
+    """Test Server.suspend_client() runs without error."""
+    with control_mode():
+        server.suspend_client()
+
+
+def test_server_access_list(server: Server) -> None:
+    """Test Server.server_access() list mode."""
+    server.new_session(session_name="access_test")
+    result = server.server_access(list_access=True)
+    assert isinstance(result, list)
+
+
 def test_start_server(server: Server) -> None:
     """Test Server.start_server() runs without error."""
     server.new_session(session_name="startsvr_test")