Utilities¶
Helper methods and mixins for libtmux.
libtmux.common¶
-
libtmux.common.TMUX_MIN_VERSION = '3.3a'¶libtmux.common.TMUX_MIN_VERSION = '3.3a'¶
Minimum version of tmux required to run libtmux
-
libtmux.common.TMUX_MAX_VERSION = '3.7'¶libtmux.common.TMUX_MAX_VERSION = '3.7'¶
Most recent version of tmux supported
-
class libtmux.common.CmdProtocol¶class libtmux.common.CmdProtocol¶
Bases:
ProtocolCommand protocol for tmux command.
-
class libtmux.common.CmdMixin¶class libtmux.common.CmdMixin¶
Bases:
objectCommand mixin for tmux command.
-
class libtmux.common.EnvironmentMixin¶class libtmux.common.EnvironmentMixin¶
Bases:
objectMixin for manager session and server level environment variables in tmux.
-
libtmux.common._literal(value)¶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'
-
libtmux.common._format_arg(value)¶libtmux.common._format_arg(value)¶
Render a name or title: a
strstays literal, aFormatexpands.>>> _format_arg("a#b") 'a#{a:35}b' >>> _format_arg(Format("#{session_name}")) '#{session_name}'
-
libtmux.common._format_path_arg(value)¶libtmux.common._format_path_arg(value)¶
Render a start directory; a
Formatreaches 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}'
-
libtmux.common._format_text(value)¶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}'
-
libtmux.common.raise_if_stderr(proc, subcommand)¶libtmux.common.raise_if_stderr(proc, subcommand)¶
Raise
LibTmuxExceptiontagged 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’shandle_tool_errors) keep the “which tmux command failed” context.- Parameters:
proc (
tmux_cmd) – Result of aServer.cmd()/Session.cmd()/ etc. call.subcommand (
str) – The tmux subcommand the wrapper invoked, e.g."last-window","swap-pane". Surfaces instr(exc)as a"<subcommand>: …"prefix.
- Raises:
LibTmuxException– Whenproc.stderris non-empty.- Return type:
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)¶libtmux.common._redact_env_values(argv)¶
Return argv with environment values masked and their names kept.
Covers
-e NAME=valueon the commands that take it and the value ofset-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']
-
libtmux.common._loggable_cmd(argv)¶libtmux.common._loggable_cmd(argv)¶
Render argv as the command line libtmux writes to its logs.
-
libtmux.common.escape_trailing_separator(value)¶libtmux.common.escape_trailing_separator(value)¶
Return
valueas 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\\\\;'
-
class libtmux.common.tmux_cmd¶class libtmux.common.tmux_cmd¶
Bases:
objectRun 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. Useescape_trailing_separator()for a value that must stay data.Changed in version 0.8: Renamed from
tmuxtotmux_cmd.
Bases:
ExceptionInternal signal: this tmux predates the
-Vflag (pre-1.7).
-
libtmux.common._no_version_flag_fallback()¶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:
-
libtmux.common._query_version(tmux_bin=None)¶libtmux.common._query_version(tmux_bin=None)¶
Return the raw
tmux -Vversion token, letter suffix intact.Runs
tmux -Vand extracts the version token (e.g."3.7a","master","next-3.8"). Not memoized –get_version()andget_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:
- Raises:
_TmuxVersionUnavailable– tmux predates the-Vflag; callers apply_no_version_flag_fallback().VersionTooLow– tmux reported another error on-V.
-
libtmux.common.get_version_str(tmux_bin=None)¶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"becomesLooseVersion("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.Examples
>>> isinstance(get_version_str(), str) True
Notes
Memoized via
functools.cache(), keyed on tmux_bin, independently ofget_version(). Callget_version_str.cache_clear()after swapping the tmux binary.
-
libtmux.common.get_version(tmux_bin=None)¶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
-openbsdappended to the latest version, e.g.2.4-openbsd.- Parameters:
tmux_bin (
str,optional) – Path to tmux binary. If None, uses the system tmux fromshutil.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 (Noneis a distinct key from any explicit path), independently ofget_version_str(). The cache is sticky acrossPATHchanges and on-disk binary swaps when tmux_bin isNoneor the same path string – callget_version.cache_clear()to invalidate. Tests that monkey-patchtmux_cmdshould callcache_clear()before asserting parsed-version behavior.
-
libtmux.common.has_version(version, tmux_bin=None)¶libtmux.common.has_version(version, tmux_bin=None)¶
Return True if tmux version installed.
-
libtmux.common.has_gt_version(min_version, tmux_bin=None)¶libtmux.common.has_gt_version(min_version, tmux_bin=None)¶
Return True if tmux version greater than minimum.
-
libtmux.common.has_gte_version(min_version, tmux_bin=None)¶libtmux.common.has_gte_version(min_version, tmux_bin=None)¶
Return True if tmux version greater or equal to minimum.
-
libtmux.common.has_lte_version(max_version, tmux_bin=None)¶libtmux.common.has_lte_version(max_version, tmux_bin=None)¶
Return True if tmux version less or equal to minimum.
-
libtmux.common.has_lt_version(max_version, tmux_bin=None)¶libtmux.common.has_lt_version(max_version, tmux_bin=None)¶
Return True if tmux version less than minimum.
-
libtmux.common.has_minimum_version(raises=True, tmux_bin=None)¶libtmux.common.has_minimum_version(raises=True, tmux_bin=None)¶
Return True if tmux meets version requirement. Version >= 3.3a.
- Parameters:
- Returns:
True if tmux meets minimum required version.
- Return type:
- 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)¶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: