Utilities

Helper methods and mixins.

libtmux.common

libtmux.common.TMUX_MIN_VERSION = '1.8'

Minimum version of tmux required to run libtmux

libtmux.common.TMUX_MAX_VERSION = '3.3'

Most recent version of tmux supported

class libtmux.common.EnvironmentMixin(add_option=None)

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

set_environment(name, value)

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

Parameters:

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

• option (str) – environment value.

Return type:

None

unset_environment(name)

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

Parameters:

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

Return type:

None

remove_environment(name)

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

Parameters:

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

Return type:

None

show_environment()

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

Return dict of environment variables for the session.

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

Return type:

Dict[str, Union[bool, str]]

getenv(name)

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

Return the value of a specific variable if the name is specified.

New in version 0.13.

Parameters:

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

Returns:

Value of environment variable

Return type:

str

Return type:

Union[str, bool, None]

class libtmux.common.tmux_cmd(*args, **kwargs)

tmux(1) command via subprocess.

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.get_version()

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 shtuil.which()’s tmux

Return type:

distutils.version.LooseVersion

Return type:

LegacyVersion

libtmux.common.has_version(version)

Return affirmative if tmux version installed.

Parameters:

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

Returns:

True if version matches

Return type:

bool

Return type:

bool

libtmux.common.has_gt_version(min_version)

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

Return type:

bool

libtmux.common.has_gte_version(min_version)

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

Return type:

bool

libtmux.common.has_lte_version(max_version)

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

Return type:

bool

libtmux.common.has_lt_version(max_version)

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

Return type:

bool

libtmux.common.has_minimum_version(raises=True)

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

Return type:

bool

libtmux.common.session_check_name(session_name)

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.

Return type:

None

libtmux.common.handle_option_error(error)

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 –

Return type:

Type[OptionError]

libtmux.common.get_libtmux_version()

Return libtmux version is a PEP386 compliant format.

Returns:

libtmux version

Return type:

distutils.version.LooseVersion

Return type:

LegacyVersion