Python API reference

>>> convert_value("on")
True
>>> convert_value("off")
False

>>> convert_value("1")
1
>>> convert_value("50")
50

>>> convert_value("%50")
'%50'

>>> import io

>>> many_more_options = io.StringIO(r'''
... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
... terminal-features[1] screen*:title
... ''')
>>> many_more_flat_dict = parse_options_to_dict(many_more_options)
>>> many_more_flat_dict == {
... "terminal-features[0]": "xterm*:clipboard:ccolour:cstyle:focus",
... "terminal-features[1]": "screen*:title",}
True
>>> explode_arrays(many_more_flat_dict) == {
... "terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
... 1: "screen*:title"}}
True

>>> explode_arrays(parse_options_to_dict(io.StringIO(r'''
... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
... terminal-features[5] screen*:title
... '''))) == {
... "terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
... 5: "screen*:title"}}
True

>>> from libtmux._internal.sparse_array import SparseArray

>>> hooks_output = io.StringIO(r'''
... session-renamed[0] display-message 'renamed'
... session-renamed[5] refresh-client
... pane-focus-in[0] run-shell 'echo focus'
... ''')
>>> hooks_exploded = explode_arrays(
...     parse_options_to_dict(hooks_output),
...     force_array=True,
... )

>>> isinstance(hooks_exploded["session-renamed"], SparseArray)
True
>>> hooks_exploded["session-renamed"][0]
"display-message 'renamed'"
>>> hooks_exploded["session-renamed"][5]
'refresh-client'
>>> sorted(hooks_exploded["session-renamed"].keys())
[0, 5]

>>> import io

>>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
... terminal-features[5] screen*:title
... '''))))
{'terminal-features': {'xterm*': ['clipboard', 'ccolour', 'cstyle', 'focus'], 'screen*': ['title']}}

>>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
... terminal-features[5] screen*:title
... ''')))) == {
... "terminal-features": {"xterm*": ["clipboard", "ccolour", "cstyle", "focus"],
... "screen*": ["title"]}}
True

>>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
... command-alias[0] split-pane=split-window
... command-alias[1] splitp=split-window
... command-alias[2] "server-info=show-messages -JT"
... ''')))) == {
... "command-alias": {"split-pane": "split-window",
... "splitp": "split-window",
... "server-info": "show-messages -JT"}}
True

>>> explode_complex(explode_arrays({"terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
... 1: "screen*:title"}}))
{'terminal-features': {0: 'xterm*:clipboard:ccolour:cstyle:focus', 1: 'screen*:title'}}

>>> explode_complex(explode_arrays({"terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
... 8: "screen*:title"}})) == SparseArray({'terminal-features': {0:
... 'xterm*:clipboard:ccolour:cstyle:focus', 8: 'screen*:title'}})
True

>>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
... terminal-overrides[0] xterm-256color:Tc
... terminal-overrides[1] *:U8=0
... ''')))) == {
... "terminal-overrides": {"xterm-256color": {"Tc": None},
... "*": {"U8": 0}}}
True

>>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
... user-keys[100] "\e[test"
... user-keys[6] "\e\n"
... user-keys[0] "\e[5;30012~"
... ''')))) == {
... "user-keys": {0: "\\e[5;30012~",
... 6: "\\e\\n",
... 100: "\\e[test"}}
True

>>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
... status-format[0] "#[align=left range=left #{E:status-left-style}]#[push-default]#{T;=/#{status-left-length}:status-left}#[pop-default]#[norange default]#[list=on align=#{status-justify}]#[list=left-marker]<#[list=right-marker]>#[list=on]#{W:#[range=window|#{window_index} #{E:window-status-style}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-format}#[pop-default]#[norange default]#{?window_end_flag,,#{window-status-separator}},#[range=window|#{window_index} list=focus #{?#{!=:#{E:window-status-current-style},default},#{E:window-status-current-style},#{E:window-status-style}}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-current-format}#[pop-default]#[norange list=on default]#{?window_end_flag,,#{window-status-separator}}}#[nolist align=right range=right #{E:status-right-style}]#[push-default]#{T;=/#{status-right-length}:status-right}#[pop-default]#[norange default]"
... status-format[1] "#[align=centre]#{P:#{?pane_active,#[reverse],}#{pane_index}[#{pane_width}x#{pane_height}]#[default] }"
... ''')))) == {
... "status-format": {0: "#[align=left range=left #{E:status-left-style}]#[push-default]#{T;=/#{status-left-length}:status-left}#[pop-default]#[norange default]#[list=on align=#{status-justify}]#[list=left-marker]<#[list=right-marker]>#[list=on]#{W:#[range=window|#{window_index} #{E:window-status-style}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-format}#[pop-default]#[norange default]#{?window_end_flag,,#{window-status-separator}},#[range=window|#{window_index} list=focus #{?#{!=:#{E:window-status-current-style},default},#{E:window-status-current-style},#{E:window-status-style}}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-current-format}#[pop-default]#[norange list=on default]#{?window_end_flag,,#{window-status-separator}}}#[nolist align=right range=right #{E:status-right-style}]#[push-default]#{T;=/#{status-right-length}:status-right}#[pop-default]#[norange default]",
... 1: "#[align=centre]#{P:#{?pane_active,#[reverse],}#{pane_index}[#{pane_width}x#{pane_height}]#[default] }",
... }}
True

>>> result = server.cmd(
...     'set-option',
...     'unknown-option-name',
... )

>>> bool(isinstance(result.stderr, list) and len(result.stderr))
True

>>> import pytest
>>> from libtmux import exc

>>> with pytest.raises(exc.OptionError):
...     handle_option_error(result.stderr[0])

>>> import io

>>> raw_options = io.StringIO("status-keys vi")
>>> parse_options_to_dict(raw_options) == {"status-keys": "vi"}
True

>>> int_options = io.StringIO("message-limit 50")
>>> parse_options_to_dict(int_options) == {"message-limit": "50"}
True

>>> empty_option = io.StringIO("user-keys")
>>> parse_options_to_dict(empty_option) == {"user-keys": None}
True

>>> array_option = io.StringIO("command-alias[0] split-pane=split-window")
>>> parse_options_to_dict(array_option) == {
... "command-alias[0]": "split-pane=split-window"}
True

>>> array_option = io.StringIO("command-alias[40] split-pane=split-window")
>>> parse_options_to_dict(array_option) == {
... "command-alias[40]": "split-pane=split-window"}
True

>>> many_options = io.StringIO(r'''status-keys
... command-alias[0] split-pane=split-window
... ''')
>>> parse_options_to_dict(many_options) == {
... "command-alias[0]": "split-pane=split-window",
... "status-keys": None,}
True

>>> many_more_options = io.StringIO(r'''
... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
... terminal-features[1] screen*:title
... ''')
>>> parse_options_to_dict(many_more_options) == {
... "terminal-features[0]": "xterm*:clipboard:ccolour:cstyle:focus",
... "terminal-features[1]": "screen*:title",}
True

>>> quoted_option = io.StringIO(r'''
... command-alias[0] "choose-session=choose-tree -s"
... ''')
>>> parse_options_to_dict(quoted_option) == {
... "command-alias[0]": "choose-session=choose-tree -s",
... }
True

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

>>> from libtmux.neo import _best_winlink
>>> _best_winlink([{"window_id": "@0", "window_index": "1"}])["window_index"]
'1'

>>> _best_winlink([
...     {"window_id": "@0", "window_index": "1", "window_active": "0"},
...     {"window_id": "@0", "window_index": "5", "window_active": "1"},
... ])["window_index"]
'5'

>>> _best_winlink([
...     {"window_id": "@0", "window_index": "1", "window_active": "0"},
...     {"window_id": "@0", "window_index": "5", "window_active": "0"},
... ])["window_index"]
'1'

>>> _best_winlink([
...     {"window_id": "@0", "window_index": "5", "window_active": "0"},
...     {"window_id": "@0", "window_index": "1", "window_active": "0"},
... ])["window_index"]
'1'

>>> from libtmux.neo import _is_target_not_found_error
>>> _is_target_not_found_error("can't find pane: %99")
True
>>> _is_target_not_found_error("can't find window: @99")
True
>>> _is_target_not_found_error("can't find session: $99")
True

>>> _is_target_not_found_error("no server running on /tmp/tmux-1000/default")
False
>>> _is_target_not_found_error(
...     "error connecting to /tmp/tmux-1000/nope (No such file or directory)"
... )
False

>>> from libtmux.neo import _normalize_tmux_version
>>> _normalize_tmux_version("3.6a") < _normalize_tmux_version("master")
True
>>> _normalize_tmux_version("3.2a") < _normalize_tmux_version("3.6a")
True

>>> from libtmux.neo import _token_scope
>>> _token_scope("pane_id")
'pane'
>>> _token_scope("window_zoomed_flag")
'window'
>>> _token_scope("client_name")
'client'
>>> _token_scope("version")
'universal'
>>> _token_scope("mouse_x")
'event'

>>> _token_scope("mouse_all_flag")
'pane'
>>> _token_scope("active_window_index")
'session'

>>> _token_scope("command_list_alias")
'context'
>>> _token_scope("search_match")
'context'

>>> _token_scope("libtmux_test_nonexistent_token")
'unknown'

>>> from libtmux.neo import fetch_obj
>>> fetch_obj(
...     server=pane.server,
...     obj_key="pane_id",
...     obj_id=pane.pane_id,
...     list_cmd="list-panes",
...     list_extra_args=("-t", pane.pane_id),
... )["pane_id"] == pane.pane_id
True

>>> from libtmux import exc
>>> try:
...     fetch_obj(
...         server=pane.server,
...         obj_key="pane_id",
...         obj_id="%99999",
...         list_cmd="list-panes",
...         list_extra_args=("-t", "%99999"),
...     )
... except exc.TmuxObjectDoesNotExist as e:
...     print(e)
Could not find pane_id=%99999 for list-panes ('-t', '%99999')

>>> from libtmux.neo import fetch_objs
>>> objs = fetch_objs(server=server, list_cmd="list-sessions")
>>> isinstance(objs, list)
True
>>> isinstance(objs[0], dict)
True
>>> 'session_id' in objs[0]
True

>>> from libtmux.neo import get_output_format
>>> fields, fmt = get_output_format("list-sessions", "3.6a")
>>> 'session_id' in fields
True
>>> 'pane_id' in fields  # active pane for the listed session
True
>>> 'client_name' in fields  # upward not allowed
False
>>> 'server' in fields
False

>>> fields, _ = get_output_format("list-panes", "3.6a")
>>> all(t in fields for t in ('pane_id', 'window_id', 'session_id'))
True

>>> fields, _ = get_output_format("list-clients", "3.6a")
>>> 'client_name' in fields
True
>>> 'pane_id' in fields
True

>>> from libtmux.neo import get_output_format, parse_output
>>> from libtmux.formats import FORMAT_SEPARATOR
>>> fields, fmt = get_output_format("list-sessions", "3.6a")
>>> values = [''] * len(fields)
>>> values[fields.index('session_id')] = '$1'
>>> result = parse_output(
...     FORMAT_SEPARATOR.join(values) + FORMAT_SEPARATOR,
...     list_cmd="list-sessions",
...     tmux_version="3.6a",
... )
>>> result['session_id']
'$1'
>>> 'pane_id' in result
False

>>> 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({})
''

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

>>> from libtmux._internal.control_mode import ControlMode
>>> def test_example(control_mode):
...     with control_mode() as ctl:
...         assert ctl.client_name != ''

>>> server = Server()  # Create server instance
>>> server.new_session()
Session($... ...)
>>> server.is_alive()
True
>>> # Each call creates a new server with unique socket
>>> server2 = Server()
>>> server2.socket_name != server.socket_name
True