Sessions#

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

class libtmux.Session(server: libtmux.server.Server, session_id: str, **kwargs: Any)[source]#

Bases: libtmux.common.TmuxMappingObject, libtmux.common.TmuxRelationalObject[libtmux.window.Window, libtmux.common.WindowDict], libtmux.common.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.

class Mapping#

Bases: Collection

A Mapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for __getitem__, __iter__, and __len__.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.#: D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.

items() → a set-like object providing a view on D's items#: D.items() -> a set-like object providing a view on D’s items

keys() → a set-like object providing a view on D's keys#: D.keys() -> a set-like object providing a view on D’s keys

values() → an object providing a view on D's values#: D.values() -> an object providing a view on D’s values

_add_option#

property _info#

_is_protocol = False#

_list_windows()[source]#

property _windows#: Property / alias to return Session._list_windows().

attach_session()[source]#: Return $ tmux attach-session aka alias: $ tmux attach.

property attached_pane#: Return active Pane object.

property attached_window#

Return active Window object.

Return type:: Window

child_id_attribute = window_id#: Unique child ID key for TmuxRelationalObject

children#

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

Return server.cmd().

Return type:: server.cmd

Notes

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

find_where(attrs: D)[source]#: Return object on first match.

Changed in version 0.4: Renamed from .findWhere to .find_where.

formatter_prefix = session_#: Namespace used for TmuxMappingObject

get(k[, d]) → D[k] if k in D, else d. d defaults to None.[source]#: D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.

get_by_id(id: str)[source]#

Return object based on child_id_attribute.

Parameters:: val (str) –
Return type:: object

Notes

Based on `.get()`_ from `backbone.js`_.

getenv(name: str)[source]#

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

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

New in version 0.13.

Parameters:: name (str) – the environment variable name. such as ‘PATH’.
Returns:: Value of environment variable
Return type:: str

items() → a set-like object providing a view on D's items[source]#: D.items() -> a set-like object providing a view on D’s items

keys()[source]#: Return list of keys.

kill_session()[source]#: $ tmux kill-session.

kill_window(target_window: Optional[str] = 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.

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

list_windows()[source]#

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

Return type:: Window

new_window(window_name: Optional[str] = None, start_directory: None = None, attach: bool = True, window_index: str = '', window_shell: None = 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.

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

remove_environment(name: str)[source]#

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

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

rename_session(new_name: str)[source]#

Rename session and return new Session object.

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

select_window(target_window: Union[str, int])[source]#

Return Window selected via $ tmux select-window.

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

Notes

server#: libtmux.server.Server session is linked to

set_environment(name: str, value: str)[source]#

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

Parameters:

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

set_option(option: str, value: Union[str, int], _global: bool = False)[source]#

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

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_environment()[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_option(option: str, _global: bool = False)[source]#

Return a list of options for the window.

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.

show_options(_global: Optional[bool] = 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().

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.

switch_client()[source]#

Switch client to this session.

Raises:: exc.LibTmuxException –

unset_environment(name: str)[source]#

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

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

values() → an object providing a view on D's values[source]#: D.values() -> an object providing a view on D’s values

where(attrs: D, first: Literal[True])[source]#

Return objects matching child objects properties.

Parameters:: attrs (dict) – tmux properties to match values of
Return type:: list of objects, or one object if first=True

property windows#: Property / alias to return Session.list_windows().