Increase tmux coverage: Client, typed fields, Native filtering

CHANGES

@@ -45,10 +45,222 @@ $ uvx --from 'libtmux' --prerelease allow python
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+libtmux 0.57.0 broadens tmux support around attached clients, tmux-native
+filtering, and format-token fields. {class}`~libtmux.Client` gives callers a
+typed object for attached terminals, `search_*()` methods let tmux return only
+matching sessions, windows, and panes, and more tmux format tokens are exposed
+as typed attributes. {exc}`~libtmux.exc.LibTmuxException` now records which
+tmux subcommand failed, making command errors easier to handle downstream.
+
+### Breaking changes
+
+#### `LibTmuxException` string form gains a subcommand prefix (#672)
+
+When {exc}`~libtmux.exc.LibTmuxException` is raised from a libtmux method,
+``str(exc)`` now begins with the originating tmux subcommand name followed
+by ``": "``. For example, an error from
+{meth}`~libtmux.Session.last_window` used to render as ``"can't find
+window"`` and now renders as ``"last-window: can't find window"``.
+
+``exc.args[0]`` still carries the original tmux error text, and the new
+{attr}`~libtmux.exc.LibTmuxException.subcommand` attribute exposes
+the tmux subcommand name as a separate field.
+{func}`~libtmux.common.raise_if_stderr` is the shared helper that
+populates both.
+
+The error-payload *type* changed: ``exc.args[0]`` is now ``str``,
+joined with ``"\n"`` when tmux emitted multiple stderr lines.
+Previously it was ``list[str]``.
+
+This is a serialization-format change: code that pattern-matches on
+``str(exc)`` exactly, anchors a regex with ``^`` against the old
+shape, or indexes ``exc.args[0]`` element-by-element will no longer
+match.
+
+```python
+# Before
+try:
+    session.last_window()
+except LibTmuxException as exc:
+    if str(exc) == "can't find window":
+        ...
+
+# After — dispatch on the typed attribute
+try:
+    session.last_window()
+except LibTmuxException as exc:
+    if exc.subcommand == "last-window":
+        ...
+
+# Or — match against the original tmux error text without the prefix
+try:
+    session.last_window()
+except LibTmuxException as exc:
+    if exc.args and exc.args[0] == "can't find window":
+        ...
+```
+
+Substring matches (``"can't find" in str(exc)``) and unanchored
+``re.search`` patterns continue to work unchanged.
+
+#### `Server.sessions`, `Server.clients`, and `Server.search_sessions` raise on tmux errors (#672)
+
+Previously, a tmux command failure under
+{attr}`~libtmux.Server.sessions`, {attr}`~libtmux.Server.clients`, or
+{meth}`~libtmux.Server.search_sessions` could return an empty
+{class}`~libtmux._internal.query_list.QueryList` indistinguishable
+from "no sessions / no clients attached" or "filter matched nothing".
+Those accessors now let {exc}`~libtmux.exc.LibTmuxException` propagate
+for real tmux failures.
+
+Genuine empty results — a server with no attached clients, or a
+filter that matched zero sessions — still return an empty
+``QueryList``. A missing or not-yet-started tmux server is also still
+treated as an empty result, preserving the historic contract that a fresh
+{class}`~libtmux.Server` can be safely introspected before its daemon is
+up. Other tmux errors, such as socket permission failures or unsupported
+flags, now surface.
+
+```python
+# Before — silent on tmux failure
+if not server.clients:
+    log("no clients")  # also runs when tmux itself crashed
+
+# After — distinguish the two cases
+try:
+    clients = server.clients
+except LibTmuxException as exc:
+    log(f"list-clients failed: {exc}")
+else:
+    if not clients:
+        log("no clients")
+```
+
+### What's new
+
+#### `Client` object and `Server.clients` accessor (#672)
+
+New {class}`~libtmux.Client` and {attr}`~libtmux.Server.clients` support tmux's
+attached-client model directly. Reads like ``client.client_readonly`` and
+``client.client_session`` work on the client object without dropping down to
+{meth}`~libtmux.Server.cmd`.
+
+Note that ``client.session_id`` / ``client.window_id`` / ``client.pane_id``
+reflect the client's attached view when the object was read —
+{meth}`~libtmux.Client.refresh` re-reads them after the client switches focus.
+``client.client_name`` is the client's stable identifier.
+
+For typed access to the live attachment, use
+{attr}`~libtmux.Client.attached_session`,
+{attr}`~libtmux.Client.attached_window`, and
+{attr}`~libtmux.Client.attached_pane`. Each property re-reads the
+client from ``list-clients`` before resolving; if tmux no longer
+reports that ``client_name``, such as after the client detaches, the
+property returns ``None``. Otherwise, the returned
+{class}`~libtmux.Session` / {class}`~libtmux.Window` /
+{class}`~libtmux.Pane` reflects where the client is attached *now*,
+not where it was when the {class}`~libtmux.Client` was constructed.
+Direct {meth}`~libtmux.Client.refresh` and
+{meth}`~libtmux.Client.from_client_name` calls still surface missing
+client lookup errors.
+
+{attr}`~libtmux.Client.attached_pane` follows the attached session's current
+window. That can differ from the per-client active pane set by
+``select-pane -P``; see {attr}`~libtmux.Client.attached_pane` for the exact
+behavior.
+
+#### `Server.display_message` and `Window.display_message` (#672)
+
+{meth}`~libtmux.Server.display_message` and
+{meth}`~libtmux.Window.display_message` join the existing
+{meth}`~libtmux.Pane.display_message`. Server reads like
+``#{version}`` and ``#{socket_path}`` work without a pane handle;
+window reads (``#{window_zoomed_flag}``, ``#{window_active_clients_list}``)
+auto-bind to the window's id.
+
+All three wrappers surface tmux stderr via :func:`warnings.warn`
+rather than dropping it silently. tmux uses stderr for both genuine
+errors and informational messages on some versions, so the wrappers
+warn rather than raise; callers that want to escalate can wrap the
+call in :func:`warnings.catch_warnings` with
+``filterwarnings("error")``. See {doc}`migration` for the escalation
+pattern.
+
+#### tmux-native filtering with `search_*()` (#672)
+
+{meth}`~libtmux.Server.search_panes`,
+{meth}`~libtmux.Server.search_windows`,
+{meth}`~libtmux.Server.search_sessions`, and the Session/Window
+analogues take a ``filter=`` kwarg routed to tmux's ``-f`` flag. tmux
+evaluates the expression and returns only matching objects.
+
+Caveat: tmux silently expands a malformed filter expression to empty, which
+it treats as false — a typo looks identical to "no matches". Verify filter
+syntax against the FORMATS section of ``tmux(1)``.
+
+#### `Pane.send_keys(cmd=None, …)` flag-only invocation (#672)
+
+{meth}`~libtmux.Pane.send_keys` accepts ``cmd=None`` together with
+``reset=True`` or ``repeat=N`` to invoke tmux's flag-only
+``send-keys -R`` / ``send-keys -N <n>`` form without any trailing
+key argument.
+
+#### `Server.list_buffers(format_string=, filter=)` (#672)
+
+{meth}`~libtmux.Server.list_buffers` gains ``format_string`` (``-F``)
+and ``filter`` (``-f``) kwargs. Callers can ask tmux to return selected
+fields (e.g. ``"#{buffer_name}"``) or only buffers matching an expression —
+same bad-filter caveat as the ``search_*`` methods.
+
+#### `Server.run_shell(cwd=, show_stderr=)` (#672)
+
+{meth}`~libtmux.Server.run_shell` gains ``cwd`` (``-c``) to set the
+shell command's working directory and ``show_stderr`` (``-E``) to
+merge the command's stderr into the captured output. Both kwargs are
+version-gated; older tmux warns and ignores the flag instead of
+erroring.
+
+#### `Pane.capture_pane(pending=True)` (#672)
+
+{meth}`~libtmux.Pane.capture_pane` gains a ``pending`` kwarg that
+returns bytes tmux has read from the pane but not yet committed to
+the terminal — useful for diagnosing programs whose output stalls
+mid-sequence.
+
+#### More format-token fields on tmux objects (#672)
+
+libtmux now asks each ``list-*`` subcommand for the format tokens that make
+sense for that object and tmux version. Tokens the running tmux does not
+support stay ``None`` instead of making the listing fail.
+
+{class}`~libtmux.Pane`, {class}`~libtmux.Window`,
+{class}`~libtmux.Session`, and {class}`~libtmux.Client` expose more typed
+attributes for pane state (``pane_dead``, ``pane_in_mode``, ``pane_marked``,
+``pane_synchronized``, ``pane_path``, ``pane_pipe``), window state
+(``window_zoomed_flag``, ``window_silence_flag``, ``window_flags``), session
+state (``session_marked``), and client state (``client_session``,
+``client_readonly``, ``client_termtype``). Some fields describe the active
+child object tmux reports with the row: for example, ``session.pane_id`` is
+the active pane in the session's current window, not a separate "session
+pane." See {ref}`format-tokens` for details.
+
+### Fixes
+
+- {meth}`~libtmux.Pane.reset` now clears pane scrollback. In 0.56.0
+  the history clear silently no-op'd, leaving the scrollback intact
+  (#650).
+
+### Documentation
+
+- New API page: {doc}`api/libtmux.client`.
+- New {ref}`format-tokens` topic explains why some fields describe an active
+  child object, such as ``session.pane_id`` reflecting the active pane in the
+  session's current window (#672).
+
 ## libtmux 0.56.0 (2026-05-10)
 
 libtmux 0.56.0 is the tmux command-parity release. It adds more than
-50 wrappers across {class}`~libtmux.Server`, {class}`~libtmux.Session`,
+50 commands across {class}`~libtmux.Server`, {class}`~libtmux.Session`,
 {class}`~libtmux.Window`, and {class}`~libtmux.Pane`, filling in many
 commands that previously required raw {meth}`~libtmux.Server.cmd` calls.
 It also adds attached-client test support so interactive tmux commands can be
@@ -58,7 +270,7 @@ covered in headless test suites.
 
 #### Interactive tmux commands are now scriptable (#653)
 
-libtmux now exposes Python wrappers for tmux commands that normally depend on
+libtmux now exposes Python commands for tmux that normally depend on
 an attached client: {meth}`~libtmux.Pane.display_popup`,
 {meth}`~libtmux.Server.display_menu`,
 {meth}`~libtmux.Server.command_prompt`,
@@ -80,7 +292,7 @@ The `detach-client` API is split by the same scopes tmux actually honors:
 `tmux detach-client -a [-t <keep>]`. This keeps each method to one tmux flag
 group and one subprocess call.
 
-#### tmux buffer I/O has first-class wrappers (#653)
+#### tmux buffer I/O has first-class support (#653)
 
 Named tmux buffers can now be used from libtmux without hand-built commands.
 {meth}`~libtmux.Server.set_buffer`,
@@ -94,7 +306,7 @@ inter-process handoff workflows.
 
 #### Server commands cover key bindings, clients, shell execution, and access (#653)
 
-{class}`~libtmux.Server` gains wrappers for key-binding inspection and mutation
+{class}`~libtmux.Server` gains support for key-binding inspection and mutation
 ({meth}`~libtmux.Server.bind_key`,
 {meth}`~libtmux.Server.unbind_key`,
 {meth}`~libtmux.Server.list_keys`,
@@ -137,7 +349,7 @@ Navigation helpers fill in the surrounding topology:
 {meth}`~libtmux.Session.next_window`, and
 {meth}`~libtmux.Session.previous_window`.
 
-#### Existing wrappers expose more tmux flags (#653)
+#### Improvements (#653)
 
 Several established methods now surface tmux flags that were previously only
 available by dropping to raw commands. Highlights include
@@ -196,7 +408,7 @@ old hardcoded socket paths. Fixes #664.
 
 #### tmux 3.7 is within the known-version range (#653)
 
-{data}`~libtmux.common.TMUX_MAX_VERSION` is now `"3.7"`, enabling wrappers and
+{data}`~libtmux.common.TMUX_MAX_VERSION` is now `"3.7"`, enabling support and
 tests for version-gated tmux 3.7 flags such as
 {meth}`~libtmux.Server.command_prompt` `bspace_exit` and
 {meth}`~libtmux.Server.show_messages` `terminals` / `jobs`. Installations on
@@ -343,7 +555,7 @@ surface from Make to Just.
 
 ### Fixes
 
-#### `Server.new_session()` no longer races its own hydration query (#625)
+#### `Server.new_session()` no longer races its own initialization query (#625)
 
 {meth}`~libtmux.Server.new_session` now parses all required session fields from
 the `tmux new-session -P` output instead of creating the session and then