Utilities#

Helper methods and mixins.

libtmux.common#

libtmux.common.TMUX_MIN_VERSION = '1.8'#: Minimum version of tmux required to run libtmux

libtmux.common.TMUX_MAX_VERSION = '3.3'#: Most recent version of tmux supported

class libtmux.common.EnvironmentMixin(add_option=None)[source]#

Mixin class for managing session and server level environment variables in tmux.

set_environment(name, value)[source]#

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

Parameters:

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

Return type:

None

unset_environment(name)[source]#

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

Parameters:: name (str) – the environment variable name. such as ‘PATH’.
Return type:: None

remove_environment(name)[source]#

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

Parameters:: name (str) – the environment variable name. such as ‘PATH’.
Return type:: None

show_environment()[source]#

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
Return type:: Dict[str, Union[bool, str]]

getenv(name)[source]#

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

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

New in version 0.13.

Parameters:: name (str) – the environment variable name. such as ‘PATH’.
Returns:: Value of environment variable
Return type:: str
Return type:: Union[str, bool, None]

class libtmux.common.tmux_cmd(*args, **kwargs)[source]#

tmux(1) command via subprocess.

Examples

proc = tmux_cmd('new-session', '-s%' % 'my session')

if proc.stderr:
    raise exc.LibTmuxException(
        'Command: %s returned error: %s' % (proc.cmd, proc.stderr)
    )

print('tmux command returned %s' % proc.stdout)

Equivalent to:

$ tmux new-session -s my session

Notes

Changed in version 0.8: Renamed from tmux to tmux_cmd.

class libtmux.common.TmuxMappingObject[source]#

Base: MutableMapping.

Convenience container. Base class for Pane, Window, Session and Server.

Instance attributes for useful information tmux(1) uses for Session, Window, Pane, stored self._info. For example, a Window will have a window_id and window_name.

Object	formatter_prefix	value
`Server`	n/a	n/a
`Session`	`Session.formatter_prefix`	session_
`Window`	`Window.formatter_prefix`	window_
`Pane`	`Pane.formatter_prefix`	pane_

keys()[source]#

Return list of keys.

Return type:: KeysView[str]

class libtmux.common.TmuxRelationalObject[source]#

Base Class for managing tmux object child entities. .. # NOQA

Manages collection of child objects (a Server has a collection of Session objects, a Session has collection of Window)

Children of TmuxRelationalObject are going to have a self.children, self.child_id_attribute.

Object	.children	method
`Server`	`Server._sessions`	`Server.list_sessions()`
`Session`	`Session._windows`	`Session.list_windows()`
`Window`	`Window._panes`	`Window.list_panes()`
`Pane`	n/a	n/a

Object	child_id_attribute	value
`Server`	`Server.child_id_attribute`	session_id
`Session`	`Session.child_id_attribute`	window_id
`Window`	`Window.child_id_attribute`	pane_id
`Pane`	n/a	n/a

find_where(attrs)[source]#

Return object on first match.

Changed in version 0.4: Renamed from .findWhere to .find_where.

Return type:: Union[Pane, Window, Session, None]

where(attrs: D, first: Literal[True]) → O[source]#

where(attrs: D, first: Literal[False]) → List[O]

where(attrs: D) → List[O]

Return objects matching child objects properties.

Parameters:: attrs (dict) – tmux properties to match values of
Return type:: list of objects, or one object if first=True
Return type:: Union[List[TypeVar(O, Pane, Window, Session)], TypeVar(O, Pane, Window, Session)]

get_by_id(id)[source]#

Return object based on child_id_attribute.

Parameters:: val (str) –
Return type:: object
Return type:: Optional[TypeVar(O, Pane, Window, Session)]

libtmux.common.get_version()[source]#

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.

Returns:: tmux version according to shtuil.which()’s tmux
Return type:: distutils.version.LooseVersion
Return type:: LooseVersion

libtmux.common.has_version(version)[source]#

Return affirmative if tmux version installed.

Parameters:: version (str) – version number, e.g. ‘1.8’
Returns:: True if version matches
Return type:: bool
Return type:: bool

libtmux.common.has_gt_version(min_version)[source]#

Return affirmative if tmux version greater than minimum.

Parameters:: min_version (str) – tmux version, e.g. ‘1.8’
Returns:: True if version above min_version
Return type:: bool
Return type:: bool

libtmux.common.has_gte_version(min_version)[source]#

Return True if tmux version greater or equal to minimum.

Parameters:: min_version (str) – tmux version, e.g. ‘1.8’
Returns:: True if version above or equal to min_version
Return type:: bool
Return type:: bool

libtmux.common.has_lte_version(max_version)[source]#

Return True if tmux version less or equal to minimum.

Parameters:: max_version (str) – tmux version, e.g. ‘1.8’
Returns:: True if version below or equal to max_version
Return type:: bool
Return type:: bool

libtmux.common.has_lt_version(max_version)[source]#

Return True if tmux version less than minimum.

Parameters:: max_version (str) – tmux version, e.g. ‘1.8’
Returns:: True if version below max_version
Return type:: bool
Return type:: bool

libtmux.common.has_minimum_version(raises=True)[source]#

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

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`_.

Return type:: bool

libtmux.common.session_check_name(session_name)[source]#

Raises 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.handle_option_error(error)[source]#

Raises exception if error in option command found.

In tmux 3.0, show-option and show-window-otion 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:

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()[source]#

Return libtmux version is a PEP386 compliant format.

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