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:

exc.OptionError –
exc.AmbiguousOption –

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