Sessions¶

Exist inside Servers
Contain Windows (which contain Panes)
Identified by $, e.g. $313

class libtmux.Session ¶ class[source] class[source] class libtmux.Session ¶

Bases: Obj, EnvironmentMixin, OptionsMixin, HooksMixin

Holds Window objects.

Parameters:: server (Server) – Server the session was queried from, and the connection every command and refresh runs over.

Examples

>>> session
Session($1 ...)

>>> session.windows
[Window(@1 ...:..., Session($1 ...)]

>>> session.active_window
Window(@1 ...:..., Session($1 ...))

>>> session.active_pane
Pane(%1 Window(@1 ...:..., Session($1 ...)))

The session can be used as a context manager to ensure proper cleanup:

>>> with server.new_session() as session:
...     window = session.new_window()
...     # Do work with the window
...     # Session will be killed automatically when exiting the context

References

[session_manual]

tmux session. openbsd manpage for TMUX(1).

“When tmux is started it creates a new session with a single window and displays it on screen…”

“A session is a single collection of pseudo terminals under the management of tmux. Each session has one or more windows linked to it.”

https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.

from_session_id(server, session_id) ¶ classmethod method[source] classmethod method[source] from_session_id(server, session_id) ¶

Create Session from existing session_id.

Parameters:

server (Server) – The tmux server holding the session.
session_id (str) – Session id, e.g. "$1".

Return type:

Session

Raises:

TmuxObjectDoesNotExist – When no such session exists on a reachable server.

Examples

>>> Session.from_session_id(
...     server=session.server, session_id=session.session_id
... )
Session($1 ...)

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

Return the session this process’s pane belongs to.

The session id baked into $TMUX is frozen at pane spawn and goes stale the moment the pane’s window is moved or linked elsewhere, so it is never read. tmux is asked instead: the pane row that Pane.from_env() fetches is stamped with the session tmux considers canonical for that pane’s window.

Parameters:

env (typing.Mapping, optional) – Environment to read. Defaults to os.environ.

Return type:

Session

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 session_id. Surfaces a clear error under python -O, where an assert would be stripped.

Examples

Even a deliberately wrong session id in $TMUX cannot mislead it:

>>> env = {"TMUX": f"{socket_path},1,999", "TMUX_PANE": pane.pane_id}
>>> Session.from_env(env).session_id == session.session_id
True

>>> Session.from_env(env)
Session($1 ...)

Added in version 0.62.

search_windows(*, filter=None) ¶ method[source] method[source] search_windows(*, filter=None) ¶

Windows in this session, optionally filtered by tmux.

Like Session.windows but with a filter kwarg passed to $ tmux list-windows -t <session> -f <filter>.

Parameters:

filter (str, optional) –

tmux format expression (-f flag).

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 of tmux(1).

Added in version 0.57.

Return type:

QueryList[Window]

See also

Session.windows: unfiltered QueryList of every window in this session (Python-side .filter() runs against this).
Filtering before object creation: when to pick search_* over QueryList.filter().

Examples

>>> _ = session.new_window(window_name='gap7s_target')
>>> _ = session.new_window(window_name='other_window')
>>> matches = session.search_windows(filter='#{m:gap7s_*,#{window_name}}')
>>> [w.window_name for w in matches]
['gap7s_target']

search_panes(*, filter=None) ¶ method[source] method[source] search_panes(*, filter=None) ¶

Panes in this session, optionally filtered by tmux.

Like Session.panes but with a filter kwarg passed to $ tmux list-panes -s -t <session> -f <filter>.

Parameters:

filter (str, optional) –

tmux format expression (-f flag).

Warning

Added in version 0.57.

Return type:

QueryList[Pane]

See also

Session.panes: unfiltered QueryList of every pane in this session (Python-side .filter() runs against this).
Filtering before object creation: when to pick search_* over QueryList.filter().

Examples

>>> target_pane = session.active_window.split()
>>> matches = session.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 session context.

Automatically binds target by adding -t for object’s session ID to the command. Pass target to keyword arguments to override.

Examples

>>> session.cmd('new-window', '-P').stdout[0]
'libtmux...:....0'

From raw output to an enriched Window object:

>>> Window.from_window_id(window_id=session.cmd(
... 'new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
Window(@... ...:..., Session($1 libtmux_...))

Parameters:

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

Return type:

server.cmd()

Notes

Changed in version 0.34: Passing target by -t is ignored. Use target keyword argument instead.

Changed in version 0.8: Renamed from .tmux to .cmd.

detach_client(*, shell_command=None) ¶ method[source] method[source] detach_client(*, shell_command=None) ¶

Detach every client attached to this session.

Maps to $ tmux detach-client -s <session_id> — the only detach-client flag group that is genuinely session-scoped.

Parameters:: shell_command (str, optional) – Run a shell command on the detached client(s) after detach (-E flag).
Return type:: None

See also

Server.detach_client(): detach a specific client by name (-t flag) — server-wide client lookup, not session-scoped.
Server.detach_all_clients(): detach every client on the server (-a flag).

Examples

>>> with control_mode() as ctl:
...     session.detach_client()

kill(all_except=None, clear=None, group=None) ¶ method[source] method[source] kill(all_except=None, clear=None, group=None) ¶

Kill Session, closes linked windows and detach all clients.

$ tmux kill-session.

Parameters:

all_except (bool, optional) – Kill all sessions in server except this one.
clear (bool, optional) – Clear alerts (bell, activity, or silence) in all windows.
group (bool, optional) – Kill all sessions in this session’s group (-g flag). Requires tmux 3.7+. If used with tmux < 3.7, a warning is issued and the flag is ignored.

Return type:

None

Examples

Kill a session:

>>> session_1 = server.new_session()

>>> session_1 in server.sessions
True

>>> session_1.kill()

>>> session_1 not in server.sessions
True

Kill all sessions except the current one:

>>> one_session_to_rule_them_all = server.new_session()

>>> other_sessions = server.new_session(
...     ), server.new_session()

>>> all([w in server.sessions for w in other_sessions])
True

>>> one_session_to_rule_them_all.kill(all_except=True)

>>> all([w not in server.sessions for w in other_sessions])
True

>>> one_session_to_rule_them_all in server.sessions
True

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

Create new window, returns new Window.

By default, this will make the window active. For the new window to be created and not set to current, pass in attach=False.

Parameters:

window_name (str, optional)
start_directory (str, optional) – working directory in which the new window is created.
attach (bool, optional) – make new window the current window after creating it, default True.
window_index (str) – create the new window at the given index position. Default is empty string which will create the window in the next available position.
window_shell (str, optional) –
execute a command on starting the window. The window will close when the command exits.

Note

When this command exits the window will close. This feature is useful for long-running processes where the closing of the window upon completion is desired.
direction (WindowDirection, optional) – Insert window before or after target window.
target_window (str, optional) – Used by Window.new_window() to specify the target window.
kill_existing (bool, optional) –
Destroy the window at the target index if it already exists (-k flag).

Added in version 0.56.
select_existing (bool, optional) –
If a window with the given name already exists, select it instead of creating a new one (-S flag).

Added in version 0.56.
versionchanged: (..) – 0.28.0: attach default changed from True to False.
environment (dict[str, str] | None)

Return type:

Window

See also

Window.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 = session.new_window(
... window_name='Window before', direction=WindowDirection.Before)
>>> window_initial.refresh()
>>> window_before
Window(@... 1:Window before, Session($1 libtmux_...))
>>> window_initial
Window(@... 3:Example, Session($1 libtmux_...))

>>> window_after = session.new_window(
... window_name='Window after', direction=WindowDirection.After)
>>> window_initial.refresh()
>>> window_after.refresh()
>>> window_after
Window(@... 3:Window after, Session($1 libtmux_...))
>>> window_initial
Window(@... 4:Example, Session($1 libtmux_...))
>>> window_before
Window(@... 1:Window before, Session($1 libtmux_...))

Returns:

The newly created window.

Return type:

Window

Parameters:

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

__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=None, default_hook_scope=None) ¶ 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=None, default_hook_scope=None) ¶

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_environment(name, value, *, expand_format=None, hidden=None) ¶ method[source] method[source] set_environment(name, value, *, expand_format=None, hidden=None) ¶

Set environment $ tmux set-environment <name> <value>.

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.
value (str) – Environment value.
expand_format (bool, optional) –
Expand tmux format strings in the value (-F flag).

Added in version 0.56.
hidden (bool, optional) –
Mark the variable as hidden (-h flag).

Added in version 0.56.

Raises:

ValueError – If tmux returns an error.

Return type:

None

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