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:
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