Sessions

class libtmux.Session
class[source]

Bases: Obj, EnvironmentMixin, OptionsMixin, HooksMixin

tmux(1) Session [session_manual].

Holds Window objects.

Parameters:

server (Server)

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.

default_option_scope: OptionScope | None = None
attribute
default_hook_scope: OptionScope | None = None
attribute
server: Server
attribute
refresh()
method[source]

Refresh session attributes from tmux.

Return type:

None

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

Create Session from existing session_id.

Parameters:
Return type:

Session

property windows: QueryList[Window]
property

Windows contained by session.

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

property panes: QueryList[Pane]
property

Panes contained by session’s windows.

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

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

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.

select_window(target_window)
method[source]

Select window and return the selected window.

Parameters:

  • window (str) – target_window can also be ‘last-window’ (-l), ‘next-window’ (-n), or ‘previous-window’ (-p)

  • target_window (str | int)

Return type:

Window

property active_pane: Pane | None
property

Return the active Pane object.

property active_window: Window
property

Return the active Window object.

attach(exit_=None, flags_=None)
method[source]

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

Examples

>>> session = server.new_session()

>>> session not in server.attached_sessions
True
Parameters:
Return type:

Session

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

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.

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

Switch client to session.

Raises:

exc.LibTmuxException –

Return type:

Session

rename_session(new_name)
method[source]

Rename session and return new Session object.

Parameters:

new_name (str) – new session name

Raises:

exc.BadSessionName –

Return type:

Session

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

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.

  • 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:
kill_window(target_window=None)
method[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.

Parameters:

target_window (str | int, optional) – Window to kill.

Raises:

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

Return type:

None

property id: str | None
property

Alias of Session.session_id.

>>> session.id
'$1'

>>> session.id == session.session_id
True
property name: str | None
property

Alias of Session.session_name.

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

>>> session.name == session.session_name
True
property attached_pane: Pane | None
deprecated property

Return the active Pane object.

Notes

Deprecated since version 0.31: Deprecated in favor of active_pane().

property attached_window: Window
deprecated property

Return the active Window object.

Notes

Deprecated since version 0.31: Deprecated in favor of active_window().

attach_session()
deprecated method[source]

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

Notes

Deprecated since version 0.30: Deprecated in favor of attach().

Return type:

Session

kill_session()
deprecated method[source]

Destroy session.

Notes

Deprecated since version 0.30: Deprecated in favor of kill().

Return type:

None

get(key, default=None)
deprecated method[source]

Return key-based lookup. Deprecated by attributes.

Deprecated since version 0.17: Deprecated by attribute lookup.e.g. session['session_name'] is now accessed via session.session_name.

Parameters:
Return type:

Any

get_by_id(session_id)
deprecated method[source]

Return window by id. Deprecated in favor of windows.get().

Deprecated since version 0.16: Deprecated by windows.get().

Parameters:

session_id (str)

Return type:

Window | None

where(kwargs)
deprecated method[source]

Filter through windows, return list of Window.

Deprecated since version 0.17: Deprecated by windows.filter().

Parameters:

kwargs (dict[str, Any])

Return type:

list[Window]

find_where(kwargs)
deprecated method[source]

Filter through windows, return first Window.

Deprecated since version 0.17: Slated to be removed in favor of windows.get().

Parameters:

kwargs (dict[str, Any])

Return type:

Window | None

_list_windows()
deprecated method[source]

Return list of windows (deprecated in favor of windows).

Deprecated since version 0.17: Slated to be removed in favor of windows.

Return type:

list[WindowDict]

property _windows: list[dict[str, Any]]
deprecated property

Property / alias to return Session._list_windows().

Deprecated since version 0.17: Slated to be removed in favor of windows.

__init__(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_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_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_title=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, default_option_scope=None, default_hook_scope=None)
method[source]

When not a user (custom) option, scope can be implied.

Parameters:
Return type:

None

_add_option = None
attribute
_refresh(obj_key, obj_id, list_cmd='list-panes', list_extra_args=None)
method[source]
Parameters:

  • obj_key (str)

  • obj_id (str)

  • list_cmd (ListCmd)

  • list_extra_args (ListExtraArgs)

Return type:

None

_show_hook(hook, global_=False, scope=<libtmux.constants._DefaultOptionScope object>)
method[source]

Return value for the hook.

Parameters:
Raises:
Return type:

list[str] | None

_show_option(option, global_=False, g=False, scope=<libtmux.constants._DefaultOptionScope object>, ignore_errors=None, include_hooks=None, include_inherited=None)
deprecated method[source]

Return option value for the target.

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

Parameters:
Raises:
Return type:

ConvertedValue | None

Examples

>>> import typing as t
>>> from libtmux.common import tmux_cmd
>>> from libtmux.constants import OptionScope

>>> class MyServer(OptionsMixin):
...     socket_name = server.socket_name
...     def cmd(self, cmd: str, *args: object):
...         cmd_args: t.List[t.Union[str, int]] = [cmd]
...         if self.socket_name:
...             cmd_args.insert(0, f"-L{self.socket_name}")
...         cmd_args.insert(0, "-f/dev/null")
...         return tmux_cmd(*cmd_args, *args)
...
...     default_option_scope = OptionScope.Server

>>> MyServer().cmd('new-session', '-d')
<libtmux.common.tmux_cmd object at ...>

>>> MyServer()._show_option('exit-unattached', global_=True)
False
_show_option_raw(option, global_=False, g=False, scope=<libtmux.constants._DefaultOptionScope object>, ignore_errors=None, include_hooks=None, include_inherited=None)
deprecated method[source]

Return raw option output for target.

Parameters:
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=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)
deprecated method[source]

Return a dict of options for the target.

Parameters:
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=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)
deprecated method[source]

Return dict of options for the target.

Parameters:
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=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)
deprecated method[source]

Return a dict of options for the target.

Parameters:
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
[...]
property _tmux_bin: str | None
property

Resolve tmux_bin from self (Server) or self.server (Session/Window/Pane).

active_window_index: str | None = None
attribute
alternate_saved_x: str | None = None
attribute
alternate_saved_y: str | None = None
attribute
buffer_name: str | None = None
attribute
buffer_sample: str | None = None
attribute
buffer_size: str | None = None
attribute
client_cell_height: str | None = None
attribute
client_cell_width: str | None = None
attribute
client_discarded: str | None = None
attribute
client_flags: str | None = None
attribute
client_height: str | None = None
attribute
client_key_table: str | None = None
attribute
client_name: str | None = None
attribute
client_pid: str | None = None
attribute
client_termname: str | None = None
attribute
client_tty: str | None = None
attribute
client_uid: str | None = None
attribute
client_user: str | None = None
attribute
client_width: str | None = None
attribute
client_written: str | None = None
attribute
command_list_alias: str | None = None
attribute
command_list_name: str | None = None
attribute
command_list_usage: str | None = None
attribute
config_files: str | None = None
attribute
copy_cursor_line: str | None = None
attribute
copy_cursor_word: str | None = None
attribute
copy_cursor_x: str | None = None
attribute
copy_cursor_y: str | None = None
attribute
current_file: str | None = None
attribute
cursor_character: str | None = None
attribute
cursor_flag: str | None = None
attribute
cursor_x: str | None = None
attribute
cursor_y: str | None = None
attribute
getenv(name)
method[source]

Show environment variable $ tmux show-environment -t [session] <name>.

Return the value of a specific variable if the name is specified.

Added in version 0.13.

Parameters:

name (str) – the environment variable name. such as ‘PATH’.

Returns:

Value of environment variable

Return type:

str

history_bytes: str | None = None
attribute
history_limit: str | None = None
attribute
history_size: str | None = None
attribute
insert_flag: str | None = None
attribute
keypad_cursor_flag: str | None = None
attribute
keypad_flag: str | None = None
attribute
last_window_index: str | None = None
attribute
line: str | None = None
attribute
list_windows()
deprecated method[source]

Return a list of Window from the tmux(1) session.

Deprecated since version 0.17: Slated to be removed in favor of windows.

Return type:

list[Window]

mouse_all_flag: str | None = None
attribute
mouse_any_flag: str | None = None
attribute
mouse_button_flag: str | None = None
attribute
mouse_sgr_flag: str | None = None
attribute
mouse_standard_flag: str | None = None
attribute
next_session_id: str | None = None
attribute
origin_flag: str | None = None
attribute
pane_active: str | None = None
attribute
pane_at_bottom: str | None = None
attribute
pane_at_left: str | None = None
attribute
pane_at_right: str | None = None
attribute
pane_at_top: str | None = None
attribute
pane_bg: str | None = None
attribute
pane_bottom: str | None = None
attribute
pane_current_command: str | None = None
attribute
pane_current_path: str | None = None
attribute
pane_dead_signal: str | None = None
attribute
pane_dead_status: str | None = None
attribute
pane_dead_time: str | None = None
attribute
pane_fg: str | None = None
attribute
pane_height: str | None = None
attribute
pane_id: str | None = None
attribute
pane_index: str | None = None
attribute
pane_left: str | None = None
attribute
pane_pid: str | None = None
attribute
pane_right: str | None = None
attribute
pane_search_string: str | None = None
attribute
pane_start_command: str | None = None
attribute
pane_start_path: str | None = None
attribute
pane_tabs: str | None = None
attribute
pane_title: str | None = None
attribute
pane_top: str | None = None
attribute
pane_tty: str | None = None
attribute
pane_width: str | None = None
attribute
pid: str | None = None
attribute
remove_environment(name)
method[source]

Remove environment variable $ tmux set-environment -r <name>.

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.

Raises:

ValueError – If tmux returns an error.

Return type:

None

run_hook(hook, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)
method[source]

Run a hook immediately. Useful for testing.

Parameters:
Return type:

Self

scroll_position: str | None = None
attribute
scroll_region_lower: str | None = None
attribute
scroll_region_upper: str | None = None
attribute
search_match: str | None = None
attribute
selection_end_x: str | None = None
attribute
selection_end_y: str | None = None
attribute
selection_start_x: str | None = None
attribute
selection_start_y: str | None = None
attribute
session_activity: str | None = None
attribute
session_alerts: str | None = None
attribute
session_attached: str | None = None
attribute
session_attached_list: str | None = None
attribute
session_created: str | None = None
attribute
session_group: str | None = None
attribute
session_group_attached: str | None = None
attribute
session_group_list: str | None = None
attribute
session_group_size: str | None = None
attribute
session_id: str | None = None
attribute
session_last_attached: str | None = None
attribute
session_name: str | None = None
attribute
session_path: str | None = None
attribute
session_stack: str | None = None
attribute
session_windows: str | None = None
attribute
set_environment(name, value)
method[source]

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

Parameters:

  • name (str) – The environment variable name, e.g. ‘PATH’.

  • value (str) – Environment value.

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=<libtmux.constants._DefaultOptionScope object>)
method[source]

Set hook for tmux target.

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

Parameters:
Raises:
Return type:

Self

set_hooks(hook, values, *, clear_existing=False, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)
method[source]

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=<libtmux.constants._DefaultOptionScope object>)
method[source]

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

Show environment $ tmux show-environment -t [session].

Return dict of environment variables for the session.

Changed in version 0.13: Removed per-item lookups. Use libtmux.common.EnvironmentMixin.getenv().

Returns:

environmental variables in dict, if no name, or str if name entered.

Return type:

dict

show_hook(hook, global_=False, scope=<libtmux.constants._DefaultOptionScope object>)
method[source]

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:
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=<libtmux.constants._DefaultOptionScope object>)
method[source]

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=<libtmux.constants._DefaultOptionScope object>, ignore_errors=None, include_hooks=None, include_inherited=None)
deprecated method[source]

Return option value for the target.

Parameters:
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=<libtmux.constants._DefaultOptionScope object>, include_hooks=None, include_inherited=None)
method[source]

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

  • 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
socket_path: str | None = None
attribute
start_time: str | None = None
attribute
uid: str | None = None
attribute
unset_environment(name)
method[source]

Unset environment variable $ tmux set-environment -u <name>.

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.

Raises:

ValueError – If tmux returns an error.

Return type:

None

unset_hook(hook, global_=None, scope=<libtmux.constants._DefaultOptionScope object>)
method[source]

Unset hook for tmux target.

Wraps $ tmux set-hook -u <hook> / $ tmux set-hook -U <hook>

Parameters:
Raises:
Return type:

Self

unset_option(option, unset_panes=None, global_=None, ignore_errors=None, scope=<libtmux.constants._DefaultOptionScope object>)
method[source]

Unset option for tmux target.

Wraps $ tmux set-option -u <option> / $ tmux set-option -U <option>

Parameters:
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
user: str | None = None
attribute
version: str | None = None
attribute
window_active: str | None = None
attribute
window_active_clients: str | None = None
attribute
window_active_sessions: str | None = None
attribute
window_activity: str | None = None
attribute
window_cell_height: str | None = None
attribute
window_cell_width: str | None = None
attribute
window_height: str | None = None
attribute
window_id: str | None = None
attribute
window_index: str | None = None
attribute
window_layout: str | None = None
attribute
window_linked: str | None = None
attribute
window_linked_sessions: str | None = None
attribute
window_linked_sessions_list: str | None = None
attribute
window_marked_flag: str | None = None
attribute
window_name: str | None = None
attribute
window_offset_x: str | None = None
attribute
window_offset_y: str | None = None
attribute
window_panes: str | None = None
attribute
window_raw_flags: str | None = None
attribute
window_stack_index: str | None = None
attribute
window_width: str | None = None
attribute
wrap_flag: str | None = None
attribute
hooks: Hooks
attribute
property children: QueryList[Window]
deprecated property

Was used by TmuxRelationalObject (but that’s longer used in this class).

Deprecated since version 0.17: Slated to be removed in favor of windows.