Sessions

class libtmux.Session
class libtmux.Session

Bases: Obj, EnvironmentMixin, OptionsMixin, HooksMixin

tmux(1) Session [session_manual].

Holds Window objects.

Reading it. Every field is a tmux format token read when the session was listed or last refreshed, and is None when tmux gave no value. refresh() rewrites the fields in place and returns None.

Finding it. from_session_id() asks tmux for one session and raises TmuxObjectDoesNotExist when it is gone. from_env() resolves the session of the pane this process runs inside, through $TMUX_PANE, and raises NotInsideTmux outside one.

Finding what is inside. Each access reads tmux again and returns a QueryList. Unlike sessions, these raise LibTmuxException when tmux writes to stderr. active_window raises NoActiveWindow or MultipleActiveWindows unless exactly one window is active. active_pane is the active window’s active pane, or None.

Moving the selection. Each returns the window that is now active and raises LibTmuxException when tmux refuses.

Adding windows. new_window() returns the new Window. It is created detached unless attach=True, and it takes the next free index unless window_index names one.

Changing it. rename_session() raises BadSessionName for an empty name or one holding a period or colon, refreshes the session and returns it. kill() closes the linked windows and detaches every client, and group=True needs tmux 3.7 or later, below which it warns and is ignored.

Options, hooks and environment. An option or hook call leaves the scope flag off by default, which tmux resolves as session scope. The setters return the session, so calls chain, and an unknown or invalid name raises OptionError or one of its subclasses. The environment calls act on this session and raise ValueError when tmux reports an error.

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.