Utilities¶

Helper methods and mixins for libtmux.

libtmux.common¶

libtmux.common.TMUX_MIN_VERSION = '3.2a' ¶ data data libtmux.common.TMUX_MIN_VERSION = '3.2a' ¶: Minimum version of tmux required to run libtmux

libtmux.common.TMUX_MAX_VERSION = '3.7' ¶ data data libtmux.common.TMUX_MAX_VERSION = '3.7' ¶: Most recent version of tmux supported

class libtmux.common.CmdProtocol ¶ class[source] class[source] class libtmux.common.CmdProtocol ¶

Bases: Protocol

Command protocol for tmux command.

class libtmux.common.CmdMixin ¶ class[source] class[source] class libtmux.common.CmdMixin ¶

Bases: object

Command mixin for tmux command.

class libtmux.common.EnvironmentMixin ¶ class[source] class[source] class libtmux.common.EnvironmentMixin ¶

Bases: object

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

set_environment(name, value, *, expand_format=None, hidden=None) ¶ method[source] method[source] set_environment(name, value, *, expand_format=None, hidden=None) ¶

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

Parameters:

name (str) – The environment variable name, e.g. ‘PATH’.
value (str) – Environment value.
expand_format (bool, optional) –
Expand tmux format strings in the value (-F flag).

Added in version 0.56.
hidden (bool, optional) –
Mark the variable as hidden (-h flag).

Added in version 0.56.

Raises:

ValueError – If tmux returns an error.

Return type:

None

libtmux.common.raise_if_stderr(proc, subcommand) ¶ function[source] function[source] libtmux.common.raise_if_stderr(proc, subcommand) ¶

Raise LibTmuxException tagged with the tmux subcommand on stderr.

Centralizes the if proc.stderr: raise exc.LibTmuxException(proc.stderr) pattern scattered across the wrappers. Tags the exception with the originating tmux subcommand so downstream consumers (e.g. libtmux-mcp’s handle_tool_errors) keep the “which tmux command failed” context.

Parameters:

proc (tmux_cmd) – Result of a Server.cmd() / Session.cmd() / etc. call.
subcommand (str) – The tmux subcommand the wrapper invoked, e.g. "last-window", "swap-pane". Surfaces in str(exc) as a "<subcommand>: …" prefix.

Raises:

LibTmuxException – When proc.stderr is non-empty.

Return type:

None

Examples

>>> from libtmux.common import raise_if_stderr
>>> from libtmux import exc
>>> proc = session.cmd("display-message", "-p", "#{session_id}")
>>> raise_if_stderr(proc, "display-message")  # no stderr → no raise

Added in version 0.57.

class libtmux.common.tmux_cmd ¶ class[source] class[source] class libtmux.common.tmux_cmd ¶

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.

libtmux.common.get_version(tmux_bin=None) ¶ function[source] function[source] libtmux.common.get_version(tmux_bin=None) ¶

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

Notes

Memoized via functools.cache(), keyed on the tmux_bin argument (None is a distinct key from any explicit path). The cache is sticky across PATH changes and on-disk binary swaps when tmux_bin is None or the same path string — call get_version.cache_clear() to invalidate. Tests that monkey-patch tmux_cmd should call cache_clear() before asserting parsed-version behavior.

libtmux.common.has_version(version, tmux_bin=None) ¶ function[source] function[source] libtmux.common.has_version(version, tmux_bin=None) ¶

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[source] function[source] libtmux.common.has_gt_version(min_version, tmux_bin=None) ¶

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[source] function[source] libtmux.common.has_gte_version(min_version, tmux_bin=None) ¶

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[source] function[source] libtmux.common.has_lte_version(max_version, tmux_bin=None) ¶

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[source] function[source] libtmux.common.has_lt_version(max_version, tmux_bin=None) ¶

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[source] function[source] libtmux.common.has_minimum_version(raises=True, tmux_bin=None) ¶

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[source] function[source] 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.

Parameters:: session_name (str) – Name of session.
Raises:: exc.BadSessionName – Invalid session name.
Return type:: None

libtmux.common.get_libtmux_version() ¶ function[source] function[source] libtmux.common.get_libtmux_version() ¶

Return libtmux version is a PEP386 compliant format.

Returns:: libtmux version
Return type:: distutils.version.LooseVersion