neo(feat[scope-aware]): Make get_output_format scope+version aware

tony · tony · commit c3f1aaef12bb · 2026-05-16T13:50:57.000-05:00
why: PR #672's CI matrix on tmux 3.2a crashed when the -F template included tokens that don't apply to the calling list-* subcommand or don't exist in the running tmux's format_table. The empirical crashers were 11 client_* tokens queried during list-windows (no client context) and several post-3.2a tokens that contributed cumulative risk. what: - src/libtmux/neo.py: - Add SCOPES_BY_LIST_CMD dict mapping each list-* to the set of token scopes its format engine can resolve (e.g. list-windows reaches universal + session + window; list-clients reaches universal + session + client). - Add FIELD_VERSION dict (initially empty) mapping field name → min tmux version; fields absent from the dict default to the project's floor (3.2a). - Add _SCOPE_PREFIXES table and _token_scope() helper that derive a token's scope from its name prefix (pane_*, window_*, session_*, client_*, buffer_*, etc.). Runtime-only tokens (mouse_*, cursor_*, selection_*, copy_cursor_*, popup_*) resolve to "event" and are excluded from all list-* templates. - Add _UNIVERSAL_TOKENS frozenset for cross-scope tokens without a scope prefix (pid, version, host, host_short, socket_path, etc.). - Add _normalize_tmux_version() helper that treats tmux master as a sentinel "newer than any tagged release" for comparison. - Rewrite get_output_format() to take (list_cmd, tmux_version) and filter the field set accordingly. Cached via @functools.cache on the small number of (list_cmd, version) combinations a process sees. - Rewrite parse_output() to take the same args so it reads the same filtered field order. - Thread the live tmux version through fetch_objs() via get_version(server.tmux_bin) before calling get_output_format(), pass through to parse_output() per line. - Doctests on the helpers and on get_output_format / parse_output demonstrate the new contracts. No Obj field changes in this commit. The 27 fields rolled back during the prior CI bisect remain absent — they re-enter in follow-up commits that exercise the new scope/version gating.
diff --git a/src/libtmux/neo.py b/src/libtmux/neo.py
@@ -10,7 +10,8 @@
 from collections.abc import Iterable
 
 from libtmux import exc
-from libtmux.common import raise_if_stderr, tmux_cmd
+from libtmux._compat import LooseVersion
+from libtmux.common import get_version, raise_if_stderr, tmux_cmd
 from libtmux.formats import FORMAT_SEPARATOR
 
 if t.TYPE_CHECKING:
@@ -26,6 +27,134 @@
 OutputsRaw = list[OutputRaw]
 
 
+SCOPES_BY_LIST_CMD: dict[str, frozenset[str]] = {
+    "list-sessions": frozenset({"universal", "session"}),
+    "list-windows": frozenset({"universal", "session", "window"}),
+    "list-panes": frozenset({"universal", "session", "window", "pane"}),
+    "list-clients": frozenset({"universal", "session", "client"}),
+}
+"""Format-token scopes a given tmux ``list-*`` subcommand can resolve.
+
+A token whose scope is in the set is safe to include in that subcommand's
+``-F`` template. A token whose scope is *outside* the set may be unknown to
+the format engine in that context, or in older tmux releases trigger a
+server-side fault — exclude it from the format string.
+"""
+
+
+FIELD_VERSION: dict[str, str] = {}
+"""Minimum tmux version that registers each format token.
+
+Field names absent from this dict default to ``"3.2a"`` (always-safe within
+the supported tmux range). Entries here represent tokens added after 3.2a
+that need explicit gating to keep the ``-F`` template compatible with older
+tmux versions.
+"""
+
+
+# Field-name prefixes that map to a single format-token scope. Resolved by
+# :func:`_token_scope`. Order matters: longer prefixes win (e.g.
+# ``copy_cursor_`` is a runtime token, not a generic ``copy_`` one).
+_SCOPE_PREFIXES: tuple[tuple[str, str], ...] = (
+    ("copy_cursor_", "event"),
+    ("pane_", "pane"),
+    ("window_", "window"),
+    ("session_", "session"),
+    ("client_", "client"),
+    ("buffer_", "buffer"),
+    ("mouse_", "event"),
+    ("cursor_", "event"),
+    ("selection_", "event"),
+    ("scroll_", "event"),
+    ("popup_", "event"),
+)
+
+# Standalone tokens not captured by the prefix table.
+_UNIVERSAL_TOKENS: frozenset[str] = frozenset(
+    {
+        "active_window_index",
+        "alternate_on",
+        "alternate_saved_x",
+        "alternate_saved_y",
+        "command_list_alias",
+        "command_list_name",
+        "command_list_usage",
+        "config_files",
+        "current_file",
+        "history_bytes",
+        "history_limit",
+        "history_size",
+        "host",
+        "host_short",
+        "insert_flag",
+        "keypad_cursor_flag",
+        "keypad_flag",
+        "last_window_index",
+        "line",
+        "next_session_id",
+        "origin_flag",
+        "pid",
+        "search_match",
+        "socket_path",
+        "start_time",
+        "uid",
+        "user",
+        "version",
+        "wrap_flag",
+    }
+)
+
+
+def _token_scope(field_name: str) -> str:
+    """Resolve a format token's scope from its name.
+
+    Returns ``"universal"`` for cross-scope tokens (e.g. ``version``,
+    ``socket_path``, ``host``). Returns ``"event"`` for runtime-only tokens
+    that never appear in a ``list-*`` output (mouse, cursor, selection,
+    popup). Returns ``"pane"`` / ``"window"`` / ``"session"`` / ``"client"``
+    / ``"buffer"`` for scope-prefixed tokens.
+
+    Examples
+    --------
+    >>> from libtmux.neo import _token_scope
+    >>> _token_scope("pane_id")
+    'pane'
+    >>> _token_scope("window_zoomed_flag")
+    'window'
+    >>> _token_scope("client_name")
+    'client'
+    >>> _token_scope("version")
+    'universal'
+    >>> _token_scope("mouse_x")
+    'event'
+    """
+    for prefix, scope in _SCOPE_PREFIXES:
+        if field_name.startswith(prefix):
+            return scope
+    if field_name in _UNIVERSAL_TOKENS:
+        return "universal"
+    return "universal"
+
+
+def _normalize_tmux_version(version: str) -> LooseVersion:
+    """Convert a tmux version string into a comparable :class:`LooseVersion`.
+
+    tmux master is reported as ``"master"`` (or e.g. ``"3.6a-master"``);
+    treat it as larger than any tagged release.
+
+    Examples
+    --------
+    >>> from libtmux.neo import _normalize_tmux_version
+    >>> _normalize_tmux_version("3.6a") < _normalize_tmux_version("master")
+    True
+    >>> _normalize_tmux_version("3.2a") < _normalize_tmux_version("3.6a")
+    True
+    """
+    if "master" in version.lower():
+        return LooseVersion("99.0")
+    return LooseVersion(version)
+
+
 @dataclasses.dataclass()
 class Obj:
     """Dataclass of generic tmux object."""
@@ -211,40 +340,98 @@ def _refresh(
 
 
 @functools.cache
-def get_output_format() -> tuple[tuple[str, ...], str]:
-    """Return field names and tmux format string for all Obj fields.
+def get_output_format(
+    list_cmd: str = "list-panes",
+    tmux_version: str = "3.2a",
+) -> tuple[tuple[str, ...], str]:
+    """Return field names and tmux format string filtered by scope and version.
+
+    Only emits tokens whose scope is reachable from *list_cmd* (per
+    :data:`SCOPES_BY_LIST_CMD`) and whose minimum tmux version (per
+    :data:`FIELD_VERSION`) is at or below *tmux_version*. Runtime-only
+    tokens (``mouse_*``, ``cursor_*``, popups) are excluded from every
+    ``list-*`` template — they only resolve in event-time format contexts.
 
-    Excludes the ``server`` field, which is a Python object reference
-    rather than a tmux format variable.
+    Parameters
+    ----------
+    list_cmd : str
+        The tmux list subcommand the format string is being built for.
+        Determines which token scopes are reachable.
+    tmux_version : str
+        The live tmux version. Used to gate post-3.2a tokens. Defaults to
+        ``"3.2a"`` (the project's minimum) for safe fallback when the
+        caller can't yet detect the version.
 
     Returns
     -------
     tuple[tuple[str, ...], str]
-        A tuple of (field_names, tmux_format_string).
+        A tuple of (field_names, tmux_format_string) restricted to tokens
+        the given *list_cmd* and *tmux_version* can resolve.
 
     Examples
     --------
     >>> from libtmux.neo import get_output_format
-    >>> fields, fmt = get_output_format()
+    >>> fields, fmt = get_output_format("list-sessions", "3.6a")
     >>> 'session_id' in fields
     True
+    >>> 'pane_id' in fields
+    False
     >>> 'server' in fields
     False
-    """
-    # Exclude 'server' - it's a Python object, not a tmux format variable
-    formats = tuple(f for f in Obj.__dataclass_fields__ if f != "server")
-    tmux_formats = [f"#{{{f}}}{FORMAT_SEPARATOR}" for f in formats]
-    return formats, "".join(tmux_formats)
 
+    Pane scope picks up window and session tokens too:
+
+    >>> fields, _ = get_output_format("list-panes", "3.6a")
+    >>> all(t in fields for t in ('pane_id', 'window_id', 'session_id'))
+    True
+
+    Client scope is isolated from pane/window tokens:
+
+    >>> fields, _ = get_output_format("list-clients", "3.6a")
+    >>> 'pane_id' in fields
+    False
+    """
+    allowed_scopes = SCOPES_BY_LIST_CMD.get(
+        list_cmd,
+        frozenset({"universal", "session", "window", "pane"}),
+    )
+    live_ver = _normalize_tmux_version(tmux_version)
+
+    formats: list[str] = []
+    for f in Obj.__dataclass_fields__:
+        if f == "server":
+            continue
+        if _token_scope(f) not in allowed_scopes:
+            continue
+        min_v = FIELD_VERSION.get(f)
+        if min_v is not None and _normalize_tmux_version(min_v) > live_ver:
+            continue
+        formats.append(f)
+
+    tmux_format = "".join(f"#{{{n}}}{FORMAT_SEPARATOR}" for n in formats)
+    return tuple(formats), tmux_format
+
+
+def parse_output(
+    output: str,
+    list_cmd: str = "list-panes",
+    tmux_version: str = "3.2a",
+) -> OutputRaw:
+    """Parse a tmux ``-F`` line into a dict keyed by Obj field name.
 
-def parse_output(output: str) -> OutputRaw:
-    """Parse tmux output formatted with get_output_format() into a dict.
+    The (*list_cmd*, *tmux_version*) pair must match what was passed to
+    :func:`get_output_format` when the ``-F`` template was built —
+    otherwise the field order won't line up with the split values.
 
     Parameters
     ----------
     output : str
-        Raw tmux output produced with the format string from
+        Raw tmux output line produced with a template from
         :func:`get_output_format`.
+    list_cmd : str
+        Same value passed to :func:`get_output_format`.
+    tmux_version : str
+        Same value passed to :func:`get_output_format`.
 
     Returns
     -------
@@ -255,16 +442,20 @@ def parse_output(output: str) -> OutputRaw:
     --------
     >>> from libtmux.neo import get_output_format, parse_output
     >>> from libtmux.formats import FORMAT_SEPARATOR
-    >>> fields, fmt = get_output_format()
+    >>> fields, fmt = get_output_format("list-sessions", "3.6a")
     >>> values = [''] * len(fields)
     >>> values[fields.index('session_id')] = '$1'
-    >>> result = parse_output(FORMAT_SEPARATOR.join(values) + FORMAT_SEPARATOR)
+    >>> result = parse_output(
+    ...     FORMAT_SEPARATOR.join(values) + FORMAT_SEPARATOR,
+    ...     list_cmd="list-sessions",
+    ...     tmux_version="3.6a",
+    ... )
     >>> result['session_id']
     '$1'
-    >>> 'buffer_sample' in result
+    >>> 'pane_id' in result
     False
     """
-    formats, _ = get_output_format()
+    formats, _ = get_output_format(list_cmd, tmux_version)
     values = output.split(FORMAT_SEPARATOR)
 
     # Remove the trailing empty string from the split
@@ -326,7 +517,8 @@ def fetch_objs(
     >>> 'session_id' in objs[0]
     True
     """
-    _fields, format_string = get_output_format()
+    tmux_version = str(get_version(tmux_bin=server.tmux_bin))
+    _fields, format_string = get_output_format(list_cmd, tmux_version)
 
     cmd_args: list[str | int] = []
 
@@ -367,7 +559,7 @@ def fetch_objs(
 
     raise_if_stderr(proc, list_cmd)
 
-    outputs = [parse_output(line) for line in proc.stdout]
+    outputs = [parse_output(line, list_cmd, tmux_version) for line in proc.stdout]
 
     if logger.isEnabledFor(logging.DEBUG):
         if cmd_str is None:
