Utilities

Helper methods and mixins for libtmux.

libtmux.common

libtmux.common.TMUX_MIN_VERSION = '3.3a'
data
data
libtmux.common.TMUX_MIN_VERSION = '3.3a'

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 libtmux.common.CmdProtocol

Bases: Protocol

Command protocol for tmux command.

class libtmux.common.CmdMixin
class libtmux.common.CmdMixin

Bases: object

Command mixin for tmux command.

class libtmux.common.EnvironmentMixin
class libtmux.common.EnvironmentMixin

Bases: object

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

libtmux.common._literal(value)
function[source]
function[source]
libtmux.common._literal(value)

Escape # so tmux stores value instead of expanding it as a format.

See libtmux.formats._escape_format() for why #{a:35}, not ##.

Examples

>>> _literal("build#2")
'build#{a:35}2'
>>> _literal("plain")
'plain'
Parameters:

value (str)

Return type:

str

libtmux.common._format_arg(value)
function[source]
function[source]
libtmux.common._format_arg(value)

Render a name or title: a str stays literal, a Format expands.

>>> _format_arg("a#b")
'a#{a:35}b'
>>> _format_arg(Format("#{session_name}"))
'#{session_name}'
Parameters:

value (str | Format)

Return type:

str

libtmux.common._format_path_arg(value)
function[source]
function[source]
libtmux.common._format_path_arg(value)

Render a start directory; a Format reaches tmux as written.

A path has ~ expanded first; a format is left to tmux.

>>> _format_path_arg("/tmp/a#b")
'/tmp/a#{a:35}b'
>>> _format_path_arg(Format("#{pane_current_path}"))
'#{pane_current_path}'
Parameters:

value (StrPath | Format)

Return type:

str

libtmux.common._format_text(value)
function[source]
function[source]
libtmux.common._format_text(value)

Render an argument tmux always expands: both forms reach tmux as written.

>>> _format_text("#{pane_id}")
'#{pane_id}'
>>> _format_text(Format("#{pane_id}-") + "50%")
'#{pane_id}-50#{a:37}'
Parameters:

value (str | Format)

Return type:

str

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.

libtmux.common._redact_env_values(argv)
function[source]
function[source]
libtmux.common._redact_env_values(argv)

Return argv with environment values masked and their names kept.

Covers -e NAME=value on the commands that take it and the value of set-environment. Only the copy that is logged goes through this; the argv tmux receives is unchanged.

Examples

>>> _redact_env_values(["tmux", "new-window", "-eTOKEN=hunter2", "-d"])
['tmux', 'new-window', '-eTOKEN=***', '-d']
>>> _redact_env_values(["tmux", "split-window", "-e", "TOKEN=hunter2"])
['tmux', 'split-window', '-e', 'TOKEN=***']
>>> _redact_env_values(["tmux", "set-environment", "-t", "$0", "TOKEN", "hunter2"])
['tmux', 'set-environment', '-t', '$0', 'TOKEN', '***']

A flag that is not an environment assignment is left alone:

>>> _redact_env_values(["tmux", "capture-pane", "-e", "-p"])
['tmux', 'capture-pane', '-e', '-p']
Parameters:

argv (Sequence[str])

Return type:

list[str]

libtmux.common._loggable_cmd(argv)
function[source]
function[source]
libtmux.common._loggable_cmd(argv)

Render argv as the command line libtmux writes to its logs.

Parameters:

argv (Sequence[str])

Return type:

str

libtmux.common.escape_trailing_separator(value)
function[source]
function[source]
libtmux.common.escape_trailing_separator(value)

Return value as one tmux argument that keeps a final ;.

tmux ends a command at an argument whose last character is ; and starts the next one there. It reads a backslash before that ; as an escape and passes the ; through as data. Typed libtmux methods call this on every free-text value they place in a command, so a value ends up in tmux unchanged.

Examples

>>> escape_trailing_separator("abc;")
'abc\\;'

A ; inside the value, and a value without one, are unchanged:

>>> escape_trailing_separator("a;b")
'a;b'

A value that already ends in \; gets its own escape:

>>> escape_trailing_separator("abc\\;")
'abc\\\\;'
Parameters:

value (str)

Return type:

str

class libtmux.common.tmux_cmd
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

Arguments are passed to tmux unchanged, so an argument ending in ; ends the command there and starts the next. Use escape_trailing_separator() for a value that must stay data.

Changed in version 0.8: Renamed from tmux to tmux_cmd.

exception libtmux.common._TmuxVersionUnavailable
exception[source]
exception[source]
exception libtmux.common._TmuxVersionUnavailable

Bases: Exception

Internal signal: this tmux predates the -V flag (pre-1.7).

libtmux.common._no_version_flag_fallback()
function[source]
function[source]
libtmux.common._no_version_flag_fallback()

Return a synthetic version string when tmux lacks -V.

OpenBSD ships a -V-less base tmux, so assume the maximum supported version; any other platform is genuinely too old.

Return type:

str

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

Return the raw tmux -V version token, letter suffix intact.

Runs tmux -V and extracts the version token (e.g. "3.7a", "master", "next-3.8"). Not memoized – get_version() and get_version_str() each cache their own result on top of this query.

Parameters:

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

Returns:

Raw version token from tmux -V.

Return type:

str

Raises:
libtmux.common.get_version_str(tmux_bin=None)
function[source]
function[source]
libtmux.common.get_version_str(tmux_bin=None)

Return the tmux version string verbatim, preserving letter suffixes.

get_version() normalizes point releases for numeric comparison ("3.7a" becomes LooseVersion("3.7")). This helper keeps the raw suffix, so callers can distinguish patch releases whose behavior differs – for example the tmux 3.7 break-pane crash, reverted in 3.7a.

Parameters:

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

Returns:

Raw tmux version, e.g. "3.7a". Git builds return "master"; OpenBSD base tmux returns "<max>-openbsd".

Return type:

str

Examples

>>> isinstance(get_version_str(), str)
True

Notes

Memoized via functools.cache(), keyed on tmux_bin, independently of get_version(). Call get_version_str.cache_clear() after swapping the tmux binary.

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), independently of get_version_str(). 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.3a.

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