Exceptions¶

libtmux exceptions.

libtmux.exc¶

libtmux.exc._format_query(query) ¶ function[source] function[source] libtmux.exc._format_query(query) ¶

Render a QueryList.get() lookup back as key=value text.

Examples

>>> from libtmux.exc import _format_query
>>> _format_query({"pane_id": "%0"})
"pane_id='%0'"

>>> _format_query({"window_name": "shared", "window_index": "1"})
"window_name='shared', window_index='1'"

>>> _format_query({})
''

Parameters:: query (Mapping[str, Any])
Return type:: str

exception libtmux.exc.LibTmuxException ¶ exception[source] exception[source] exception libtmux.exc.LibTmuxException ¶

Bases: Exception

Base Exception for libtmux Errors.

Parameters:

*args (object) – Forwarded to Exception.
subcommand (str, optional) –
The tmux subcommand that produced this error (e.g. "last-window"). When set, __str__() formats as "<subcommand>: <stderr>" so downstream consumers see which tmux command failed.

Added in version 0.57.

exception libtmux.exc.DeprecatedError ¶ exception[source] exception[source] exception libtmux.exc.DeprecatedError ¶

Bases: LibTmuxException

Raised when a deprecated function, method, or parameter is used.

This exception provides clear guidance on what to use instead.

Parameters:

deprecated (str) – The name of the deprecated API (e.g., “Pane.resize_pane()”)
replacement (str) – The recommended replacement API to use instead
version (str) – The version when the API was deprecated (e.g., “0.28.0”)

exception libtmux.exc.TmuxSessionExists ¶ exception[source] exception[source] exception libtmux.exc.TmuxSessionExists ¶: Bases: LibTmuxException

Session does not exist in the server.

exception libtmux.exc.TmuxCommandNotFound ¶ exception[source] exception[source] exception libtmux.exc.TmuxCommandNotFound ¶: Bases: LibTmuxException

Application binary for tmux not found.

exception libtmux.exc.NotInsideTmux ¶ exception[source] exception[source] exception libtmux.exc.NotInsideTmux ¶

Bases: LibTmuxException

Raised when the process is not running inside a tmux pane.

tmux exports $TMUX and $TMUX_PANE into the environment of every pane it spawns. The from_env() family raises this when one of them is missing or malformed – i.e. the caller is not (or is no longer) recognizable as a tmux pane’s child process.

Parameters:

variable (str, optional) – Name of the offending environment variable, e.g. "TMUX".
reason (str) – Why it is unusable. Defaults to "unset or empty".
*args (object) – Forwarded to LibTmuxException.

Examples

>>> from libtmux import exc
>>> str(exc.NotInsideTmux("TMUX"))
'Not inside a tmux pane: $TMUX is unset or empty'

>>> str(exc.NotInsideTmux("TMUX_PANE", reason="not a pane id"))
'Not inside a tmux pane: $TMUX_PANE is not a pane id'

>>> str(exc.NotInsideTmux())
'Not inside a tmux pane'

It is part of the LibTmuxException hierarchy:

>>> issubclass(exc.NotInsideTmux, exc.LibTmuxException)
True

Added in version 0.62.

exception libtmux.exc.ObjectDoesNotExist ¶ exception[source] exception[source] exception libtmux.exc.ObjectDoesNotExist ¶

Bases: LibTmuxException

A lookup expected one object and matched none.

Raised by get() when nothing matches and no default was passed.

Parameters:

*args (object) – A ready-made message, forwarded to LibTmuxException. When omitted, the message is built from query.
query (Mapping, optional) – The lookup that matched nothing, e.g. {"pane_id": "%99"}.

Examples

>>> from libtmux import exc
>>> str(exc.ObjectDoesNotExist())
'No objects found'

A lookup that named what it wanted says so:

>>> str(exc.ObjectDoesNotExist(query={"pane_id": "%99"}))
"No objects found: pane_id='%99'"

It is part of the LibTmuxException hierarchy, so except LibTmuxException catches it:

>>> issubclass(exc.ObjectDoesNotExist, exc.LibTmuxException)
True

Changed in version 0.62: Re-based on LibTmuxException and given a message.

exception libtmux.exc.MultipleObjectsReturned ¶ exception[source] exception[source] exception libtmux.exc.MultipleObjectsReturned ¶

Bases: LibTmuxException

A lookup expected one object and matched several.

Raised by get(). Unlike ObjectDoesNotExist, a default does not suppress it: a default is a stand-in for an object that is absent, and an ambiguous lookup is not an absent one. Silently answering with one of several equally valid matches is how you end up driving the wrong pane.

On a server-wide collection, several matches for a single id is ordinary and means the window is linked into more than one session. See When one window is in two sessions for what to do about it.

Parameters:

*args (object) – A ready-made message, forwarded to LibTmuxException. When omitted, the message is built from count and query.
count (int, optional) – How many objects the lookup matched.
query (Mapping, optional) – The lookup that matched them, e.g. {"pane_id": "%0"}.

Examples

>>> from libtmux import exc
>>> str(exc.MultipleObjectsReturned())
'Multiple objects returned'

A lookup that matched too much reports how much, and for what:

>>> str(exc.MultipleObjectsReturned(count=2, query={"pane_id": "%0"}))
"Multiple objects returned (2): pane_id='%0'"

It is part of the LibTmuxException hierarchy, so except LibTmuxException catches it:

>>> issubclass(exc.MultipleObjectsReturned, exc.LibTmuxException)
True

Added in version 0.62: Added to libtmux.exc as a LibTmuxException subclass with a message.

exception libtmux.exc.TmuxObjectDoesNotExist ¶ exception[source] exception[source] exception libtmux.exc.TmuxObjectDoesNotExist ¶

Bases: ObjectDoesNotExist

tmux has no object with the id that was asked for.

Examples

>>> from libtmux import exc
>>> str(exc.TmuxObjectDoesNotExist())
'Could not find object'

>>> str(
...     exc.TmuxObjectDoesNotExist(
...         obj_key="pane_id",
...         obj_id="%99",
...         list_cmd="list-panes",
...         list_extra_args=("-t", "%99"),
...     )
... )
"Could not find pane_id=%99 for list-panes ('-t', '%99')"

exception libtmux.exc.VersionTooLow ¶ exception[source] exception[source] exception libtmux.exc.VersionTooLow ¶: Bases: LibTmuxException

Raised if tmux below the minimum version to use libtmux.

exception libtmux.exc.BadSessionName ¶ exception[source] exception[source] exception libtmux.exc.BadSessionName ¶

Bases: LibTmuxException

Disallowed session name for tmux (empty, contains periods or colons).

exception libtmux.exc.OptionError ¶ exception[source] exception[source] exception libtmux.exc.OptionError ¶: Bases: LibTmuxException

Root error for any error involving invalid, ambiguous or bad options.

exception libtmux.exc.UnknownOption ¶ exception[source] exception[source] exception libtmux.exc.UnknownOption ¶: Bases: OptionError

Option unknown to tmux show-option(s) or show-window-option(s).

exception libtmux.exc.UnknownColorOption ¶ exception[source] exception[source] exception libtmux.exc.UnknownColorOption ¶

Bases: UnknownOption

Unknown color option.

exception libtmux.exc.InvalidOption ¶ exception[source] exception[source] exception libtmux.exc.InvalidOption ¶: Bases: OptionError

Option invalid to tmux.

exception libtmux.exc.AmbiguousOption ¶ exception[source] exception[source] exception libtmux.exc.AmbiguousOption ¶: Bases: OptionError

Option that could potentially match more than one.

exception libtmux.exc.WaitTimeout ¶ exception[source] exception[source] exception libtmux.exc.WaitTimeout ¶: Bases: LibTmuxException

Function timed out without meeting condition.

exception libtmux.exc.VariableUnpackingError ¶ exception[source] exception[source] exception libtmux.exc.VariableUnpackingError ¶

Bases: LibTmuxException

Error unpacking variable.

exception libtmux.exc.PaneError ¶ exception[source] exception[source] exception libtmux.exc.PaneError ¶: Bases: LibTmuxException

Any type of pane related error.

exception libtmux.exc.PaneNotFound ¶ exception[source] exception[source] exception libtmux.exc.PaneNotFound ¶

Bases: PaneError

Pane not found.

exception libtmux.exc.WindowError ¶ exception[source] exception[source] exception libtmux.exc.WindowError ¶: Bases: LibTmuxException

Any type of window related error.

exception libtmux.exc.MultipleActiveWindows ¶ exception[source] exception[source] exception libtmux.exc.MultipleActiveWindows ¶

Bases: WindowError

Multiple active windows.

exception libtmux.exc.NoActiveWindow ¶ exception[source] exception[source] exception libtmux.exc.NoActiveWindow ¶

Bases: WindowError

No active window found.

exception libtmux.exc.NoWindowsExist ¶ exception[source] exception[source] exception libtmux.exc.NoWindowsExist ¶

Bases: WindowError

No windows exist for object.

exception libtmux.exc.AdjustmentDirectionRequiresAdjustment ¶ exception[source] exception[source] exception libtmux.exc.AdjustmentDirectionRequiresAdjustment ¶

Bases: LibTmuxException, ValueError

If adjustment_direction is set, adjustment must be set.

exception libtmux.exc.WindowAdjustmentDirectionRequiresAdjustment ¶ exception[source] exception[source] exception libtmux.exc.WindowAdjustmentDirectionRequiresAdjustment ¶: Bases: WindowError, AdjustmentDirectionRequiresAdjustment

ValueError for libtmux.Window.resize_window().

exception libtmux.exc.PaneAdjustmentDirectionRequiresAdjustment ¶ exception[source] exception[source] exception libtmux.exc.PaneAdjustmentDirectionRequiresAdjustment ¶: Bases: WindowError, AdjustmentDirectionRequiresAdjustment

ValueError for libtmux.Pane.resize_pane().

exception libtmux.exc.RequiresDigitOrPercentage ¶ exception[source] exception[source] exception libtmux.exc.RequiresDigitOrPercentage ¶

Bases: LibTmuxException, ValueError

Requires digit (int or str digit) or a percentage.