Utilities#

Helper methods and mixins.

libtmux.common#

class libtmux.common.EnvironmentMixin(add_option=None)[source]#

Mixin class for managing session and server level environment variables in tmux.

remove_environment(self, name)[source]#

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

Parameters:

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

set_environment(self, 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(self, 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(self, name)[source]#

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

Parameters:

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

libtmux.common.PaneDict#
libtmux.common.SessionDict#
libtmux.common.TMUX_MAX_VERSION = 2.4#
libtmux.common.TMUX_MIN_VERSION = 1.8#
class libtmux.common.TmuxMappingObject[source]#

Base: MutableMapping.

Convenience container. Base class for Pane, Window, Session and Server.

Instance attributes for useful information tmux(1) uses for Session, Window, Pane, stored self._info. For example, a Window will have a window_id and window_name.

Object

formatter_prefix

value

Server

n/a

n/a

Session

Session.formatter_prefix

session_

Window

Window.formatter_prefix

window_

Pane

Pane.formatter_prefix

pane_

keys(self)[source]#

Return list of keys.

class libtmux.common.TmuxRelationalObject[source]#

Base Class for managing tmux object child entities. .. # NOQA

Manages collection of child objects (a Server has a collection of Session objects, a Session has collection of Window)

Children of TmuxRelationalObject are going to have a self.children, self.child_id_attribute.

Object

.children

method

Server

Server._sessions

Server.list_sessions()

Session

Session._windows

Session.list_windows()

Window

Window._panes

Window.list_panes()

Pane

n/a

n/a

Object

child_id_attribute

value

Server

Server.child_id_attribute

session_id

Session

Session.child_id_attribute

window_id

Window

Window.child_id_attribute

pane_id

Pane

n/a

n/a

find_where(self, attrs)[source]#

Return object on first match.

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

get_by_id(self, id)[source]#

Return object based on child_id_attribute.

Parameters:

val (str) –

Return type:

object

Notes

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

where(self, attrs, first=False)[source]#

Return objects matching child objects properties.

Parameters:

attrs (dict) – tmux properties to match values of

Return type:

list

libtmux.common.WindowDict#
libtmux.common.console_to_str(s: bytes)[source]#

From pypa/pip project, pip.backwardwardcompat. License MIT.

libtmux.common.get_libtmux_version()[source]#

Return libtmux version is a PEP386 compliant format.

Returns:

libtmux version

Return type:

distutils.version.LooseVersion

libtmux.common.get_version()[source]#

Return tmux version.

If tmux is built from git master, the version returned will be the latest version appended with -master, e.g. 2.4-master.

If using OpenBSD’s base system tmux, the version will have -openbsd appended to the latest version, e.g. 2.4-openbsd.

Returns:

tmux version according to libtmux.common.which()’s tmux

Return type:

distutils.version.LooseVersion

libtmux.common.handle_option_error(error: str)[source]#

Raises exception if error in option command found.

In tmux 3.0, show-option and show-window-otion return invalid option instead of unknown option. See https://github.com/tmux/tmux/blob/3.0/cmd-show-options.c.

In tmux >2.4, there are 3 different types of option errors:

  • unknown option

  • invalid option

  • ambiguous option

In tmux <2.4, unknown option was the only option.

All errors raised will have the base error of exc.OptionError. So to catch any option error, use except exc.OptionError.

Parameters:

error (str) – Error response from subprocess call.

Raises:
libtmux.common.has_gt_version(min_version: str)[source]#

Return affirmative if tmux version greater than minimum.

Parameters:

min_version (str) – tmux version, e.g. ‘1.8’

Returns:

True if version above min_version

Return type:

bool

libtmux.common.has_gte_version(min_version: str)[source]#

Return True if tmux version greater or equal to minimum.

Parameters:

min_version (str) – tmux version, e.g. ‘1.8’

Returns:

True if version above or equal to min_version

Return type:

bool

libtmux.common.has_lt_version(max_version: str)[source]#

Return True if tmux version less than minimum.

Parameters:

max_version (str) – tmux version, e.g. ‘1.8’

Returns:

True if version below max_version

Return type:

bool

libtmux.common.has_lte_version(max_version: str)[source]#

Return True if tmux version less or equal to minimum.

Parameters:

max_version (str) – tmux version, e.g. ‘1.8’

Returns:

True if version below or equal to max_version

Return type:

bool

libtmux.common.has_minimum_version(raises: bool = True)[source]#

Return if tmux meets version requirement. Version >1.8 or above.

Parameters:

raises (bool) – raise exception if below minimum version requirement

Returns:

True if tmux meets minimum required version.

Return type:

bool

Raises:

libtmux.exc.VersionTooLow – tmux version below minimum required for libtmux

Notes

Changed in version 0.7.0: No longer returns version, returns True or False

Changed in version 0.1.7: Versions will now remove trailing letters per `Issue 55`_.

libtmux.common.has_version(version: str)[source]#

Return affirmative if tmux version installed.

Parameters:

version (str) – version number, e.g. ‘1.8’

Returns:

True if version matches

Return type:

bool

libtmux.common.logger#
libtmux.common.session_check_name(session_name: str)[source]#

Raises exception session name invalid, modeled after tmux function.

tmux(1) session names may not be empty, or include periods or colons. These delimiters are reserved for noting session, window and pane.

Parameters:

session_name (str) – Name of session.

Raises:

exc.BadSessionName – Invalid session name.

libtmux.common.str_from_console(s: Union[str, bytes])[source]#
class libtmux.common.tmux_cmd(*args, **kwargs)[source]#

tmux(1) command via subprocess.

Parameters:
  • tmux_search_paths (list, optional) – Default PATHs to search tmux for, defaults to default_paths used in which().

  • append_env_path (bool) – Append environment PATHs to tmux search paths. True by default.

Examples

proc = tmux_cmd('new-session', '-s%' % 'my session')

if proc.stderr:
    raise exc.LibTmuxException(
        'Command: %s returned error: %s' % (proc.cmd, proc.stderr)
    )

print('tmux command returned %s' % proc.stdout)

Equivalent to:

$ tmux new-session -s my session

Notes

Changed in version 0.8: Renamed from tmux to tmux_cmd.

libtmux.common.which(exe: str, default_paths: List[str] = ['/bin', '/sbin', '/usr/bin', '/usr/sbin', '/usr/local/bin'], append_env_path: bool = True)[source]#

Return path of bin. Python clone of /usr/bin/which.

Parameters:
  • exe (str) – Application to search PATHs for.

  • default_paths (list) – Paths to check inside of

  • append_env_path (bool, optional) – Append list of directories to check in from PATH environment variable. Default True. Setting False only for testing / diagnosing.

Returns:

path of application, if found in paths.

Return type:

str

Notes

from salt.util - https://www.github.com/saltstack/salt - license apache