Windows¶
- Parameters:
session (
Session)
Examples
>>> window = session.new_window('My project', attach=True)
>>> window Window(@2 2:My project, Session($... ...))
Windows have panes:
>>> window.panes [Pane(...)]
>>> window.active_pane Pane(...)
Relations moving up:
>>> window.session Session(...)
>>> window.window_id == session.active_window.window_id True
>>> window == session.active_window True
>>> window in session.windows True
The window can be used as a context manager to ensure proper cleanup:
>>> with session.new_window() as window: ... pane = window.split() ... # Do work with the pane ... # Window will be killed automatically when exiting the context
References
[window_manual]- tmux window. openbsd manpage for TMUX(1).
“Each session has one or more windows linked to it. A window occupies the entire screen and may be split into rectangular panes…”
https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
Refresh window attributes from tmux.
Scoped to this window’s own session (
list-windows -t @ID), so tmux – not libtmux – decides which session the window belongs to. SeeWindow.from_window_id().- Raises:
ValueError– Whenwindow_idis unset. Surfaces a clear error underpython -O, where anassertwould be stripped.TmuxObjectDoesNotExist– When the window no longer exists.LibTmuxException– When tmux itself is unreachable.
- Return type:
Examples
>>> window.refresh() >>> window.window_id '@1'
Create Window from existing window_id.
tmux’s
cmd_findroutes a-ttarget by sigil, so an@-id handed tolist-windowsresolves to that window’s session and lists it. The rows come back stamped with the session tmux considers canonical for the window – the most recently active one – so a window linked into several sessions reports the same parent tmux itself would.- Parameters:
- Return type:
- Raises:
TmuxObjectDoesNotExist– When no such window exists on a reachable server.LibTmuxException– When tmux itself is unreachable.
Examples
>>> Window.from_window_id(server=window.server, window_id=window.window_id) Window(@1 1:..., Session($1 ...))
Return the window containing the pane this process runs inside of.
Resolves through
Pane.from_env(), so the answer is the window that contains the caller – not the session’s currently active window, which may be a different one entirely.- Parameters:
env (
typing.Mapping, optional) – Environment to read. Defaults toos.environ.- Return type:
- Raises:
NotInsideTmux– When$TMUXor$TMUX_PANEis unset or malformed.TmuxObjectDoesNotExist– When the pane named by$TMUX_PANEis gone.LibTmuxException– When the server named by$TMUXis unreachable.ValueError– When the resolved pane carries nowindow_id. Surfaces a clear error underpython -O, where anassertwould be stripped.
Examples
>>> Window.from_env(env) Window(@1 1:..., Session($1 ...))
The caller’s window is reported even while another window is active:
>>> _ = session.new_window(window_name="foreground", attach=True) >>> Window.from_env(env).window_id == window.window_id True
Added in version 0.62.
Every session this window is reachable from.
Usually one, and then this is just
Window.sessionin a list.link-windowand grouped sessions (tmux new-session -t existing) make it more: the window is genuinely in each of them at once, andWindow.sessionreturns the session recorded on thisWindowinstance.Each session is listed once, however many indexes it links the window at, and they come back in the order tmux lists them. Fetching the holders takes two list commands total, independent of how many there are. If either listing fails, the result is empty.
See also
Window.sessionthe session recorded on this window instance.
Examples
A window you just made belongs to the session you made it in:
>>> window = session.new_window(window_name="solo", attach=False) >>> [s.session_name for s in window.linked_sessions] == [session.session_name] True
Link it into a second session and it belongs to both:
>>> guest = server.new_session(session_name="guest") >>> target = f"{guest.session_id}:" >>> _ = server.cmd("link-window", "-d", "-s", window.window_id, "-t", target) >>> sorted(s.session_name for s in window.linked_sessions) == sorted( ... [session.session_name, "guest"] ... ) True
Added in version 0.62.
Panes contained by window.
Can be accessed via
.panes.get()and.panes.filter()
Panes in this window, optionally filtered by tmux.
Like
Window.panesbut with afilterkwarg passed to$ tmux list-panes -t <window> -f <filter>.- Parameters:
filter (
str,optional) –tmux format expression (
-fflag).Warning
tmux silently expands a malformed filter (unclosed
#{...}, unknown format token) to empty, which the filter treats as false — every row is suppressed and no stderr is emitted. A bad filter is indistinguishable from “filter matched nothing”; verify filter syntax against the FORMATS section oftmux(1).Added in version 0.57.
- Return type:
See also
Window.panesunfiltered
QueryListof every pane in this window (Python-side.filter()runs against this).- Filtering before object creation
when to pick
search_*overQueryList.filter().
Examples
>>> target_pane = window.split() >>> matches = window.search_panes( ... filter=f'#{{m:{target_pane.pane_id},#{{pane_id}}}}' ... ) >>> [p.pane_id for p in matches] == [target_pane.pane_id] True
Execute tmux subcommand within window context.
Automatically binds target by adding
-tfor object’s window ID to the command. Passtargetto keyword arguments to override.Examples
Create a pane from a window:
>>> window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0] '%...'
Magic, directly to a Pane:
>>> Pane.from_pane_id(pane_id=session.cmd( ... 'split-window', '-P', '-F#{pane_id}').stdout[0], server=session.server) Pane(%... Window(@... ...:..., Session($1 libtmux_...)))
Select pane and return selected
Pane.$ tmux select-pane.
Split window on active pane and return the created
Pane.- Parameters:
attach (
bool,optional) – Make new window the current window after creating it, default True.start_directory (
str or PathLike, optional) – Specifies the working directory in which the new window is created.direction (
PaneDirection,optional) – Split in direction. If none is specified, assume down.full_window_split (
bool,optional) – Split across full window width or height, rather than active pane.zoom (
bool,optional) – Expand pane.shell (
str,optional) –Execute a command on splitting the window. The pane will close when the command exits.
NOTE: When this command exits the pane will close. This feature is useful for long-running processes where the closing of the window upon completion is desired.
size (
int,optional) – Cell/row count to occupy with respect to current window.percentage (
int,optional) –Percentage (0-100) of the window to occupy (
-pflag). Mutually exclusive with size.Added in version 0.56.
environment (
dict,optional) – Environmental variables for new pane. Passthrough to-e.empty (
bool,optional) – Create an empty pane with no command (-Eflag) instead of spawning the default shell. Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored.style (
str,optional) – Style for the new pane (-s). Requires tmux 3.7+.active_border_style (
str,optional) – Active-pane border style (-S). Requires tmux 3.7+.inactive_border_style (
str,optional) – Inactive-pane border style (-R). Requires tmux 3.7+.message (
str,optional) – Keep the pane open (until a key is pressed) after exit, showing thisremain-on-exit-formatmessage (-m). Requires tmux 3.7+.keep (
bool,optional) – Keep the pane open until a key is pressed after exit (-k). Requires tmux 3.7+. These 3.7 flags warn and are ignored below 3.7.
- Returns:
The newly created pane.
- Return type:
Create a floating
Panein this window ($ tmux new-pane).Use
split()for a tiled pane. Floating panes require tmux 3.7+; delegates toPane.new_pane()on the active pane.- Parameters:
target (
int or str, optional) – Custom target-pane.start_directory (
str or PathLike, optional) – Working directory for the new pane (-c).attach (
bool,optional) – Make the new pane active, default False (-dotherwise).shell (
str,optional) – Command to run; the pane closes when it exits.environment (
dict,optional) – Environment variables for the new pane (-e).width (
int,optional) – Width in cells (-x).height (
int,optional) – Height in cells (-y).x (
int,optional) – X position in cells (-X).y (
int,optional) – Y position in cells (-Y).zoom (
bool,optional) – Zoom the pane (-Z).empty (
bool,optional) – Create an empty pane with no command (-E).style (
str,optional) – Style for the floating pane (-s).active_border_style (
str,optional) – Border style when the pane is active (-S).inactive_border_style (
str,optional) – Border style when the pane is inactive (-R).message (
str,optional) – Keep the pane open (until a key is pressed) after the command exits, showing thisremain-on-exit-formatmessage (-m).keep (
bool,optional) – Keep the pane open until a key is pressed after exit (-k), using the defaultremain-on-exit-format.
- Returns:
The newly created floating pane.
- Return type:
Examples
>>> from libtmux.common import has_gte_version >>> if has_gte_version("3.7"): ... floating = window.new_pane(width=40, height=10, shell="sleep 5") ... is_floating = floating.pane_floating_flag ... else: ... is_floating = "1" >>> is_floating '1'
Resize tmux window.
- Parameters:
adjustment_direction (
ResizeAdjustmentDirection,optional) – direction to adjust,Up,Down,Left,Right.adjustment (
ResizeAdjustmentDirection,optional)height (
int,optional) –resize-window -ydimensionswidth (
int,optional) –resize-window -xdimensionsexpand (
bool) – expand windowshrink (
bool) – shrink window
- Raises:
- Return type:
Notes
Three types of resizing are available:
Adjustments:
adjustment_directionandadjustment.Manual resizing:
heightand / orwidth.Expand or shrink:
expandorshrink.
Select the last (previously active) pane via
$ tmux last-pane.- Parameters:
- Returns:
The selected pane, or None if no last pane exists.
- Return type:
Paneor None
Examples
>>> pane1 = window.active_pane >>> pane2 = window.split() >>> pane2.select() Pane(...) >>> result = window.last_pane()
Select layout for window.
Wrapper for
$ tmux select-layout <layout>.- Parameters:
layout (
str,optional) –String of the layout, ‘even-horizontal’, ‘tiled’, etc. Entering None (leaving this blank) is same as
select-layoutwith no layout. In recent tmux versions, it picks the most recently set layout.- ’even-horizontal’
Panes are spread out evenly from left to right across the window.
- ’even-vertical’
Panes are spread evenly from top to bottom.
- ’main-horizontal’
A large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom.
- ’main-vertical’
Similar to main-horizontal but the large pane is placed on the left and the others spread from top to bottom along the right.
- ’tiled’
Panes are spread out as evenly as possible over the window in both rows and columns.
- ’custom’
Custom dimensions (see tmux(1) manpages).
spread (
bool,optional) –Spread panes out evenly (
-Eflag).Added in version 0.56.
next_layout (
bool,optional) –Move to the next layout (
-nflag).Added in version 0.56.
previous_layout (
bool,optional) –Move to the previous layout (
-pflag).Added in version 0.56.
- Returns:
Self, for method chaining.
- Return type:
- Raises:
libtmux.exc.LibTmuxException– If tmux returns an error.ValueError– If both layout and a flag (spread, next_layout, previous_layout) are specified.
Cycle to the next layout via
$ tmux next-layout.>>> pane1 = window.active_pane >>> pane2 = window.split() >>> window.next_layout() Window(...)
- Return type:
Cycle to the previous layout via
$ tmux previous-layout.>>> pane1 = window.active_pane >>> pane2 = window.split() >>> window.previous_layout() Window(...)
- Return type:
Link this window to another session via
$ tmux link-window.- Parameters:
target_session (
str or Session) – Target session to link the window to.target_index (
str,optional) – Target window index in the destination session.kill_existing (
bool,optional) – Kill target window if it exists (-kflag).after (
bool,optional) – Insert after the target window (-aflag).before (
bool,optional) – Insert before the target window (-bflag).detach (
bool,optional) – Do not make the linked window active (-dflag).
- Return type:
Examples
>>> w = session.new_window(window_name='link_test') >>> s2 = server.new_session(session_name='link_target') >>> w.link(s2)
Unlink this window from the current session via
$ tmux unlink-window.Examples
>>> w = session.new_window(window_name='unlink_test') >>> s2 = server.new_session(session_name='unlink_s2') >>> w.link(s2) >>> linked = [x for x in s2.windows if x.window_name == 'unlink_test'] >>> linked[0].unlink()
Rotate pane positions in the window via
$ tmux rotate-window.Examples
>>> pane1 = window.active_pane >>> pane2 = window.split() >>> window.rotate() Window(...)
Respawn the window process via
$ tmux respawn-window.- Parameters:
shell (
str,optional) – Shell command to run in the respawned window.start_directory (
str or PathLike, optional) – Working directory for the respawned window (-cflag).environment (
dict,optional) – Environment variables (-eflag).kill (
bool,optional) – Kill the current process before respawning (-kflag). Required if the window is still active.
- Return type:
Examples
>>> window = session.new_window(window_name='respawn_test') >>> window.respawn(kill=True, shell='sh')
Swap this window with another via
$ tmux swap-window.Examples
>>> w1 = session.new_window(window_name='swap_a') >>> w2 = session.new_window(window_name='swap_b') >>> w1_idx = w1.window_index >>> w2_idx = w2.window_index >>> w1.swap(w2) >>> w1.window_index == w2_idx True >>> w2.window_index == w1_idx True
-
method
Display message at window scope via
$ tmux display-message.Like
Pane.display_message()but auto-injects-t @<window-id>instead of a pane id. Window-scoped format reads such as#{window_zoomed_flag}or#{window_active_clients}no longer require dropping toWindow.cmd().- Parameters:
cmd (
str) –Format string to display or evaluate (e.g.
"#{window_zoomed_flag}").Added in version 0.57.
get_text (
bool,optional) –Return tmux’s stdout instead of rendering to the status line (
-pflag).Added in version 0.57.
format_string (
str,optional) –Alternative format template (
-Fflag).Added in version 0.57.
all_formats (
bool,optional) –List all format variables (
-aflag).Added in version 0.57.
verbose (
bool,optional) –Show format variable types (
-vflag).Added in version 0.57.
no_expand (
bool,optional) –Output the literal string without format expansion (
-lflag). Requires tmux 3.4+.Added in version 0.57.
target_client (
str,optional) –Target client (
-cflag).Added in version 0.57.
delay (
int,optional) –Display time in milliseconds (
-dflag).Added in version 0.57.
notify (
bool,optional) –Do not wait for input (
-Nflag).Added in version 0.57.
- Returns:
Message output if
get_textis True, otherwiseNone.- Return type:
Examples
Read the window’s id format:
>>> result = window.display_message("#{window_id}", get_text=True) >>> result[0].startswith("@") True
Check zoom state (a common gap-#670 use case):
>>> result = window.display_message( ... "#{window_zoomed_flag}", get_text=True ... ) >>> result[0] in {"0", "1"} True
Notes
Stderr from tmux is reported via
warnings.warn(), not raised. Callers that want to escalate to an exception can wrap the call inwarnings.catch_warnings()withfilterwarnings("error").Changed in version 0.57: Reports stderr via
warnings.warn()instead of raising.
Rename window.
Examples
>>> window = session.active_window
>>> window.rename_window('My project') Window(@1 1:My project, Session($1 ...))
>>> window.rename_window('New name') Window(@1 1:New name, Session($1 ...))
Kill
Window.$ tmux kill-window.Examples
Kill a window:
>>> window_1 = session.new_window()
>>> window_1 in session.windows True
>>> window_1.kill()
>>> window_1 not in session.windows True
Kill all windows except the current one:
>>> one_window_to_rule_them_all = session.new_window()
>>> other_windows = session.new_window( ... ), session.new_window()
>>> all([w in session.windows for w in other_windows]) True
>>> one_window_to_rule_them_all.kill(all_except=True)
>>> all([w not in session.windows for w in other_windows]) True
>>> one_window_to_rule_them_all in session.windows True
Move current
Windowobject$ tmux move-window.- Parameters:
destination (
str,optional) – Thetarget windowor index to move the window to, default: empty string.session (
str,optional) – Thetarget sessionor index to move the window to, default: current session.after (
bool,optional) –Insert after the target window (
-aflag).Added in version 0.56.
before (
bool,optional) –Insert before the target window (
-bflag).Added in version 0.56.
no_select (
bool,optional) –Do not make the moved window the current window (
-dflag).Added in version 0.56.
kill_target (
bool,optional) –Kill the target window if it exists (
-kflag).Added in version 0.56.
renumber (
bool,optional) –Renumber all windows in sequential order (
-rflag). This is a standalone operation — when used, no move is performed and other parameters are ignored.Added in version 0.56.
- Returns:
Self, for method chaining.
- Return type:
- Raises:
libtmux.exc.LibTmuxException– If tmux returns an error.
Create new window respective of current window’s position.
See also
Examples
>>> window_initial = session.new_window(window_name='Example') >>> window_initial Window(@... 2:Example, Session($1 libtmux_...)) >>> window_initial.window_index '2'
>>> window_before = window_initial.new_window( ... window_name='Window before', direction=WindowDirection.Before) >>> window_initial.refresh() >>> window_before Window(@... 2:Window before, Session($1 libtmux_...)) >>> window_initial Window(@... 3:Example, Session($1 libtmux_...))
>>> window_after = window_initial.new_window( ... window_name='Window after', direction=WindowDirection.After) >>> window_initial.refresh() >>> window_after.refresh() >>> window_after Window(@... 4:Window after, Session($1 libtmux_...)) >>> window_initial Window(@... 3:Example, Session($1 libtmux_...)) >>> window_before Window(@... 2:Window before, Session($1 libtmux_...))
Select window.
To select a window object asynchrously. If a
windowobject exists and is no longer the current window,w.select_window()will makewthe current window.Examples
>>> window = session.active_window >>> new_window = session.new_window() >>> session.refresh() >>> active_windows = [w for w in session.windows if w.window_active == '1']
>>> new_window.window_active == '1' False
>>> new_window.select() Window(...)
>>> new_window.window_active == '1' True
- Return type:
Return attached
Pane.
Alias of
Window.window_height.>>> window.height.isdigit() True
>>> window.height == window.window_height True
Alias of
Window.window_width.>>> window.width.isdigit() True
>>> window.width == window.window_width True
- Return type:
Set option for tmux window. Deprecated by
Window.set_option().Deprecated since version 0.50: Deprecated by
Window.set_option().
Show options for tmux window. Deprecated by
Window.show_options().Deprecated since version 0.50: Deprecated by
Window.show_options().
Return option for target window. Deprecated by
Window.show_option().Deprecated since version 0.50: Deprecated by
Window.show_option().
Return key-based lookup. Deprecated by attributes.
Deprecated since version 0.17: Deprecated by attribute lookup.e.g.
window['window_name']is now accessed viawindow.window_name.
Return pane by id. Deprecated in favor of
panes.get().Deprecated since version 0.16: Deprecated by
panes.get().
Filter through panes, return list of
Pane.Deprecated since version 0.17: Deprecated by
panes.filter().
-
__init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, bracket_paste_flag=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_activity=None, client_cell_height=None, client_cell_width=None, client_control_mode=None, client_created=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_last_session=None, client_mode_format=None, client_name=None, client_pid=None, client_prefix=None, client_readonly=None, client_session=None, client_termfeatures=None, client_termname=None, client_termtype=None, client_tty=None, client_uid=None, client_user=None, client_utf8=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_at_bottom=None, pane_at_left=None, pane_at_right=None, pane_at_top=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_flags=None, pane_floating_flag=None, pane_format=None, pane_height=None, pane_id=None, pane_in_mode=None, pane_index=None, pane_input_off=None, pane_last=None, pane_left=None, pane_marked=None, pane_marked_set=None, pane_mode=None, pane_path=None, pane_pb_progress=None, pane_pb_state=None, pane_pid=None, pane_pipe=None, pane_pipe_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_synchronized=None, pane_tabs=None, pane_title=None, pane_top=None, pane_tty=None, pane_width=None, pane_x=None, pane_y=None, pane_z=None, pane_zoomed_flag=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_format=None, session_group=None, session_group_attached=None, session_group_attached_list=None, session_group_list=None, session_group_many_attached=None, session_group_size=None, session_grouped=None, session_id=None, session_last_attached=None, session_many_attached=None, session_marked=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, synchronized_output_flag=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_clients_list=None, window_active_sessions=None, window_active_sessions_list=None, window_activity=None, window_activity_flag=None, window_bell_flag=None, window_bigger=None, window_cell_height=None, window_cell_width=None, window_end_flag=None, window_flags=None, window_format=None, window_height=None, window_id=None, window_index=None, window_last_flag=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_silence_flag=None, window_stack_index=None, window_start_flag=None, window_visible_layout=None, window_width=None, window_zoomed_flag=None, wrap_flag=None, default_option_scope=¶
OptionScope.Window, default_hook_scope=OptionScope.Window)method[source]method[source]__init__(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, bracket_paste_flag=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_activity=None, client_cell_height=None, client_cell_width=None, client_control_mode=None, client_created=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_last_session=None, client_mode_format=None, client_name=None, client_pid=None, client_prefix=None, client_readonly=None, client_session=None, client_termfeatures=None, client_termname=None, client_termtype=None, client_tty=None, client_uid=None, client_user=None, client_utf8=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_at_bottom=None, pane_at_left=None, pane_at_right=None, pane_at_top=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_flags=None, pane_floating_flag=None, pane_format=None, pane_height=None, pane_id=None, pane_in_mode=None, pane_index=None, pane_input_off=None, pane_last=None, pane_left=None, pane_marked=None, pane_marked_set=None, pane_mode=None, pane_path=None, pane_pb_progress=None, pane_pb_state=None, pane_pid=None, pane_pipe=None, pane_pipe_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_synchronized=None, pane_tabs=None, pane_title=None, pane_top=None, pane_tty=None, pane_width=None, pane_x=None, pane_y=None, pane_z=None, pane_zoomed_flag=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_format=None, session_group=None, session_group_attached=None, session_group_attached_list=None, session_group_list=None, session_group_many_attached=None, session_group_size=None, session_grouped=None, session_id=None, session_last_attached=None, session_many_attached=None, session_marked=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, synchronized_output_flag=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_clients_list=None, window_active_sessions=None, window_active_sessions_list=None, window_activity=None, window_activity_flag=None, window_bell_flag=None, window_bigger=None, window_cell_height=None, window_cell_width=None, window_end_flag=None, window_flags=None, window_format=None, window_height=None, window_id=None, window_index=None, window_last_flag=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_silence_flag=None, window_stack_index=None, window_start_flag=None, window_visible_layout=None, window_width=None, window_zoomed_flag=None, wrap_flag=None, default_option_scope=¶OptionScope.Window, default_hook_scope=OptionScope.Window) When not a user (custom) option, scope can be implied.
- Parameters:
server (
Server)default_option_scope (
OptionScope|None)default_hook_scope (
OptionScope|None)
- Return type:
Refresh dataclass fields from a single
list-*row.Used by the public
refresh()methods onPane,Window,Session, andClient. Each subclass guards its identity field (pane_id,window_id,session_id,client_name) againstNonebefore delegating here; this base method enforces the same precondition explicitly so the guarantee survivespython -O, where anassertwould be stripped.- Raises:
ValueError– Whenobj_idisNone. Surfaces a clear error underpython -O, matching the contract of the publicrefresh()methods.- Parameters:
- Return type:
Return value for the hook.
- Parameters:
hook (
str)global_ (
bool)scope (
OptionScope|_DefaultOptionScope|None)
- Raises:
- Return type:
Return option value for the target.
todo: test and return True/False for on/off string
- Parameters:
- Raises:
- Return type:
ConvertedValue|None
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer().cmd('new-session', '-d') <libtmux.common.tmux_cmd object at ...>
>>> MyServer()._show_option('exit-unattached', global_=True) False
Return raw option output for target.
- Parameters:
- Raises:
- Return type:
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer().cmd('new-session', '-d') <libtmux.common.tmux_cmd object at ...>
>>> MyServer()._show_option_raw('exit-unattached', global_=True) <libtmux.common.tmux_cmd object at ...>
>>> MyServer()._show_option_raw('exit-unattached', global_=True).stdout ['exit-unattached off']
>>> isinstance(MyServer()._show_option_raw('exit-unattached', global_=True).stdout, list) True
>>> isinstance(MyServer()._show_option_raw('exit-unattached', global_=True).stdout[0], str) True
Return a dict of options for the target.
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer()._show_options() {...}
Return dict of options for the target.
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer()._show_options_dict() {...}
>>> isinstance(MyServer()._show_options_dict(), dict) True
Return a dict of options for the target.
- Parameters:
g (
bool,optional) –Deprecated since version 0.50.0: Use
global_instead.quiet (
bool,optional) –Suppress errors silently (
-qflag).Added in version 0.56.
values_only (
bool,optional) –Return only option values without names (
-vflag).Added in version 0.56.
scope (
OptionScope|_DefaultOptionScope|None)
- Return type:
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer()._show_options_raw() <libtmux.common.tmux_cmd object at ...>
>>> MyServer()._show_options_raw().stdout [...]
Resolve tmux_bin from self (Server) or self.server (Session/Window/Pane).
Filter through panes, return first
Pane.Deprecated since version 0.17: Slated to be removed in favor of
panes.get().
Run a hook immediately. Useful for testing.
- Parameters:
hook (
str)scope (
OptionScope|_DefaultOptionScope|None)
- Return type:
Self
Set hook for tmux target.
Wraps
$ tmux set-hook <hook> <value>.- Parameters:
- Raises:
- Return type:
Self
Set multiple indexed hooks at once.
- Parameters:
hook (
str) – Hook name, e.g. ‘session-renamed’values (
HookValues) – Values to set. Can be: - dict[int, str]: {0: ‘cmd1’, 1: ‘cmd2’} - explicit indices - SparseArray[str]: preserves indices from another hook - list[str]: [‘cmd1’, ‘cmd2’] - sequential indices starting at 0clear_existing (
bool) – If True, unset all existing hook values firstscope (
OptionScope|None) – Scope for the hook
- Returns:
Returns self for method chaining.
- Return type:
Self
Examples
Set hooks with explicit indices:
>>> session.set_hooks('session-renamed', { ... 0: 'display-message "hook 0"', ... 1: 'display-message "hook 1"', ... }) Session($...)
>>> hooks = session.show_hook('session-renamed') >>> sorted(hooks.keys()) [0, 1]
>>> session.unset_hook('session-renamed') Session($...)
Set hooks from a list (sequential indices):
>>> session.set_hooks('after-new-window', [ ... 'select-pane -t 0', ... 'send-keys "clear" Enter', ... ]) Session($...)
>>> hooks = session.show_hook('after-new-window') >>> sorted(hooks.keys()) [0, 1]
Replace all existing hooks with
clear_existing=True:>>> session.set_hooks( ... 'session-renamed', ... {0: 'display-message "new"'}, ... clear_existing=True, ... ) Session($...)
>>> hooks = session.show_hook('session-renamed') >>> sorted(hooks.keys()) [0]
>>> session.unset_hook('session-renamed') Session($...)
>>> session.unset_hook('after-new-window') Session($...)
Set option for tmux target.
Wraps
$ tmux set-option <option> <value>.- Parameters:
option (
str) – option to set, e.g. ‘aggressive-resize’value (
str) – option value. True/False will turn in ‘on’ and ‘off’, also accepts string of ‘on’ or ‘off’ directly.deprecated: (
..) – 0.28: Deprecated bygfor global, useglobal_instead.scope (
OptionScope|_DefaultOptionScope|None)
- Raises:
- Return type:
Self
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope >>> from libtmux._internal.sparse_array import SparseArray
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer().set_option('escape-time', 1250) <libtmux.options.MyServer object at ...>
>>> MyServer()._show_option('escape-time') 1250
>>> MyServer().set_option('escape-time', 495) <libtmux.options.MyServer object at ...>
>>> MyServer()._show_option('escape-time') 495
Return value for a hook.
For array hooks (e.g.,
session-renamed), returns aSparseArraywith hook values at their original indices. Use.keys()for indices and.values()for values.- Parameters:
hook (
str) – Hook name to queryglobal_ (
bool)scope (
OptionScope|_DefaultOptionScope|None)
- Returns:
Hook value. For array hooks, returns SparseArray.
- Return type:
str|int|SparseArray[str] |None- Raises:
Examples
>>> session.set_hook('session-renamed[0]', 'display-message "test"') Session($...)
>>> hooks = session.show_hook('session-renamed') >>> isinstance(hooks, SparseArray) True
>>> sorted(hooks.keys()) [0]
>>> session.unset_hook('session-renamed') Session($...)
Return a dict of hooks for the target.
- Parameters:
global (
bool,optional) – Pass-gflag for global hooks, default False.scope (
OptionScope|_DefaultOptionScope|None,optional) – Hook scope (Server/Session/Window/Pane), defaults to object’s scope.
- Returns:
Dictionary mapping hook names to their values.
- Return type:
HookDict
Examples
>>> session.set_hook('session-renamed[0]', 'display-message "test"') Session($...)
>>> hooks = session.show_hooks() >>> isinstance(hooks, dict) True
>>> 'session-renamed[0]' in hooks True
>>> session.unset_hook('session-renamed') Session($...)
Return option value for the target.
- Parameters:
- Raises:
- Return type:
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer().cmd('new-session', '-d') <libtmux.common.tmux_cmd object at ...>
>>> MyServer().show_option('exit-unattached', global_=True) False
Return all options for the target.
- Parameters:
global (
bool,optional) – Pass-gflag for global options, default False.scope (
OptionScope|_DefaultOptionScope|None,optional) – Option scope (Server/Session/Window/Pane), defaults to object’s scope.include_hooks (
bool,optional) – Include hook options (-Hflag).include_inherited (
bool,optional) – Include inherited options (-Aflag).quiet (
bool,optional) –Suppress errors silently (
-qflag).Added in version 0.56.
global_ (
bool)
- Returns:
Dictionary with all options, arrays exploded and values converted.
- Return type:
ExplodedComplexUntypedOptionsDict- Raises:
Examples
>>> options = server.show_options() >>> isinstance(options, dict) True
>>> 'buffer-limit' in options True
Unset hook for tmux target.
Wraps
$ tmux set-hook -u <hook>/$ tmux set-hook -U <hook>- Parameters:
hook (
str) – hook to unset, e.g. ‘after-show-environment’scope (
OptionScope|_DefaultOptionScope|None)
- Raises:
- Return type:
Self
Unset option for tmux target.
Wraps
$ tmux set-option -u <option>/$ tmux set-option -U <option>- Parameters:
option (
str) – option to unset, e.g. ‘aggressive-resize’scope (
OptionScope|_DefaultOptionScope|None)
- Raises:
- Return type:
Self
Examples
>>> import typing as t >>> from libtmux.common import tmux_cmd >>> from libtmux.constants import OptionScope
>>> class MyServer(OptionsMixin): ... socket_name = server.socket_name ... def cmd(self, cmd: str, *args: object): ... cmd_args: t.List[t.Union[str, int]] = [cmd] ... if self.socket_name: ... cmd_args.insert(0, f"-L{self.socket_name}") ... cmd_args.insert(0, "-f/dev/null") ... return tmux_cmd(*cmd_args, *args) ... ... default_option_scope = OptionScope.Server
>>> MyServer().set_option('escape-time', 1250) <libtmux.options.MyServer object at ...>
>>> MyServer()._show_option('escape-time') 1250
>>> MyServer().unset_option('escape-time') <libtmux.options.MyServer object at ...>
>>> isinstance(MyServer()._show_option('escape-time'), int) True
Property / alias to return
_list_panes().Deprecated since version 0.17: Slated to be removed in favor of
panes.