Servers

  • identified by socket path and socket name
  • may have >1 servers running of tmux at the same time.
  • hold Sessions (which hold Windows, which hold Panes)

In tmux, a server is automatically started on your behalf when you first run tmux.

class libtmux.Server(socket_name=None, socket_path=None, config_file=None, colors=None, **kwargs)[source]

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

The tmux(1) server [1].

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

References

[1]
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 TmuxMappingObject

socket_name = None

[-L socket-name]

socket_path = None

[-S socket-path]

config_file = None

[-f file]

colors = None

-2 or -8

cmd(*args, **kwargs)[source]

Execute tmux command and return output.

Returns:
Return type:common.tmux_cmd

Notes

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

_list_sessions()[source]

Return list of sessions in dict form.

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

The list is derived from stdout in common.tmux_cmd which wraps subprocess.Popen.

Returns:
Return type:list of dict
property _sessions

Property / alias to return _list_sessions().

list_sessions()[source]

Return list of Session from the tmux(1) session.

Returns:
Return type:list of Session
property sessions

Property / alias to return list_sessions().

property children

Alias sessions for TmuxRelationalObject

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

Returns:
Return type:list of dict
_update_windows()[source]

Update internal window data and return self for chainability.

Returns:
Return type:Server
_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.

Returns:
Return type:list
_update_panes()[source]

Update internal pane data and return self for chainability.

Returns:
Return type:Server
property attached_sessions

Return active Session objects.

This will not work where multiple tmux sessions are attached.

Returns:
Return type:list of Session
has_session(target_session, exact=True)[source]

Return True if session exists. $ tmux has-session.

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 –

Returns:
Return type:

bool
kill_server()[source]

$ tmux kill-server.

find_where(attrs)[source]

Return object on first match.

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

get_by_id(id)[source]

Return object based on child_id_attribute.

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

Notes

Based on .get() from backbone.js.

kill_session(target_session=None)[source]

Kill the tmux session with $ tmux kill-session, return self.

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

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

Parameters:name (str) – the environment variable name. such as ‘PATH’.
set_environment(name, value)[source]

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

Parameters:
  • name (str) – the environment variable name. such as ‘PATH’.
  • option (str) – environment value.
show_environment(name=None)[source]

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
unset_environment(name)[source]

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

Parameters:name (str) – the environment variable name. such as ‘PATH’.
where(attrs, first=False)[source]

Return objects matching child objects properties.

Parameters:attrs (dict) – tmux properties to match values of
Returns:
Return type:list
switch_client(target_session)[source]

$ tmux switch-client.

Parameters:target_session (str) – name of the session. fnmatch(3) works.
Raises:exc.BadSessionName –
attach_session(target_session=None)[source]

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

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, *args, **kwargs)[source]

Return Session from $ tmux 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.

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
Other Parameters:
 

  • 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) – 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.
Returns:
Return type:

Session
Raises:

exc.BadSessionName –