Utilities

Helper methods and mixins for libtmux.

libtmux.common

libtmux.common.TMUX_MIN_VERSION = '3.2a'

data

Minimum version of tmux required to run libtmux

libtmux.common.TMUX_MAX_VERSION = '3.6'

data

Most recent version of tmux supported

class libtmux.common.CmdProtocol

class

Bases: Protocol

Command protocol for tmux command.

__init__(*args, **kwargs)

method

_abc_impl = <_abc._abc_data object>

attribute

_is_protocol = True

attribute

class libtmux.common.CmdMixin

class

Bases: object

Command mixin for tmux command.

cmd: CmdProtocol

attribute

class libtmux.common.EnvironmentMixin

class

Bases: object

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

cmd: Callable[[t.Any, t.Any], tmux_cmd]

attribute

__init__(add_option=None)

method

Parameters:

add_option (str | None)

Return type:

None

_add_option = None

attribute

set_environment(name, value)

method

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

Parameters:

• name (str) – The environment variable name, e.g. ‘PATH’.

• value (str) – Environment value.

Raises:

ValueError – If tmux returns an error.

Return type:

None

unset_environment(name)

method

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

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.

Raises:

ValueError – If tmux returns an error.

Return type:

None

remove_environment(name)

method

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

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.

Raises:

ValueError – If tmux returns an error.

Return type:

None

show_environment()

method

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

getenv(name)

method

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

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

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

class

Bases: object

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, tmux_bin=None)

method

Parameters:

• args (Any)

• tmux_bin (str | None)

Return type:

None

libtmux.common.get_version(tmux_bin=None)

function

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.

Parameters:

tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux from shutil.which().

Returns:

tmux version according to tmux_bin if provided, otherwise the system tmux from shutil.which()

Return type:

distutils.version.LooseVersion

libtmux.common.has_version(version, tmux_bin=None)

function

Return True if tmux version installed.

Parameters:

• version (str) – version number, e.g. ‘3.2a’

• tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version matches

Return type:

bool

libtmux.common.has_gt_version(min_version, tmux_bin=None)

function

Return True if tmux version greater than minimum.

Parameters:

• min_version (str) – tmux version, e.g. ‘3.2a’

• tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version above min_version

Return type:

bool

libtmux.common.has_gte_version(min_version, tmux_bin=None)

function

Return True if tmux version greater or equal to minimum.

Parameters:

• min_version (str) – tmux version, e.g. ‘3.2a’

• tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version above or equal to min_version

Return type:

bool

libtmux.common.has_lte_version(max_version, tmux_bin=None)

function

Return True if tmux version less or equal to minimum.

Parameters:

• max_version (str) – tmux version, e.g. ‘3.2a’

• tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version below or equal to max_version

Return type:

bool

libtmux.common.has_lt_version(max_version, tmux_bin=None)

function

Return True if tmux version less than minimum.

Parameters:

• max_version (str) – tmux version, e.g. ‘3.2a’

• tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

Returns:

True if version below max_version

Return type:

bool

libtmux.common.has_minimum_version(raises=True, tmux_bin=None)

function

Return True if tmux meets version requirement. Version >= 3.2a.

Parameters:

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

• tmux_bin (str, optional) – Path to tmux binary. If None, uses the system tmux.

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.49.0: Minimum version bumped to 3.2a. For older tmux, use libtmux v0.48.x.

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)

function

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.

Parameters:

session_name (str) – Name of session.

Return type:

None

:raises exc.BadSessionName: Invalid session name.

libtmux.common.get_libtmux_version()

function

Return libtmux version is a PEP386 compliant format.

Returns:

libtmux version

Return type:

distutils.version.LooseVersion