Sessions#

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

class libtmux.Session(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_cell_height=None, client_cell_width=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_name=None, client_pid=None, client_termname=None, client_tty=None, client_uid=None, client_user=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_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_height=None, pane_id=None, pane_index=None, pane_left=None, pane_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_tabs=None, pane_top=None, pane_tty=None, pane_width=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_group=None, session_group_attached=None, session_group_list=None, session_group_size=None, session_id=None, session_last_attached=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_sessions=None, window_activity=None, window_cell_height=None, window_cell_width=None, window_height=None, window_id=None, window_index=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_stack_index=None, window_width=None, wrap_flag=None)[source]#

Bases: Obj, EnvironmentMixin

A tmux(1) Session [session_manual].

Holds Window objects.

Parameters:: server (Server) –

Examples

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

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

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

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

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.

property windows: QueryList[Window]#

Windows belonging session.

Can be accessed via .windows.get() and .windows.filter()

property panes: QueryList[Pane]#

Panes belonging session.

Can be accessed via .panes.get() and .panes.filter()

cmd(*args, **kwargs)[source]#

Return server.cmd().

Return type:: tmux_cmd
Return type:: server.cmd

Notes

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

set_option(option, value, _global=False)[source]#

Set option $ tmux set-option <option> <value>.

Return type:

Session

Parameters:

option (str) – the window option. such as ‘default-shell’.
value (str, int, or bool) – True/False will turn in ‘on’ and ‘off’. You can also enter ‘on’ or ‘off’ directly.
_global (bool, optional) – check for option globally across all servers (-g)

Raises:

exc.OptionError –
exc.InvalidOption –

Notes

show_options(_global=False)[source]#

Return a dict of options for the window.

For familiarity with tmux, the option option param forwards to pick a single option, forwarding to Session.show_option().

Return type:: Dict[str, Union[str, int]]
Parameters:: _global (bool, optional) – Pass -g flag for global variable (server-wide)
Return type:: dict

Notes

Uses _global for keyword name instead of global to avoid colliding with reserved keyword.

show_option(option, _global=False)[source]#

Return a list of options for the window.

Return type:

Union[str, int, bool, None]

Parameters:

option (str) – option name
_global (bool, optional) – use global option scope, same as -g

Return type:

str, int, or bool

Raises:

exc.OptionError –
exc.InvalidOption –

Notes

Uses _global for keyword name instead of global to avoid colliding with reserved keyword.

Test and return True/False for on/off string.

select_window(target_window)[source]#

Return Window selected via $ tmux select-window.

Return type:: Window
Parameters:: window (str) – target_window also ‘last-window’ (-l), ‘next-window’ (-n), or ‘previous-window’ (-p)
Return type:: Window

Notes

property attached_window: Window#: Return active Window object.

attach_session()[source]#

Return $ tmux attach-session aka alias: $ tmux attach.

Return type:: Session

kill_session()[source]#

$ tmux kill-session.

Return type:: None

switch_client()[source]#

Switch client to this session.

Return type:: Session
Raises:: exc.LibTmuxException –

rename_session(new_name)[source]#

Rename session and return new Session object.

Return type:: Session
Parameters:: new_name (str) – new session name
Raises:: exc.BadSessionName –

new_window(window_name=None, start_directory=None, attach=True, window_index='', window_shell=None, environment=None)[source]#

Return Window from $ tmux 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.

Return type:

Window

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.

Return type:

Window

kill_window(target_window=None)[source]#

Close a tmux window, and all panes inside it, $ tmux kill-window

Kill the current window or the window at target-window. removing it from any sessions to which it is linked.

Return type:: None
Parameters:: target_window (str, optional) – window to kill

property attached_pane: Pane | None#: Return active Pane object.

property id: str | None#

Alias of Session.session_id

>>> session.id
'$1'

>>> session.id == session.session_id
True

property name: str | None#

Alias of Session.session_name

>>> session.name
'libtmux_...'

>>> session.name == session.session_name
True

get(key, default=None)[source]#