Windows¶

Exist inside Sessions
Contain Panes
Identified by @, e.g. @313

class libtmux.Window ¶ class[source] class[source] class libtmux.Window ¶

Bases: Obj, OptionsMixin, HooksMixin

Holds Pane objects.

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() ¶ method[source] method[source] refresh() ¶

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. See Window.from_window_id().

Raises:

ValueError – When window_id is unset. Surfaces a clear error under python -O, where an assert would be stripped.
TmuxObjectDoesNotExist – When the window no longer exists.
LibTmuxException – When tmux itself is unreachable.

Return type:

None

Examples

>>> window.refresh()
>>> window.window_id
'@1'

from_window_id(server, window_id) ¶ classmethod method[source] classmethod method[source] from_window_id(server, window_id) ¶

Create Window from existing window_id.

tmux’s cmd_find routes a -t target by sigil, so an @-id handed to list-windows resolves 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:

server (Server) – The tmux server holding the window.
window_id (str) – Window id, e.g. "@3".

Return type:

Window

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 ...))

from_env(env=None) ¶ classmethod method[source] classmethod method[source] from_env(env=None) ¶

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 to os.environ.

Return type:

Window

Raises:

NotInsideTmux – When $TMUX or $TMUX_PANE is unset or malformed.
TmuxObjectDoesNotExist – When the pane named by $TMUX_PANE is gone.
LibTmuxException – When the server named by $TMUX is unreachable.
ValueError – When the resolved pane carries no window_id. Surfaces a clear error under python -O, where an assert would 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.

property linked_sessions: QueryList[Session] ¶ property property property linked_sessions: QueryList[Session] ¶

Every session this window is reachable from.

Usually one, and then this is just Window.session in a list. link-window and grouped sessions (tmux new-session -t existing) make it more: the window is genuinely in each of them at once, and Window.session returns the session recorded on this Window instance.

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.

Return type:: QueryList of Session

See also

Window.panes: unfiltered QueryList of every pane in this window (Python-side .filter() runs against this).
Filtering before object creation: when to pick search_* over QueryList.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

cmd(cmd, *args, target=None) ¶ method[source] method[source] cmd(cmd, *args, target=None) ¶

Execute tmux subcommand within window context.

Automatically binds target by adding -t for object’s window ID to the command. Pass target to 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_...)))

Parameters:

target (str, optional) – Optional custom target override. By default, the target is the window ID.
cmd (str)
args (Any)

Return type:

server.cmd()

split(target=None, start_directory=None, attach=False, direction=None, full_window_split=None, zoom=None, shell=None, size=None, percentage=None, environment=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶ method[source] method[source] split(target=None, start_directory=None, attach=False, direction=None, full_window_split=None, zoom=None, shell=None, size=None, percentage=None, environment=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶

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 (-p flag). 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 (-E flag) 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 this remain-on-exit-format message (-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.
target (int | str | None)

Returns:

The newly created pane.

Return type:

Pane

new_pane(target=None, start_directory=None, attach=False, shell=None, environment=None, width=None, height=None, x=None, y=None, zoom=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶ method[source] method[source] new_pane(target=None, start_directory=None, attach=False, shell=None, environment=None, width=None, height=None, x=None, y=None, zoom=None, empty=None, style=None, active_border_style=None, inactive_border_style=None, message=None, keep=None) ¶

Create a floating Pane in this window ($ tmux new-pane).

Use split() for a tiled pane. Floating panes require tmux 3.7+; delegates to Pane.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 (-d otherwise).
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 this remain-on-exit-format message (-m).
keep (bool, optional) – Keep the pane open until a key is pressed after exit (-k), using the default remain-on-exit-format.

Returns:

The newly created floating pane.

Return type:

Pane

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(adjustment_direction=None, adjustment=None, height=None, width=None, expand=None, shrink=None) ¶ method[source] method[source] resize(adjustment_direction=None, adjustment=None, height=None, width=None, expand=None, shrink=None) ¶

Resize tmux window.

Parameters:

adjustment_direction (ResizeAdjustmentDirection, optional) – direction to adjust, Up, Down, Left, Right.
adjustment (ResizeAdjustmentDirection, optional)
height (int, optional) – resize-window -y dimensions
width (int, optional) – resize-window -x dimensions
expand (bool) – expand window
shrink (bool) – shrink window

Raises:

Return type:

Window

Notes

Three types of resizing are available:

Adjustments: adjustment_direction and adjustment.
Manual resizing: height and / or width.
Expand or shrink: expand or shrink.

last_pane(*, disable_input=None, enable_input=None, keep_zoom=None) ¶ method[source] method[source] last_pane(*, disable_input=None, enable_input=None, keep_zoom=None) ¶

Select the last (previously active) pane via $ tmux last-pane.

Parameters:

disable_input (bool, optional) –
Disable input to the pane (-d flag).

Added in version 0.56.
enable_input (bool, optional) –
Enable input to the pane (-e flag).

Added in version 0.56.
keep_zoom (bool, optional) –
Keep the window zoomed if zoomed (-Z flag).

Added in version 0.56.

Returns:

The selected pane, or None if no last pane exists.

Return type:

Pane or None

Examples

>>> pane1 = window.active_pane
>>> pane2 = window.split()
>>> pane2.select()
Pane(...)
>>> result = window.last_pane()

select_layout(layout=None, *, spread=None, next_layout=None, previous_layout=None) ¶ method[source] method[source] select_layout(layout=None, *, spread=None, next_layout=None, previous_layout=None) ¶

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-layout with 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 (-E flag).

Added in version 0.56.
next_layout (bool, optional) –
Move to the next layout (-n flag).

Added in version 0.56.
previous_layout (bool, optional) –
Move to the previous layout (-p flag).

Added in version 0.56.

Returns:

Self, for method chaining.

Return type:

Window

Raises:

libtmux.exc.LibTmuxException – If tmux returns an error.
ValueError – If both layout and a flag (spread, next_layout, previous_layout) are specified.

link(target_session, *, target_index=None, kill_existing=None, after=None, before=None, detach=None) ¶ method[source] method[source] link(target_session, *, target_index=None, kill_existing=None, after=None, before=None, detach=None) ¶

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 (-k flag).
after (bool, optional) – Insert after the target window (-a flag).
before (bool, optional) – Insert before the target window (-b flag).
detach (bool, optional) – Do not make the linked window active (-d flag).

Return type:

None

Examples

>>> w = session.new_window(window_name='link_test')
>>> s2 = server.new_session(session_name='link_target')
>>> w.link(s2)

unlink(*, kill_if_last=None) ¶ method[source] method[source] unlink(*, kill_if_last=None) ¶

Unlink this window from the current session via $ tmux unlink-window.

Parameters:: kill_if_last (bool, optional) – Kill the window if it is the last window in the session (-k).
Return type:: None

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(*, upward=None, downward=None, keep_zoom=None) ¶ method[source] method[source] rotate(*, upward=None, downward=None, keep_zoom=None) ¶

Rotate pane positions in the window via $ tmux rotate-window.

Parameters:

upward (bool, optional) – Rotate upward (-U flag).
downward (bool, optional) – Rotate downward (-D flag).
keep_zoom (bool, optional) – Keep the window zoomed if zoomed (-Z flag).

Returns:

Self, for method chaining.

Return type:

Window

Examples

>>> pane1 = window.active_pane
>>> pane2 = window.split()
>>> window.rotate()
Window(...)

respawn(*, shell=None, start_directory=None, environment=None, kill=None) ¶ method[source] method[source] respawn(*, shell=None, start_directory=None, environment=None, kill=None) ¶

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 (-c flag).
environment (dict, optional) – Environment variables (-e flag).
kill (bool, optional) – Kill the current process before respawning (-k flag). Required if the window is still active.

Return type:

None

Examples

>>> window = session.new_window(window_name='respawn_test')
>>> window.respawn(kill=True, shell='sh')

swap(target, *, detach=None) ¶ method[source] method[source] swap(target, *, detach=None) ¶

Swap this window with another via $ tmux swap-window.

Parameters:

target (str or Window) – Target window to swap with. Can be a window ID string or Window.
detach (bool, optional) – Do not change the active window (-d flag).

Return type:

None

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

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 to Window.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 (-p flag).

Added in version 0.57.
format_string (str, optional) –
Alternative format template (-F flag).

Added in version 0.57.
all_formats (bool, optional) –
List all format variables (-a flag).

Added in version 0.57.
verbose (bool, optional) –
Show format variable types (-v flag).

Added in version 0.57.
no_expand (bool, optional) –
Output the literal string without format expansion (-l flag). Requires tmux 3.4+.

Added in version 0.57.
target_client (str, optional) –
Target client (-c flag).

Added in version 0.57.
delay (int, optional) –
Display time in milliseconds (-d flag).

Added in version 0.57.
notify (bool, optional) –
Do not wait for input (-N flag).

Added in version 0.57.

Returns:

Message output if get_text is True, otherwise None.

Return type:

list[str] | None

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 in warnings.catch_warnings() with filterwarnings("error").

Changed in version 0.57: Reports stderr via warnings.warn() instead of raising.

kill(all_except=None) ¶ method[source] method[source] kill(all_except=None) ¶

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

Parameters:: all_except (bool | None)
Return type:: None

move_window(destination='', session=None, *, after=None, before=None, no_select=None, kill_target=None, renumber=None) ¶ method[source] method[source] move_window(destination='', session=None, *, after=None, before=None, no_select=None, kill_target=None, renumber=None) ¶

Move current Window object $ tmux move-window.

Parameters:

destination (str, optional) – The target window or index to move the window to, default: empty string.
session (str, optional) – The target session or index to move the window to, default: current session.
after (bool, optional) –
Insert after the target window (-a flag).

Added in version 0.56.
before (bool, optional) –
Insert before the target window (-b flag).

Added in version 0.56.
no_select (bool, optional) –
Do not make the moved window the current window (-d flag).

Added in version 0.56.
kill_target (bool, optional) –
Kill the target window if it exists (-k flag).

Added in version 0.56.
renumber (bool, optional) –
Renumber all windows in sequential order (-r flag). 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:

Window

Raises:

libtmux.exc.LibTmuxException – If tmux returns an error.

new_window(window_name=None, *, start_directory=None, attach=False, window_index='', window_shell=None, environment=None, direction=None) ¶ method[source] method[source] new_window(window_name=None, *, start_directory=None, attach=False, window_index='', window_shell=None, environment=None, direction=None) ¶

Create new window respective of current window’s position.

See also

Session.new_window()

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_...))

Parameters:

window_name (str | None)
start_directory (None)
attach (bool)
window_index (str)
window_shell (str | None)
environment (dict[str, str] | None)
direction (WindowDirection | None)

Return type:

Window

select() ¶ method[source] method[source] select() ¶

Select window.

To select a window object asynchrously. If a window object exists and is no longer the current window, w.select_window() will make w the 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:: Window

split_window(target=None, start_directory=None, attach=False, vertical=True, shell=None, size=None, percent=None, environment=None) ¶ deprecated method[source] deprecated method[source] split_window(target=None, start_directory=None, attach=False, vertical=True, shell=None, size=None, percent=None, environment=None) ¶

Split window and return the created Pane.

Notes

Deprecated since version 0.33.0: Deprecated in favor of split().

Changed in version 0.28.0: attach default changed from True to False.

Deprecated since version 0.28.0: percent=25 deprecated in favor of size="25%".

Parameters:

target (int | str | None)
start_directory (StrPath | None)
attach (bool)
vertical (bool)
shell (str | None)
size (str | int | None)
percent (int | None)
environment (dict[str, str] | None)

Return type:

Pane

__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)
active_window_index (str | None)
alternate_saved_x (str | None)
alternate_saved_y (str | None)
bracket_paste_flag (str | None)
buffer_name (str | None)
buffer_sample (str | None)
buffer_size (str | None)
client_activity (str | None)
client_cell_height (str | None)
client_cell_width (str | None)
client_control_mode (str | None)
client_created (str | None)
client_discarded (str | None)
client_flags (str | None)
client_height (str | None)
client_key_table (str | None)
client_last_session (str | None)
client_mode_format (str | None)
client_name (str | None)
client_pid (str | None)
client_prefix (str | None)
client_readonly (str | None)
client_session (str | None)
client_termfeatures (str | None)
client_termname (str | None)
client_termtype (str | None)
client_tty (str | None)
client_uid (str | None)
client_user (str | None)
client_utf8 (str | None)
client_width (str | None)
client_written (str | None)
command_list_alias (str | None)
command_list_name (str | None)
command_list_usage (str | None)
config_files (str | None)
copy_cursor_line (str | None)
copy_cursor_word (str | None)
copy_cursor_x (str | None)
copy_cursor_y (str | None)
current_file (str | None)
cursor_character (str | None)
cursor_flag (str | None)
cursor_x (str | None)
cursor_y (str | None)
history_bytes (str | None)
history_limit (str | None)
history_size (str | None)
insert_flag (str | None)
keypad_cursor_flag (str | None)
keypad_flag (str | None)
last_window_index (str | None)
line (str | None)
mouse_all_flag (str | None)
mouse_any_flag (str | None)
mouse_button_flag (str | None)
mouse_sgr_flag (str | None)
mouse_standard_flag (str | None)
next_session_id (str | None)
origin_flag (str | None)
pane_active (str | None)
pane_at_bottom (str | None)
pane_at_left (str | None)
pane_at_right (str | None)
pane_at_top (str | None)
pane_bg (str | None)
pane_bottom (str | None)
pane_current_command (str | None)
pane_current_path (str | None)
pane_dead (str | None)
pane_dead_signal (str | None)
pane_dead_status (str | None)
pane_dead_time (str | None)
pane_fg (str | None)
pane_flags (str | None)
pane_floating_flag (str | None)
pane_format (str | None)
pane_height (str | None)
pane_id (str | None)
pane_in_mode (str | None)
pane_index (str | None)
pane_input_off (str | None)
pane_last (str | None)
pane_left (str | None)
pane_marked (str | None)
pane_marked_set (str | None)
pane_mode (str | None)
pane_path (str | None)
pane_pb_progress (str | None)
pane_pb_state (str | None)
pane_pid (str | None)
pane_pipe (str | None)
pane_pipe_pid (str | None)
pane_right (str | None)
pane_search_string (str | None)
pane_start_command (str | None)
pane_start_path (str | None)
pane_synchronized (str | None)
pane_tabs (str | None)
pane_title (str | None)
pane_top (str | None)
pane_tty (str | None)
pane_width (str | None)
pane_x (str | None)
pane_y (str | None)
pane_z (str | None)
pane_zoomed_flag (str | None)
pid (str | None)
scroll_position (str | None)
scroll_region_lower (str | None)
scroll_region_upper (str | None)
search_match (str | None)
selection_end_x (str | None)
selection_end_y (str | None)
selection_start_x (str | None)
selection_start_y (str | None)
session_activity (str | None)
session_alerts (str | None)
session_attached (str | None)
session_attached_list (str | None)
session_created (str | None)
session_format (str | None)
session_group (str | None)
session_group_attached (str | None)
session_group_attached_list (str | None)
session_group_list (str | None)
session_group_many_attached (str | None)
session_group_size (str | None)
session_grouped (str | None)
session_id (str | None)
session_last_attached (str | None)
session_many_attached (str | None)
session_marked (str | None)
session_name (str | None)
session_path (str | None)
session_stack (str | None)
session_windows (str | None)
socket_path (str | None)
start_time (str | None)
synchronized_output_flag (str | None)
uid (str | None)
user (str | None)
version (str | None)
window_active (str | None)
window_active_clients (str | None)
window_active_clients_list (str | None)
window_active_sessions (str | None)
window_active_sessions_list (str | None)
window_activity (str | None)
window_activity_flag (str | None)
window_bell_flag (str | None)
window_bigger (str | None)
window_cell_height (str | None)
window_cell_width (str | None)
window_end_flag (str | None)
window_flags (str | None)
window_format (str | None)
window_height (str | None)
window_id (str | None)
window_index (str | None)
window_last_flag (str | None)
window_layout (str | None)
window_linked (str | None)
window_linked_sessions (str | None)
window_linked_sessions_list (str | None)
window_marked_flag (str | None)
window_name (str | None)
window_offset_x (str | None)
window_offset_y (str | None)
window_panes (str | None)
window_raw_flags (str | None)
window_silence_flag (str | None)
window_stack_index (str | None)
window_start_flag (str | None)
window_visible_layout (str | None)
window_width (str | None)
window_zoomed_flag (str | None)
wrap_flag (str | None)
default_option_scope (OptionScope | None)
default_hook_scope (OptionScope | None)

Return type:

None

_refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None) ¶ method[source] method[source] _refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None) ¶

Refresh dataclass fields from a single list-* row.

Used by the public refresh() methods on Pane, Window, Session, and Client. Each subclass guards its identity field (pane_id, window_id, session_id, client_name) against None before delegating here; this base method enforces the same precondition explicitly so the guarantee survives python -O, where an assert would be stripped.

Raises:

ValueError – When obj_id is None. Surfaces a clear error under python -O, matching the contract of the public refresh() methods.

Parameters:

obj_key (str)
obj_id (str)
list_cmd (ListCmd)
list_extra_args (ListExtraArgs)

Return type:

None

_show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶ deprecated method[source] deprecated method[source] _show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶

Return option value for the target.

todo: test and return True/False for on/off string

Parameters:

option (str)
g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)
ignore_errors (bool | None)
include_hooks (bool | None)
include_inherited (bool | None)

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

_show_option_raw(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶ deprecated method[source] deprecated method[source] _show_option_raw(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶

Return raw option output for target.

Parameters:

option (str)
g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)
ignore_errors (bool | None)
include_hooks (bool | None)
include_inherited (bool | None)

Raises:

Return type:

tmux_cmd

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

_show_options(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶ deprecated method[source] deprecated method[source] _show_options(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶

Return a dict of options for the target.

Parameters:

g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)
include_hooks (bool | None)
include_inherited (bool | None)
quiet (bool | None)

Return type:

ExplodedComplexUntypedOptionsDict

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()
{...}

_show_options_dict(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶ deprecated method[source] deprecated method[source] _show_options_dict(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶

Return dict of options for the target.

Parameters:

g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)
include_hooks (bool | None)
include_inherited (bool | None)
quiet (bool | None)

Return type:

UntypedOptionsDict

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

_show_options_raw(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None, values_only=None) ¶ deprecated method[source] deprecated method[source] _show_options_raw(g=False, global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None, values_only=None) ¶

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 (-q flag).

Added in version 0.56.
values_only (bool, optional) –
Return only option values without names (-v flag).

Added in version 0.56.
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)
include_hooks (bool | None)
include_inherited (bool | None)

Return type:

tmux_cmd

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
[...]

set_hook(hook, value, unset=None, run=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] set_hook(hook, value, unset=None, run=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

Set hook for tmux target.

Wraps $ tmux set-hook <hook> <value>.

Parameters:

hook (str) – hook to set, e.g. ‘aggressive-resize’
value (int | str) – hook command.
unset (bool | None)
run (bool | None)
append (bool | None)
g (bool | None)
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)

Raises:

Return type:

Self

set_hooks(hook, values, *, clear_existing=False, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] set_hooks(hook, values, *, clear_existing=False, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

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 0
clear_existing (bool) – If True, unset all existing hook values first
global (bool | None) – Use global hooks
scope (OptionScope | None) – Scope for the hook
global_ (bool | None)

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(option, value, _format=None, prevent_overwrite=None, ignore_errors=None, suppress_warnings=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] set_option(option, value, _format=None, prevent_overwrite=None, ignore_errors=None, suppress_warnings=None, append=None, g=None, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

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 by g for global, use global_ instead.
_format (bool | None)
prevent_overwrite (bool | None)
ignore_errors (bool | None)
suppress_warnings (bool | None)
append (bool | None)
g (bool | None)
global_ (bool | None)
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

show_hook(hook, global_=False, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] show_hook(hook, global_=False, scope=DEFAULT_OPTION_SCOPE) ¶

Return value for a hook.

For array hooks (e.g., session-renamed), returns a SparseArray with hook values at their original indices. Use .keys() for indices and .values() for values.

Parameters:

hook (str) – Hook name to query
global_ (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($...)

show_hooks(global_=False, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] show_hooks(global_=False, scope=DEFAULT_OPTION_SCOPE) ¶

Return a dict of hooks for the target.

Parameters:

global (bool, optional) – Pass -g flag for global hooks, default False.
scope (OptionScope | _DefaultOptionScope | None, optional) – Hook scope (Server/Session/Window/Pane), defaults to object’s scope.
global_ (bool | None)

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($...)

show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶ deprecated method[source] deprecated method[source] show_option(option, global_=False, g=False, scope=DEFAULT_OPTION_SCOPE, ignore_errors=None, include_hooks=None, include_inherited=None) ¶

Return option value for the target.

Parameters:

option (str)
g (bool, optional) –

Deprecated since version 0.50.0: Use global_ instead.
global_ (bool)
scope (OptionScope | _DefaultOptionScope | None)
ignore_errors (bool | None)
include_hooks (bool | None)
include_inherited (bool | None)

Raises:

Return type:

Any | 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

show_options(global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶ method[source] method[source] show_options(global_=False, scope=DEFAULT_OPTION_SCOPE, include_hooks=None, include_inherited=None, quiet=None) ¶

Return all options for the target.

Parameters:

global (bool, optional) – Pass -g flag 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 (-H flag).
include_inherited (bool, optional) – Include inherited options (-A flag).
quiet (bool, optional) –
Suppress errors silently (-q flag).

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(hook, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] unset_hook(hook, global_=None, scope=DEFAULT_OPTION_SCOPE) ¶

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’
global_ (bool | None)
scope (OptionScope | _DefaultOptionScope | None)

Raises:

Return type:

Self

unset_option(option, unset_panes=None, global_=None, ignore_errors=None, scope=DEFAULT_OPTION_SCOPE) ¶ method[source] method[source] unset_option(option, unset_panes=None, global_=None, ignore_errors=None, scope=DEFAULT_OPTION_SCOPE) ¶

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’
unset_panes (bool | None)
global_ (bool | None)
ignore_errors (bool | None)
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