Sessions

• Exist inside Servers

• Contain Windows (which contain Panes)

• Identified by $, e.g. $313

class libtmux.Session(server=None, **kwargs)

Bases: libtmux.common.TmuxMappingObject, libtmux.common.TmuxRelationalObject, libtmux.common.EnvironmentMixin

A tmux(1) Session [session_manual].

Holds Window objects.

Parameters:

server (Server) –

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.

__marker

_add_option

property _info(self)

_list_windows(self)

property _windows(self)

Property / alias to return Session._list_windows().

attach_session(self)

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

property attached_pane(self)

Return active Pane object.

property attached_window(self)

Return active Window object.

Return type:

Window

child_id_attribute = window_id

children

clear() → None.  Remove all items from D.

D.clear() -> None. Remove all items from D.

cmd(self, *args, **kwargs)

Return server.cmd().

Return type:

server.cmd

Notes

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

find_where(self, attrs)

Return object on first match.

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

formatter_prefix = session_

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.

get_by_id(self, id)

Return object based on child_id_attribute.

Parameters:

val (str) –

Return type:

object

Notes

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

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(self)

Return list of keys.

kill_session(self)

$ tmux kill-session.

kill_window(self, target_window=None)

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(self)

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

Return type:

Window

new_window(self, window_name=None, start_directory=None, attach=True, window_index='', window_shell=None)

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

pop(k[, d]) → v, remove specified key and return the corresponding value.

D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty.

remove_environment(self, name)

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

Parameters:

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

rename_session(self, new_name: str)

Rename session and return new Session object.

Parameters:

new_name (str) – new session name

Return type:

Session

Raises:

exc.BadSessionName –

select_window(self, target_window: str)

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

set_environment(self, name, value)

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

Parameters:

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

• option (str) – environment value.

set_option(self, option, value, _global=False)

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

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D

show_environment(self, name=None)

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

Return dict of environment variables for the session or the value of a specific variable if the name is specified.

Parameters:

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

Returns:

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

Return type:

str or dict

show_option(self, option, _global=False)

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(self, option=None, _global=False)

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:

• option (str, optional) – name of option, e.g. ‘visual-silence’. Defaults to None, which returns all options.

• _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(self)

Switch client to this session.

Raises:

exc.LibTmuxException –

unset_environment(self, name)

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

Parameters:

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

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

D.update([E, ]**F) -> None. Update D from mapping/iterable E and F. If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

D.values() -> an object providing a view on D’s values

where(self, attrs, first=False)

Return objects matching child objects properties.

Parameters:

attrs (dict) – tmux properties to match values of

Return type:

list

property windows(self)

Property / alias to return Session.list_windows().