Servers¶

Identified by socket path and socket name
May have >1 servers running of tmux at the same time.
Contain Sessions (which contain Windows, which contain Panes)

tmux initializes a server automatically on first running (e.g. executing tmux)

class libtmux.Server[source]¶

Bases: EnvironmentMixin

tmux(1) Server [server_manual].

Server.sessions [Session, …]
- Session.windows [Window, …]
  - Window.panes [Pane, …]
    - Pane

When instantiated stores information on live, running tmux server.

Parameters:

socket_name (str, optional) –
socket_path (str, optional) –
config_file (str, optional) –
colors (str, optional) –

Examples

>>> server
Server(socket_name=libtmux_test...)

>>> server.sessions
[Session($1 ...)]

>>> server.sessions[0].windows
[Window(@1 1:..., Session($1 ...))]

>>> server.sessions[0].active_window
Window(@1 1:..., Session($1 ...))

>>> server.sessions[0].active_pane
Pane(%1 Window(@1 1:..., Session($1 ...)))

References

[server_manual]

CLIENTS AND SESSIONS. openbsd manpage for TMUX(1): “The tmux server manages clients, sessions, windows and panes. Clients are attached to sessions to interact with them, either when they are created with the new-session command, or later with the attach-session command. Each session has one or more windows linked into it. Windows may be linked to multiple sessions and are made up of one or more panes, each of which contains a pseudo terminal.”

https://man.openbsd.org/tmux.1#CLIENTS_AND_SESSIONS. Accessed April 1st, 2018.

child_id_attribute = 'session_id'¶: Unique child ID used by TmuxRelationalObject

formatter_prefix = 'server_'¶: Namespace used for TmuxMappingObject

__init__(socket_name=None, socket_path=None, config_file=None, colors=None, **kwargs)[source]¶

Parameters:

socket_name (str | None) –
socket_path (str | Path | None) –
config_file (str | None) –
colors (int | None) –
kwargs (Any) –

Return type:

None

socket_name = None¶: Passthrough to [-L socket-name]

socket_path = None¶: Passthrough to [-S socket-path]

config_file = None¶: Passthrough to [-f file]

colors = None¶: -2 or -8

is_alive()[source]¶

Return True if tmux server alive.

Return type:: bool

>>> tmux = Server(socket_name="no_exist")
>>> assert not tmux.is_alive()

raise_if_dead()[source]¶

Raise if server not connected.

>>> tmux = Server(socket_name="no_exist")
>>> try:
...     tmux.raise_if_dead()
... except Exception as e:
:rtype: :sphinx_autodoc_typehints_type:`\:py\:obj\:\`None\``

… print(type(e)) <class ‘subprocess.CalledProcessError’>

Return type:: None

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

Execute tmux command respective of socket name and file, return output.

Return type:

tmux_cmd

Parameters:

cmd (str) –
args (Any) –
target (str | int | None) –

Examples

>>> server.cmd('display-message', 'hi')
<libtmux.common.tmux_cmd object at ...>

New session:

>>> server.cmd('new-session', '-d', '-P', '-F#{session_id}').stdout[0]
'$2'

>>> session.cmd('new-window', '-P').stdout[0]
'libtmux...:2.0'

Output of tmux -L … new-window -P -F#{window_id} to a Window object:

>>> Window.from_window_id(window_id=session.cmd(
... 'new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
Window(@4 3:..., Session($1 libtmux_...))

Create a pane from a window:

>>> window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0]
'%5'

Output of tmux -L … split-window -P -F#{pane_id} to a Pane object:

>>> Pane.from_pane_id(pane_id=window.cmd(
... 'split-window', '-P', '-F#{pane_id}').stdout[0], server=window.server)
Pane(%... Window(@... ...:..., Session($1 libtmux_...)))

Parameters:

target (str, optional) – Optional custom target.
cmd (str) –
args (Any) –

Return type:

common.tmux_cmd

Notes

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

property attached_sessions: List[Session]¶

Return active :class:`Session`s.

Examples

>>> server.attached_sessions
[]

Return type:: list of Session

has_session(target_session, exact=True)[source]¶

Return True if session exists.

Return type:

bool

Parameters:

target_session (str) – session name
exact (bool) – match the session name exactly. tmux uses fnmatch by default. Internally prepends = to the session in $ tmux has-session. tmux 2.1 and up only.

Raises:

exc.BadSessionName –

Return type:

bool

kill()[source]¶

Kill tmux server.

>>> svr = Server(socket_name="testing")
:rtype: :sphinx_autodoc_typehints_type:`\:py\:obj\:\`None\``

>>> svr
Server(socket_name=testing)

>>> svr.new_session()
Session(...)

>>> svr.is_alive()
True

>>> svr.kill()

>>> svr.is_alive()
False

Return type:: None

kill_session(target_session)[source]¶

Kill tmux session.

Return type:: Server
Parameters:: target_session (str, optional) – target_session: str. note this accepts fnmatch(3). ‘asdf’ will kill ‘asdfasd’.
Return type:: Server
Raises:: exc.BadSessionName –

switch_client(target_session)[source]¶

Switch tmux client.

Return type:: None
Parameters:: target_session (str) – name of the session. fnmatch(3) works.
Raises:: exc.BadSessionName –

attach_session(target_session=None)[source]¶

Attach tmux session.

Return type:: None
Parameters:: target_session (str) – name of the session. fnmatch(3) works.
Raises:: exc.BadSessionName –

new_session(session_name=None, kill_session=False, attach=False, start_directory=None, window_name=None, window_command=None, x=None, y=None, environment=None, *args, **kwargs)[source]¶

Create new session, returns new Session.

Uses -P flag to print session info, -F for return formatting returns new Session object.

$ tmux new-session -d will create the session in the background $ tmux new-session -Ad will move to the session name if it already exists. todo: make an option to handle this.

Return type:

Session

Parameters:

session_name (str, optional) –
```
$ tmux new-session -s <session_name>
```
attach (bool, optional) –
create session in the foreground. attach=False is equivalent to:
```
$ tmux new-session -d
```
kill_session (bool, optional) – Kill current session if $ tmux has-session. Useful for testing workspaces.
start_directory (str, optional) – specifies the working directory in which the new session is created.
window_name (str, optional) –
```
$ tmux new-session -n <window_name>
```
window_command (str, optional) – execute a command on starting the session. 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.
x ([int, str], optional) – Force the specified width instead of the tmux default for a detached session
y ([int, str], optional) – Force the specified height instead of the tmux default for a detached session
environment (Dict[str, str] | None) –
args (Any) –
kwargs (Any) –

Return type:

Session

Raises:

exc.BadSessionName –

Examples

Sessions can be created without a session name (0.14.2+):

>>> server.new_session()
Session($2 2)

Creating them in succession will enumerate IDs (via tmux):

>>> server.new_session()
Session($3 3)

With a session_name:

>>> server.new_session(session_name='my session')
Session($4 my session)

property sessions: QueryList[Session]¶

Sessions contained in server.

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

property windows: QueryList[Window]¶

Windows contained in server’s sessions.

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

property panes: QueryList[Pane]¶

Panes contained in tmux server (across all windows in all sessions).

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

kill_server()[source]¶

Kill tmux server.

Return type:: None

Notes

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

_list_panes()[source]¶

Return list of panes in dict form.

Retrieved from $ tmux(1) list-panes stdout.

The list is derived from stdout in util.tmux_cmd which wraps subprocess.Popen. :rtype: List[Dict[str, Any]]

Deprecated since version 0.16: Deprecated in favor of panes.

Return type:: List[Dict[str, Any]]

getenv(name)[source]¶

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

Return the value of a specific variable if the name is specified. :rtype: Union[str, bool, None]

New in version 0.13.

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

remove_environment(name)[source]¶

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

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

set_environment(name, value)[source]¶

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

Return type:

None

Parameters:

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

show_environment()[source]¶

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

Return dict of environment variables for the session. :rtype: Dict[str, Union[bool, str]]

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

unset_environment(name)[source]¶

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

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

_update_panes()[source]¶

Update internal pane data and return self for chainability. :rtype: Server

Deprecated since version 0.16: Deprecated in favor of panes and returning self.

Return type:: Server

get_by_id(session_id)[source]¶

Return session by id. Deprecated in favor of sessions.get(). :rtype: Optional[Session]

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

Parameters:: session_id (str) –
Return type:: Session | None

where(kwargs)[source]¶

Filter through sessions, return list of Session. :rtype: List[Session]

Deprecated since version 0.16: Deprecated by session.filter().

Parameters:: kwargs (Dict[str, Any]) –
Return type:: List[Session]

find_where(kwargs)[source]¶

Filter through sessions, return first Session. :rtype: Optional[Session]

Deprecated since version 0.16: Slated to be removed in favor of sessions.get().

Parameters:: kwargs (Dict[str, Any]) –
Return type:: Session | None

_list_windows()[source]¶

Return list of windows in dict form.

Retrieved from $ tmux(1) list-windows stdout.

The list is derived from stdout in common.tmux_cmd which wraps subprocess.Popen. :rtype: List[Dict[str, Any]]

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

Return type:: List[Dict[str, Any]]

_update_windows()[source]¶

Update internal window data and return self for chainability. :rtype: Server

Deprecated since version 0.16: Deprecated in favor of windows and returning self.

Return type:: Server

property _sessions: List[Dict[str, Any]]¶: Property / alias to return _list_sessions().

Deprecated since version 0.16: Slated to be removed in favor of sessions.

_list_sessions()[source]¶

Return list of session object dictionaries. :rtype: List[Dict[str, Any]]

Deprecated since version 0.16: Slated to be removed in favor of sessions.

Return type:: List[Dict[str, Any]]

list_sessions()[source]¶

Return list of Session from the tmux(1) session. :rtype: List[Session]

Deprecated since version 0.16: Slated to be removed in favor of sessions.

Return type:: list of Session

property children: QueryList[Session]¶: Was used by TmuxRelationalObject (but that’s longer used in this class).

Deprecated since version 0.16: Slated to be removed in favor of sessions.