diff --git a/CHANGES b/CHANGES index ceafe8c33..09fa208fd 100644 --- a/CHANGES +++ b/CHANGES @@ -66,6 +66,13 @@ Workflow actions moved to their current major releases: `actions/checkout` v7, and `dorny/paths-filter` v4. Workflow behavior is unchanged, though setup-uv no longer prunes the uv cache, so the first run after this repopulates it. +#### tmux options, hooks, and formats are described (#721) + +The server, session, window, and pane option classes, the hook table, and +the format object now carry the tmux manual's description for every field. +They previously reached the rendered API reference as "Alias for field +number 0" or as a bare name carrying only its type. + ## libtmux 0.62.0 (2026-07-12) libtmux 0.62.0 teaches libtmux objects to locate themselves and to resolve diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py index a0b798111..df4d9843f 100644 --- a/src/libtmux/_internal/constants.py +++ b/src/libtmux/_internal/constants.py @@ -23,7 +23,66 @@ class ServerOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux server options.""" + """Container for tmux server options. + + Each field carries the value of the tmux server option named the same with + hyphens in place of underscores. A field keeps its default — ``None``, or an + empty container for the array options — when tmux reports no value for it. + + Attributes + ---------- + backspace : str | None + Key tmux sends when backspace is pressed. + buffer_limit : int | None + Number of paste buffers kept before the oldest is discarded. + command_alias : SparseArray[str] + Command aliases by array index, each a ``name=value`` pair expanded when a + command is parsed. + default_terminal : str | None + Value of ``TERM`` given to new windows. + copy_command : str | None + Shell command that copy-pipe pipes to when called without arguments. + escape_time : int | None + Milliseconds tmux waits after an escape to decide whether it starts a key + sequence. + editor : str | None + Command tmux runs when it needs an editor. + exit_empty : Literal["on", "off"] | None + Whether the server exits once no sessions remain. + exit_unattached : Literal["on", "off"] | None + Whether the server exits once no clients are attached. + extended_keys : Literal["on", "off", "always"] | None + Whether keys pressed with Control, Meta, or Shift are reported as extended + sequences, and whether the program in the pane may pick the mode. + focus_events : Literal["on", "off"] | None + Whether focus events are requested from the terminal and passed through to + applications. + history_file : str | None + File command prompt history is loaded from and written back to; an empty + value keeps no history file. + message_limit : int | None + Number of messages kept in each client's message log. + prompt_history_limit : int | None + Number of entries kept in the history file for each type of prompt. + set_clipboard : Literal["on", "external", "off"] | None + Whether tmux sets the terminal clipboard, and whether applications may + create paste buffers with the escape sequence. + terminal_features : TerminalFeatures + Feature names tmux applies to each terminal type pattern, for classes of + functionality terminfo does not report. + terminal_overrides : SparseArray[str] + terminfo capability overrides by array index, each a terminal type pattern + followed by ``name=value`` entries. + user_keys : SparseArray[str] + Escape sequences by array index, bound to the keys named ``User0``, + ``User1``, and so on. + default_client_command : str | None + Command run when tmux is invoked without one. + extended_keys_format : Literal["csi-u", "xterm"] | None + Escape sequence format used to report modified keys to applications. + get_clipboard : Literal["off", "buffer", "request", "both"] | None + How tmux answers an application that asks for the clipboard. + """ backspace: str | None = field(default=None) buffer_limit: int | None = field(default=None) @@ -62,7 +121,127 @@ def __init__(self, **kwargs: object) -> None: class SessionOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux session options.""" + """Container for tmux session options. + + Each field carries the value of the tmux session option named the same with + hyphens in place of underscores. A field keeps its default — ``None``, or an + empty container for the array options — when tmux reports no value for it. + + Attributes + ---------- + activity_action : Literal["any", "none", "current", "other"] | None + Which windows raise an alert on activity while monitor-activity is on. + assume_paste_time : int | None + Milliseconds below which consecutive input counts as a paste and key + bindings are not processed; zero disables. + base_index : int | None + Index of the first window in the session. + bell_action : Literal["any", "none", "current", "other"] | None + Which windows raise an alert on a bell while monitor-bell is on. + default_command : str | None + Command run in new windows; empty starts a login shell from default-shell. + default_shell : str | None + Full path of the shell used when default-command is empty. + default_size : str | None + Size of new windows as ``WIDTHxHEIGHT``, used when window-size is manual + or a session is created detached. + destroy_unattached : Literal["on", "off"] | None + Whether the session is destroyed once its last client detaches. + detach_on_destroy : Literal["off", "on", "no-detached", "previous", "next"] | None + Where a client goes when the session it is attached to is destroyed. + display_panes_active_colour : str | None + Colour of the active pane indicator shown by display-panes. + display_panes_colour : str | None + Colour of the inactive pane indicators shown by display-panes. + display_panes_time : int | None + Milliseconds the display-panes indicators stay on screen. + display_time : int | None + Milliseconds status line messages and indicators stay on screen; zero + holds them until a key is pressed. + history_limit : int | None + Lines of scrollback kept per pane, applied to panes created afterwards. + key_table : str | None + Key table key presses are looked up in first. + lock_after_time : int | None + Seconds of inactivity after which the session locks; zero never locks. + lock_command : str | None + Shell command run to lock each client. + menu_style : str | None + Style of menus. + menu_selected_style : str | None + Style of the selected menu item. + menu_border_style : str | None + Style of menu borders. + menu_border_lines : Literal["single", ...] | None + Characters used to draw menu borders. + message_command_style : str | None + Style of the command prompt while in vi command mode. + message_line : int | None + Status line row that messages and the command prompt are drawn on. + message_style : str | None + Style of messages and the command prompt. + mouse : Literal["on", "off"] | None + Whether tmux captures the mouse so mouse events run key bindings. + prefix : str | None + Key accepted as the prefix key; the tmux key name ``None`` sets no prefix. + prefix2 : str | None + Second key accepted as a prefix key. + renumber_windows : Literal["on", "off"] | None + Whether closing a window renumbers the rest so no gaps are left. + repeat_time : int | None + Milliseconds a key bound with ``-r`` may be repeated without the prefix. + set_titles : Literal["on", "off"] | None + Whether tmux sets the client terminal title. + set_titles_string : str | None + Format expanded to build the terminal title while set-titles is on. + silence_action : Literal["any", "none", "current", "other"] | None + Which windows raise an alert on silence while monitor-silence is on. + status : Literal["off", "on"] | int | None + Whether the status line is shown, and how many rows it occupies. + status_format : list[str] | None + Format of each status line row, one entry per row. + status_interval : int | None + Seconds between status line updates; zero disables timed redraws. + status_justify : Literal["left", "centre", "right", "absolute-centre"] | None + Position of the window list within the status line. + status_keys : Literal["vi", "emacs"] | None + Key set used at the command prompt and in the status line. + status_left : str | None + Format drawn on the left of the status line. + status_left_length : int | None + Maximum width of the left side of the status line. + status_left_style : str | None + Style of the left side of the status line. + status_position : Literal["top", "bottom"] | None + Edge of the terminal the status line sits on. + status_right : str | None + Format drawn on the right of the status line. + status_right_length : int | None + Maximum width of the right side of the status line. + status_right_style : str | None + Style of the right side of the status line. + status_style : str | None + Style of the status line. + update_environment : SparseArray[str] + Environment variable names by array index, copied from the client into the + session environment when a session is created or attached. + visual_activity : Literal["on", "off", "both"] | None + Whether an activity alert shows a message, rings the bell, or both. + visual_bell : Literal["on", "off", "both"] | None + Whether a bell alert shows a message, rings the bell, or both. + visual_silence : Literal["on", "off", "both"] | None + Whether a silence alert shows a message, rings the bell, or both. + word_separators : str | None + Characters that separate words for the copy mode word commands. + focus_follows_mouse : Literal["on", "off"] | None + Whether moving the mouse into a pane selects it, while mouse is on. + message_format : str | None + Format of the prompt and message area, where ``#{message}`` expands to the + prompt or message text. + prompt_command_cursor_style : Literal["default", ...] | None + Shape of the cursor in the command prompt while in vi command mode, and + whether it blinks. + """ activity_action: t.Literal["any", "none", "current", "other"] | None = field( default=None, @@ -154,7 +333,116 @@ def __init__(self, **kwargs: object) -> None: class WindowOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux window options.""" + """Container for tmux window options. + + Each field carries the value of the tmux window option named the same with + hyphens in place of underscores, and is ``None`` when tmux reports no value + for it. + + Attributes + ---------- + aggressive_resize : Literal["on", "off"] | None + Whether the window is sized from the sessions where it is the current + window rather than from every session it is linked to. + automatic_rename : Literal["on", "off"] | None + Whether tmux renames the window from automatic-rename-format. + automatic_rename_format : str | None + Format used to build the name while automatic-rename is on. + clock_mode_colour : str | None + Colour of the clock in clock mode. + clock_mode_style : Literal["12", "24"] | None + Hour format of the clock in clock mode. + fill_character : str | None + Character filling terminal area the window does not cover. + main_pane_height : int | str | None + Height of the main pane in the main-horizontal layouts, in rows or as a + percentage such as ``"10%"``. + main_pane_width : int | str | None + Width of the main pane in the main-vertical layouts, in columns or as a + percentage such as ``"10%"``. + copy_mode_match_style : str | None + Style of search matches in copy mode. + copy_mode_mark_style : str | None + Style of the line holding the mark in copy mode. + copy_mode_current_match_style : str | None + Style of the search match the cursor is on in copy mode. + mode_keys : Literal["vi", "emacs"] | None + Key set used in copy mode. + mode_style : str | None + Style of indicators and highlighting in window modes. + monitor_activity : Literal["on", "off"] | None + Whether activity in the window raises an alert. + monitor_bell : Literal["on", "off"] | None + Whether a bell in the window raises an alert. + monitor_silence : int | None + Seconds of silence after which the window raises an alert; zero disables. + other_pane_height : int | str | None + Height of the panes beside the main one in the main-horizontal layouts, in + rows or as a percentage; zero has no effect. + other_pane_width : int | str | None + Width of the panes beside the main one in the main-vertical layouts, in + columns or as a percentage; zero has no effect. + pane_active_border_style : str | None + Style of the border around the active pane. + pane_base_index : int | None + Index of the first pane in the window. + pane_border_format : str | None + Format of the text shown in pane border status lines. + pane_border_indicators : Literal["off", "colour", "arrows", "both"] | None + How the active pane is marked on the border, by colouring it, by arrow + markers, by both, or not at all. + pane_border_lines : Literal["single", "double", "heavy", "simple", "number"] | None + Characters used to draw pane borders. + pane_border_status : Literal["off", "top", "bottom"] | None + Whether pane border status lines are drawn, and on which border. + pane_border_style : str | None + Style of the borders around panes other than the active one. + popup_style : str | None + Style of popups. + popup_border_style : str | None + Style of popup borders. + popup_border_lines : Literal["single", ...] | None + Characters used to draw popup borders. + window_status_activity_style : str | None + Style of a window in the status line while it has an activity alert. + window_status_bell_style : str | None + Style of a window in the status line while it has a bell alert. + window_status_current_format : str | None + Format of the current window in the status line window list. + window_status_current_style : str | None + Style of the current window in the status line. + window_status_format : str | None + Format of windows other than the current one in the status line window + list. + window_status_last_style : str | None + Style of the last active window in the status line. + window_status_separator : str | None + Text drawn between windows in the status line window list. + window_status_style : str | None + Style of windows other than the current and last ones in the status line. + window_size : Literal["largest", "smallest", "manual", "latest"] | None + How tmux derives the window size from the attached clients. + wrap_search : Literal["on", "off"] | None + Whether a copy mode search wraps around the end of the pane contents. + tiled_layout_max_columns : int | None + Maximum columns in the tiled layout, with further panes stacked in extra + rows; zero means no limit. + copy_mode_line_numbers : Literal["off", ...] | None + Whether copy mode shows line numbers, and whether they are counted from + the start of the history or from the cursor. + copy_mode_line_number_style : str | None + Style of line numbers in copy mode. + copy_mode_current_line_number_style : str | None + Style of the line number on the cursor line in copy mode. + tree_mode_preview_format : str | None + Format of the preview indicator in tree mode. + tree_mode_preview_style : str | None + Style of the preview indicator in tree mode. + window_pane_status_format : str | None + Format of panes other than the current one in the status line pane list. + window_pane_current_status_format : str | None + Format of the current pane in the status line pane list. + """ aggressive_resize: t.Literal["on", "off"] | None = field(default=None) automatic_rename: t.Literal["on", "off"] | None = field(default=None) @@ -229,7 +517,56 @@ def __init__(self, **kwargs: object) -> None: class PaneOptions( SkipDefaultFieldsReprMixin, ): - """Container for tmux pane options.""" + """Container for tmux pane options. + + Each field carries the value of the tmux pane option named the same with + hyphens in place of underscores, and is ``None`` when tmux reports no value + for it. + + Attributes + ---------- + allow_passthrough : Literal["on", "off", "all"] | None + Whether programs in the pane may bypass tmux with the passthrough escape + sequence, and whether an invisible pane may do so. + allow_rename : Literal["on", "off"] | None + Whether programs in the pane may rename the window with an escape + sequence. + alternate_screen : Literal["on", "off"] | None + Whether programs in the pane may use the terminal alternate screen, which + restores the earlier pane contents when they exit. + cursor_colour : str | None + Colour of the cursor in the pane. + pane_colours : list[str] | None + Colour palette the pane uses for the colours numbered zero to 255, in + index order. + cursor_style : Literal["default", ...] | None + Shape of the cursor in the pane, and whether it blinks. + remain_on_exit : Literal["on", "off", "failed", "key"] | None + Whether the pane stays open once the program running in it exits. + remain_on_exit_format : str | None + Text shown at the bottom of a pane held open by remain-on-exit. + scroll_on_clear : Literal["on", "off"] | None + Whether clearing the whole screen scrolls its contents into history first. + synchronize_panes : Literal["on", "off"] | None + Whether input is duplicated to the other panes in the window that also + have this on. + window_active_style : str | None + Style of the pane while it is the active pane. + window_style : str | None + Style of the pane while it is not the active pane. + pane_scrollbars : Literal["off", "modal", "on"] | None + Whether a character based scrollbar is drawn beside the pane, all the time + or only while the pane is in copy or view mode. + pane_scrollbars_style : str | None + Style of the pane scrollbar, whose width and pad attributes size it and + the gap to the pane. + tree_mode_preview_format : str | None + Format of the preview indicator in tree mode. + pane_active_border_style : str | None + Style of the pane border while the pane is active. + pane_border_style : str | None + Style of the pane border while the pane is not active. + """ allow_passthrough: t.Literal["on", "off", "all"] | None = field(default=None) allow_rename: t.Literal["on", "off"] | None = field(default=None) @@ -300,6 +637,203 @@ class Hooks( Parses tmux hook output into typed :class:`SparseArray` fields, preserving array indices for hooks that can have multiple commands at different indices. + A field holds an empty :class:`SparseArray` when tmux reports no commands + for that hook. + + Attributes + ---------- + alert_activity : SparseArray[str] + Run when a window has activity. See monitor-activity. + alert_bell : SparseArray[str] + Run when a window has received a bell. See monitor-bell. + alert_silence : SparseArray[str] + Run when a window has been silent. See monitor-silence. + client_active : SparseArray[str] + Run when a client becomes the latest active client of its session. + client_attached : SparseArray[str] + Run when a client is attached. + client_detached : SparseArray[str] + Run when a client is detached. + client_focus_in : SparseArray[str] + Run when focus enters a client. + client_focus_out : SparseArray[str] + Run when focus exits a client. + client_resized : SparseArray[str] + Run when a client is resized. + client_session_changed : SparseArray[str] + Run when a client's attached session is changed. + pane_died : SparseArray[str] + Run when the program running in a pane exits, but remain-on-exit is on so the + pane has not closed. + pane_exited : SparseArray[str] + Run when the program running in a pane exits. + pane_focus_in : SparseArray[str] + Run when the focus enters a pane, if the focus-events option is on. + pane_focus_out : SparseArray[str] + Run when the focus exits a pane, if the focus-events option is on. + pane_set_clipboard : SparseArray[str] + Run when the terminal clipboard is set using the xterm(1) escape sequence. + session_created : SparseArray[str] + Run when a new session created. + session_closed : SparseArray[str] + Run when a session closed. + session_renamed : SparseArray[str] + Run when a session is renamed. + window_linked : SparseArray[str] + Run when a window is linked into a session. + window_renamed : SparseArray[str] + Run when a window is renamed. + window_resized : SparseArray[str] + Run when a window is resized. This may be after the client-resized hook is run. + window_unlinked : SparseArray[str] + Run when a window is unlinked from a session. + pane_title_changed : SparseArray[str] + Run when a pane title changes (tmux 3.5+). + client_light_theme : SparseArray[str] + Run when terminal reports a light theme (tmux 3.5+). + client_dark_theme : SparseArray[str] + Run when terminal reports a dark theme (tmux 3.5+). + client_detached_control : SparseArray[str] + The client has detached. + client_session_changed_control : SparseArray[str] + The client is now attached to the session with ID session-id, which is named + name. + config_error : SparseArray[str] + An error has happened in a configuration file. + continue_control : SparseArray[str] + The pane has been continued after being paused (if the pause-after flag is set, + see refresh-client -A). + exit_control : SparseArray[str] + The tmux client is exiting immediately, either because it is not attached to any + session or an error occurred. + extended_output : SparseArray[str] + New form of %output sent when the pause-after flag is set. + layout_change : SparseArray[str] + The layout of a window with ID window-id changed. + message_control : SparseArray[str] + A message sent with the display-message command. + output : SparseArray[str] + A window pane produced output. + pane_mode_changed : SparseArray[str] + The pane with ID pane-id has changed mode. + paste_buffer_changed : SparseArray[str] + Paste buffer name has been changed. + paste_buffer_deleted : SparseArray[str] + Paste buffer name has been deleted. + pause_control : SparseArray[str] + The pane has been paused (if the pause-after flag is set). + session_changed_control : SparseArray[str] + The client is now attached to the session with ID session-id, which is named + name. + session_renamed_control : SparseArray[str] + The current session was renamed to name. + session_window_changed : SparseArray[str] + The session with ID session-id changed its active window to the window with ID + window-id. + sessions_changed : SparseArray[str] + A session was created or destroyed. + subscription_changed : SparseArray[str] + The value of the format associated with subscription name has changed to value. + unlinked_window_add : SparseArray[str] + The window with ID window-id was created but is not linked to the current + session. + unlinked_window_close : SparseArray[str] + The window with ID window-id, which is not linked to the current session, was + closed. + unlinked_window_renamed : SparseArray[str] + The window with ID window-id, which is not linked to the current session, was + renamed. + window_add : SparseArray[str] + The window with ID window-id was linked to the current session. + window_close : SparseArray[str] + The window with ID window-id closed. + window_layout_changed : SparseArray[str] + The layout of a window with ID window-id changed. The new layout is + window-layout. The window's visible layout is window-visible-layout and the + window flags are window-flags. + window_pane_changed : SparseArray[str] + The active pane in the window with ID window-id changed to the pane with ID + pane-id. + window_renamed_control : SparseArray[str] + The window with ID window-id was renamed to name. + after_bind_key : SparseArray[str] + Runs after 'bind-key' completes. + after_capture_pane : SparseArray[str] + Runs after 'capture-pane' completes. + after_copy_mode : SparseArray[str] + Runs after 'copy-mode' completes. + after_display_message : SparseArray[str] + Runs after 'display-message' completes. + after_display_panes : SparseArray[str] + Runs after 'display-panes' completes. + after_kill_pane : SparseArray[str] + Runs after 'kill-pane' completes. + after_list_buffers : SparseArray[str] + Runs after 'list-buffers' completes. + after_list_clients : SparseArray[str] + Runs after 'list-clients' completes. + after_list_keys : SparseArray[str] + Runs after 'list-keys' completes. + after_list_panes : SparseArray[str] + Runs after 'list-panes' completes. + after_list_sessions : SparseArray[str] + Runs after 'list-sessions' completes. + after_list_windows : SparseArray[str] + Runs after 'list-windows' completes. + after_load_buffer : SparseArray[str] + Runs after 'load-buffer' completes. + after_lock_server : SparseArray[str] + Runs after 'lock-server' completes. + after_new_session : SparseArray[str] + Runs after 'new-session' completes. + after_new_window : SparseArray[str] + Runs after 'new-window' completes. + after_paste_buffer : SparseArray[str] + Runs after 'paste-buffer' completes. + after_pipe_pane : SparseArray[str] + Runs after 'pipe-pane' completes. + after_queue : SparseArray[str] + Runs after 'queue' command is processed. + after_refresh_client : SparseArray[str] + Runs after 'refresh-client' completes. + after_rename_session : SparseArray[str] + Runs after 'rename-session' completes. + after_rename_window : SparseArray[str] + Runs after 'rename-window' completes. + after_resize_pane : SparseArray[str] + Runs after 'resize-pane' completes. + after_resize_window : SparseArray[str] + Runs after 'resize-window' completes. + after_save_buffer : SparseArray[str] + Runs after 'save-buffer' completes. + after_select_layout : SparseArray[str] + Runs after 'select-layout' completes. + after_select_pane : SparseArray[str] + Runs after 'select-pane' completes. + after_select_window : SparseArray[str] + Runs after 'select-window' completes. + after_send_keys : SparseArray[str] + Runs after 'send-keys' completes. + after_set_buffer : SparseArray[str] + Runs after 'set-buffer' completes. + after_set_environment : SparseArray[str] + Runs after 'set-environment' completes. + after_set_hook : SparseArray[str] + Runs after 'set-hook' completes. + after_set_option : SparseArray[str] + Runs after 'set-option' completes. + after_show_environment : SparseArray[str] + Runs after 'show-environment' completes. + after_show_messages : SparseArray[str] + Runs after 'show-messages' completes. + after_show_options : SparseArray[str] + Runs after 'show-options' completes. + after_split_window : SparseArray[str] + Runs after 'split-window' completes. + after_unbind_key : SparseArray[str] + Runs after 'unbind-key' completes. + command_error : SparseArray[str] + Runs when a command fails (tmux 3.5+). Examples -------- diff --git a/src/libtmux/neo.py b/src/libtmux/neo.py index 7a7d1a46a..98ece86fa 100644 --- a/src/libtmux/neo.py +++ b/src/libtmux/neo.py @@ -284,6 +284,384 @@ def _normalize_tmux_version(version: str) -> LooseVersion: class Obj: """Dataclass of generic tmux object. + Every field but ``server`` is a tmux format token, and tmux reports each + one as a string. A field is ``None`` when its token was left out of the + query or expanded to empty: tokens outside the listing's scope (see + :data:`SCOPES_BY_LIST_CMD`) and tokens the running tmux is too old to + register (see :data:`FIELD_VERSION`) are never requested, and copy-mode + and command-context tokens only resolve at event time. + + Attributes + ---------- + server : Server + Server the object was queried from, and the connection every refresh + re-runs its ``list-*`` command over. + active_window_index : str | None + Index of the session's active window. + alternate_saved_x : str | None + Saved cursor X position for the pane's alternate screen. + alternate_saved_y : str | None + Saved cursor Y position for the pane's alternate screen. + bracket_paste_flag : str | None + ``"1"`` when the pane's terminal has bracketed paste mode enabled. + buffer_name : str | None + Name of the buffer. + buffer_sample : str | None + Sample taken from the start of the buffer's contents. + buffer_size : str | None + Size of the buffer, in bytes. + client_activity : str | None + Time the client last had activity. + client_cell_height : str | None + Height of one of the client's terminal cells, in pixels. + client_cell_width : str | None + Width of one of the client's terminal cells, in pixels. + client_control_mode : str | None + ``"1"`` when the client is running in control mode. + client_created : str | None + Time the client was created. + client_discarded : str | None + Bytes discarded because the client fell behind. + client_flags : str | None + List of the client's flags. + client_height : str | None + Height of the client, in cells. + client_key_table : str | None + Name of the key table the client is currently using. + client_last_session : str | None + Name of the session the client was attached to before its current one. + client_mode_format : str | None + Default format string tmux's client mode (``choose-client``) renders + each client row with. + client_name : str | None + Name of the client. + client_pid : str | None + PID of the client process. + client_prefix : str | None + ``"1"`` while the prefix key has been pressed. + client_readonly : str | None + ``"1"`` when the client is attached read-only. + client_session : str | None + Name of the session the client is attached to. + client_termfeatures : str | None + Terminal features tmux detected for the client, if any. + client_termname : str | None + Terminal name of the client. + client_termtype : str | None + Terminal type of the client, if available. + client_tty : str | None + Path to the client's pseudo terminal. + client_uid : str | None + UID of the client process. + client_user : str | None + User the client process runs as. + client_utf8 : str | None + ``"1"`` when the client supports UTF-8. + client_width : str | None + Width of the client, in cells. + client_written : str | None + Bytes written to the client. + command_list_alias : str | None + Command alias, when listing commands. + command_list_name : str | None + Command name, when listing commands. + command_list_usage : str | None + Command usage string, when listing commands. + config_files : str | None + List of the configuration files tmux loaded. + copy_cursor_line : str | None + Text of the line the cursor sits on in copy mode. + copy_cursor_word : str | None + Word under the cursor in copy mode. + copy_cursor_x : str | None + Cursor X position in copy mode. + copy_cursor_y : str | None + Cursor Y position in copy mode. + current_file : str | None + Configuration file currently being parsed. + cursor_character : str | None + Character at the pane's cursor position. + cursor_flag : str | None + ``"1"`` when the pane's cursor is visible. + cursor_x : str | None + Cursor X position in the pane. + cursor_y : str | None + Cursor Y position in the pane. + history_bytes : str | None + Bytes held in the pane's scrollback history. + history_limit : str | None + Maximum number of scrollback lines the pane keeps. + history_size : str | None + Lines currently held in the pane's scrollback history. + insert_flag : str | None + ``"1"`` when the pane's terminal is in insert mode. + keypad_cursor_flag : str | None + ``"1"`` when the pane's terminal is in application cursor key mode. + keypad_flag : str | None + ``"1"`` when the pane's terminal is in application keypad mode. + last_window_index : str | None + Index of the last window in the session. + line : str | None + Row number tmux assigns to the entry in the listing. + mouse_all_flag : str | None + ``"1"`` when the pane's terminal has all-motion mouse reporting + enabled. + mouse_any_flag : str | None + ``"1"`` when the pane's terminal has any mouse reporting mode enabled. + mouse_button_flag : str | None + ``"1"`` when the pane's terminal has button-event mouse reporting + enabled. + mouse_sgr_flag : str | None + ``"1"`` when the pane's terminal reports mouse events in SGR form. + mouse_standard_flag : str | None + ``"1"`` when the pane's terminal has standard mouse reporting enabled. + next_session_id : str | None + Session ID tmux will give the next new session. + origin_flag : str | None + ``"1"`` when the pane's terminal is in origin mode. + pane_active : str | None + ``"1"`` when this is the active pane of its window. + pane_at_bottom : str | None + ``"1"`` when the pane touches the bottom of the window. + pane_at_left : str | None + ``"1"`` when the pane touches the left of the window. + pane_at_right : str | None + ``"1"`` when the pane touches the right of the window. + pane_at_top : str | None + ``"1"`` when the pane touches the top of the window. + pane_bg : str | None + Pane background colour. + pane_bottom : str | None + Bottom edge of the pane, as a window row. + pane_current_command : str | None + Command running in the pane, if available. + pane_current_path : str | None + Working directory of the pane, if available. + pane_dead : str | None + ``"1"`` when the pane's process has exited and the pane is dead. + pane_dead_signal : str | None + Signal that killed the process in a dead pane. + pane_dead_status : str | None + Exit status of the process in a dead pane. + pane_dead_time : str | None + Time the process in a dead pane exited. + pane_fg : str | None + Pane foreground colour. + pane_flags : str | None + Pane flags: ``*`` for the active pane, ``-`` for the last used, ``Z`` + for zoomed, ``F`` for floating. + pane_floating_flag : str | None + ``"1"`` when the pane is floating. + pane_format : str | None + ``"1"`` when the format is being evaluated for a pane. + pane_height : str | None + Height of the pane, in cells. + pane_id : str | None + Unique pane ID, e.g. ``"%3"`` (the ``#D`` alias). + pane_in_mode : str | None + Number of modes the pane is in. + pane_index : str | None + Index of the pane within its window (the ``#P`` alias). + pane_input_off : str | None + ``"1"`` when input to the pane is disabled. + pane_last : str | None + ``"1"`` when this is the window's last used pane. + pane_left : str | None + Left edge of the pane, as a window column. + pane_marked : str | None + ``"1"`` when this pane is the marked pane. + pane_marked_set : str | None + ``"1"`` when a marked pane is set on the server. + pane_mode : str | None + Name of the mode the pane is in, if any. + pane_path : str | None + Path of the pane; the application running in it can set this. + pane_pb_progress : str | None + Progress percentage of the pane's progress bar; the application running + in it can set this. + pane_pb_state : str | None + Pane progress bar state, one of ``hidden``, ``normal``, ``error``, + ``indeterminate``, or ``paused``; the application running in the pane + can set this. + pane_pid : str | None + PID of the first process started in the pane. + pane_pipe : str | None + ``"1"`` while the pane's output is being piped. + pane_pipe_pid : str | None + PID of the pipe process, if any. + pane_right : str | None + Right edge of the pane, as a window column. + pane_search_string : str | None + Last search string used in the pane's copy mode. + pane_start_command : str | None + Command the pane was started with. + pane_start_path : str | None + Working directory the pane was started in. + pane_synchronized : str | None + ``"1"`` when the pane has ``synchronize-panes`` in effect. + pane_tabs : str | None + Tab stop positions in the pane. + pane_title : str | None + Title of the pane; the application running in it can set this (the + ``#T`` alias). + pane_top : str | None + Top edge of the pane, as a window row. + pane_tty : str | None + Path to the pane's pseudo terminal. + pane_width : str | None + Width of the pane, in cells. + pane_x : str | None + X position of the pane. + pane_y : str | None + Y position of the pane. + pane_z : str | None + Z position of the pane. + pane_zoomed_flag : str | None + ``"1"`` when the pane is zoomed. + pid : str | None + PID of the tmux server process. + scroll_position : str | None + Scroll position in copy mode. + scroll_region_lower : str | None + Bottom line of the pane's scroll region. + scroll_region_upper : str | None + Top line of the pane's scroll region. + search_match : str | None + Search match in the pane's copy mode, if any. + selection_end_x : str | None + X position of the end of the copy-mode selection. + selection_end_y : str | None + Y position of the end of the copy-mode selection. + selection_start_x : str | None + X position of the start of the copy-mode selection. + selection_start_y : str | None + Y position of the start of the copy-mode selection. + session_activity : str | None + Time of the session's last activity. + session_alerts : str | None + List of indexes of the session's windows with alerts. + session_attached : str | None + Number of clients attached to the session. + session_attached_list : str | None + List of the clients attached to the session. + session_created : str | None + Time the session was created. + session_format : str | None + ``"1"`` when the format is being evaluated for a session. + session_group : str | None + Name of the session group the session belongs to. + session_group_attached : str | None + Number of clients attached to sessions in the session group. + session_group_attached_list : str | None + List of the clients attached to sessions in the session group. + session_group_list : str | None + List of the sessions in the session group. + session_group_many_attached : str | None + ``"1"`` when more than one client is attached to sessions in the + session group. + session_group_size : str | None + Number of sessions in the session group. + session_grouped : str | None + ``"1"`` when the session belongs to a session group. + session_id : str | None + Unique session ID, e.g. ``"$1"``. + session_last_attached : str | None + Time the session was last attached. + session_many_attached : str | None + ``"1"`` when more than one client is attached to the session. + session_marked : str | None + ``"1"`` when the session contains the marked pane. + session_name : str | None + Name of the session (the ``#S`` alias). + session_path : str | None + Working directory of the session. + session_stack : str | None + Indexes of the session's windows, most recently used first. + session_windows : str | None + Number of windows in the session. + socket_path : str | None + Path to the tmux server's socket. + start_time : str | None + Time the tmux server started. + synchronized_output_flag : str | None + ``"1"`` when the pane's terminal has synchronized output enabled. + uid : str | None + UID the tmux server runs as. + user : str | None + User the tmux server runs as. + version : str | None + Version of the running tmux server. + window_active : str | None + ``"1"`` when the window is its session's current window. + window_active_clients : str | None + Number of clients viewing the window. + window_active_clients_list : str | None + List of the clients viewing the window. + window_active_sessions : str | None + Number of sessions in which the window is the active one. + window_active_sessions_list : str | None + List of the sessions in which the window is the active one. + window_activity : str | None + Time of the window's last activity. + window_activity_flag : str | None + ``"1"`` when the window has an activity alert. + window_bell_flag : str | None + ``"1"`` when the window has a bell alert. + window_bigger : str | None + ``"1"`` when the window is larger than the client viewing it. + window_cell_height : str | None + Height of one of the window's cells, in pixels. + window_cell_width : str | None + Width of one of the window's cells, in pixels. + window_end_flag : str | None + ``"1"`` when the window has the highest index in the session. + window_flags : str | None + Window flags, with ``#`` escaped as ``##`` (the ``#F`` alias). + window_format : str | None + ``"1"`` when the format is being evaluated for a window. + window_height : str | None + Height of the window, in cells. + window_id : str | None + Unique window ID, e.g. ``"@2"``. + window_index : str | None + Index of the window in its session (the ``#I`` alias). + window_last_flag : str | None + ``"1"`` when the window is the session's last used one. + window_layout : str | None + Window layout description, ignoring zoomed panes. + window_linked : str | None + ``"1"`` when the window is linked across sessions. + window_linked_sessions : str | None + Number of sessions the window is linked into. + window_linked_sessions_list : str | None + List of the sessions the window is linked into. + window_marked_flag : str | None + ``"1"`` when the window contains the marked pane. + window_name : str | None + Name of the window (the ``#W`` alias). + window_offset_x : str | None + X offset into the window when it is larger than the client. + window_offset_y : str | None + Y offset into the window when it is larger than the client. + window_panes : str | None + Number of panes in the window. + window_raw_flags : str | None + Window flags, with nothing escaped. + window_silence_flag : str | None + ``"1"`` when the window has a silence alert. + window_stack_index : str | None + Index of the window in its session's most recently used stack. + window_start_flag : str | None + ``"1"`` when the window has the lowest index in the session. + window_visible_layout : str | None + Window layout description, respecting zoomed panes. + window_width : str | None + Width of the window, in cells. + window_zoomed_flag : str | None + ``"1"`` when the window is zoomed. + wrap_flag : str | None + ``"1"`` when the pane's terminal wraps at the right margin. + Notes ----- tmux may return fields from an object's active children along with the diff --git a/src/libtmux/pane.py b/src/libtmux/pane.py index d10dabb0b..e0c2f5961 100644 --- a/src/libtmux/pane.py +++ b/src/libtmux/pane.py @@ -57,6 +57,22 @@ class Pane( ``Pane`` instances can send commands directly to a pane, or traverse between linked tmux objects. + Attributes + ---------- + default_option_scope : OptionScope | None + Scope :class:`~libtmux.options.OptionsMixin` falls back to when an + option call leaves ``scope`` unset. ``OptionScope.Pane`` sends + ``set-option`` and ``show-options`` with tmux's ``-p`` flag; ``None`` + sends no scope flag, which tmux resolves as session scope. + default_hook_scope : OptionScope | None + Scope :class:`~libtmux.hooks.HooksMixin` falls back to when a hook + call leaves ``scope`` unset. ``OptionScope.Pane`` sends ``set-hook`` + and ``show-hooks`` with tmux's ``-p`` flag; ``None`` sends no scope + flag, which tmux resolves as session scope. + server : Server + Server the pane was queried from, and the connection every command + and refresh runs over. + Examples -------- >>> pane diff --git a/src/libtmux/session.py b/src/libtmux/session.py index 31d071aca..4277052a3 100644 --- a/src/libtmux/session.py +++ b/src/libtmux/session.py @@ -62,6 +62,21 @@ class Session( Parameters ---------- server : :class:`Server` + Server the session was queried from, and the connection every command + and refresh runs over. + + Attributes + ---------- + default_option_scope : OptionScope | None + Scope :class:`~libtmux.options.OptionsMixin` falls back to when an + option call leaves ``scope`` unset. ``None`` sends ``set-option`` and + ``show-options`` with no scope flag, which tmux resolves as session + scope; ``OptionScope.Session`` maps to that same empty flag. + default_hook_scope : OptionScope | None + Scope :class:`~libtmux.hooks.HooksMixin` falls back to when a hook + call leaves ``scope`` unset. ``None`` sends ``set-hook`` and + ``show-hooks`` with no scope flag, which tmux resolves as session + scope. Examples -------- diff --git a/src/libtmux/window.py b/src/libtmux/window.py index 02c16f3f6..b57db9969 100644 --- a/src/libtmux/window.py +++ b/src/libtmux/window.py @@ -64,6 +64,22 @@ class Window( ---------- session : :class:`Session` + Attributes + ---------- + default_option_scope : OptionScope | None + Scope :class:`~libtmux.options.OptionsMixin` falls back to when an + option call leaves ``scope`` unset. ``OptionScope.Window`` sends + ``set-option`` and ``show-options`` with tmux's ``-w`` flag; ``None`` + sends no scope flag, which tmux resolves as session scope. + default_hook_scope : OptionScope | None + Scope :class:`~libtmux.hooks.HooksMixin` falls back to when a hook + call leaves ``scope`` unset. ``OptionScope.Window`` sends ``set-hook`` + and ``show-hooks`` with tmux's ``-w`` flag; ``None`` sends no scope + flag, which tmux resolves as session scope. + server : Server + Server the window was queried from, and the connection every command + and refresh runs over. + Examples -------- >>> window = session.new_window('My project', attach=True)