Utilities

Helper methods and mixins for libtmux.

libtmux.common

libtmux.common.TMUX_MIN_VERSION = '1.8'

Minimum version of tmux required to run libtmux

libtmux.common.TMUX_MAX_VERSION = '3.4'

Most recent version of tmux supported

class libtmux.common.EnvironmentMixin

Mixin for manager session and server level environment variables in tmux.

__init__(add_option=None)

Parameters:

add_option (str | None)

Return type:

None

set_environment(name, value)

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)

unset_environment(name)

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

Return type:

None

Parameters:

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

remove_environment(name)

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

Return type:

None

Parameters:

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

show_environment()

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

getenv(name)

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]

Added in version 0.13.

Parameters:

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

Returns:

Value of environment variable

Return type:

str

class libtmux.common.tmux_cmd

Run any tmux(1) command through subprocess.

Examples

Create a new session, check for error:

>>> proc = tmux_cmd(f'-L{server.socket_name}', 'new-session', '-d', '-P', '-F#S')
>>> if proc.stderr:
...     raise exc.LibTmuxException(
...         'Command: %s returned error: %s' % (proc.cmd, proc.stderr)
...     )
...

>>> print(f'tmux command returned {" ".join(proc.stdout)}')
tmux command returned 2

Equivalent to:

$ tmux new-session -s my session

Notes

Changed in version 0.8: Renamed from tmux to tmux_cmd.

__init__(*args)

Parameters:

args (Any)

Return type:

None

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.

Return type:

LegacyVersion

Returns:

tmux version according to shtuil.which()’s tmux

Return type:

distutils.version.LooseVersion

libtmux.common.has_version(version)

Return True if tmux version installed.

Return type:

bool

Parameters:

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

Returns:

True if version matches

Return type:

bool

libtmux.common.has_gt_version(min_version)

Return True if tmux version greater than minimum.

Return type:

bool

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)

Return True if tmux version greater or equal to minimum.

Return type:

bool

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_lte_version(max_version)

Return True if tmux version less or equal to minimum.

Return type:

bool

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_lt_version(max_version)

Return True if tmux version less than minimum.

Return type:

bool

Parameters:

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

Returns:

True if version below max_version

Return type:

bool

libtmux.common.has_minimum_version(raises=True)

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

Return type:

bool

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.session_check_name(session_name)

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

Return type:

None

Parameters:

session_name (str) – Name of session.

Raises:

exc.BadSessionName – Invalid session name.

libtmux.common.handle_option_error(error)

Raise exception if error in option command found.

In tmux 3.0, show-option and show-window-option 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: :rtype: type[OptionError]

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

Return type:

LegacyVersion

Returns:

libtmux version

Return type:

distutils.version.LooseVersion