Windows#

class libtmux.Window(server, active_window_index=None, alternate_saved_x=None, alternate_saved_y=None, buffer_name=None, buffer_sample=None, buffer_size=None, client_cell_height=None, client_cell_width=None, client_discarded=None, client_flags=None, client_height=None, client_key_table=None, client_name=None, client_pid=None, client_termname=None, client_tty=None, client_uid=None, client_user=None, client_width=None, client_written=None, command_list_alias=None, command_list_name=None, command_list_usage=None, config_files=None, copy_cursor_line=None, copy_cursor_word=None, copy_cursor_x=None, copy_cursor_y=None, current_file=None, cursor_character=None, cursor_flag=None, cursor_x=None, cursor_y=None, history_bytes=None, history_limit=None, history_size=None, insert_flag=None, keypad_cursor_flag=None, keypad_flag=None, last_window_index=None, line=None, mouse_all_flag=None, mouse_any_flag=None, mouse_button_flag=None, mouse_sgr_flag=None, mouse_standard_flag=None, next_session_id=None, origin_flag=None, pane_active=None, pane_bg=None, pane_bottom=None, pane_current_command=None, pane_current_path=None, pane_dead_signal=None, pane_dead_status=None, pane_dead_time=None, pane_fg=None, pane_height=None, pane_id=None, pane_index=None, pane_left=None, pane_pid=None, pane_right=None, pane_search_string=None, pane_start_command=None, pane_start_path=None, pane_tabs=None, pane_top=None, pane_tty=None, pane_width=None, pid=None, scroll_position=None, scroll_region_lower=None, scroll_region_upper=None, search_match=None, selection_end_x=None, selection_end_y=None, selection_start_x=None, selection_start_y=None, session_activity=None, session_alerts=None, session_attached=None, session_attached_list=None, session_created=None, session_group=None, session_group_attached=None, session_group_list=None, session_group_size=None, session_id=None, session_last_attached=None, session_name=None, session_path=None, session_stack=None, session_windows=None, socket_path=None, start_time=None, uid=None, user=None, version=None, window_active=None, window_active_clients=None, window_active_sessions=None, window_activity=None, window_cell_height=None, window_cell_width=None, window_height=None, window_id=None, window_index=None, window_layout=None, window_linked=None, window_linked_sessions=None, window_linked_sessions_list=None, window_marked_flag=None, window_name=None, window_offset_x=None, window_offset_y=None, window_panes=None, window_raw_flags=None, window_stack_index=None, window_width=None, wrap_flag=None)[source]#

Bases: Obj

A tmux(1) Window [window_manual].

Holds Pane objects.

Parameters:

session (Session) –

Examples

>>> window = session.new_window('My project')

>>> window
Window(@2 2:My project, Session($... ...))

Windows have panes:

>>> window.panes
[Pane(...)]

>>> window.attached_pane
Pane(...)

Relations moving up:

>>> window.session
Session(...)

>>> window.window_id == session.attached_window.window_id
True

>>> window == session.attached_window
True

>>> window in session.windows
True

References

[window_manual]
tmux window. openbsd manpage for TMUX(1).

“Each session has one or more windows linked to it. A window occupies the entire screen and may be split into rectangular panes…”

https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.

refresh()[source]#

Refresh window attributes from tmux.

Return type:

None

classmethod from_window_id(server, window_id)[source]#

Create Window from existing window_id.

Return type:

Window

property session: Session#

Parent session of window.

property panes: QueryList[Pane]#

Panes belonging windows.

Can be accessed via .panes.get() and .panes.filter()

cmd(cmd, *args, **kwargs)[source]#

Return Server.cmd() defaulting to target_window as target.

Send command to tmux with window_id as target-window.

Specifying ('-t', 'custom-target') or ('-tcustom_target') in args will override using the object’s window_id as target.

Return type:

tmux_cmd

select_pane(target_pane)[source]#

Return selected Pane through $ tmux select-pane.

Return type:

Optional[Pane]

Parameters:

target_pane (str) – ‘target_pane’, ‘-U’ ,’-D’, ‘-L’, ‘-R’, or ‘-l’.

Return type:

Pane

split_window(target=None, start_directory=None, attach=True, vertical=True, shell=None, percent=None, environment=None)[source]#

Split window and return the created Pane.

Used for splitting window and holding in a python object.

Return type:

Pane

Parameters:

  • attach (bool, optional) – make new window the current window after creating it, default True.

  • start_directory (str, optional) – specifies the working directory in which the new window is created.

  • target (str) – target_pane to split.

  • vertical (str) – split vertically

  • shell (str, optional) –

    execute a command on splitting the window. The pane will close when the command exits.

    NOTE: When this command exits the pane will close. This feature is useful for long-running processes where the closing of the window upon completion is desired.

  • percent (int, optional) – percentage to occupy with respect to current window

  • environment (dict, optional) – Environmental variables for new pane. tmux 3.0+ only. Passthrough to -e.

Notes

tmux(1) will move window to the new pane if the split-window target is off screen. tmux handles the -d the same way as new-window and attach in Session.new_window.

By default, this will make the window the pane is created in active. To remain on the same window and split the pane in another target window, pass in attach=False.

last_pane()[source]#

Return last pane.

Return type:

Optional[Pane]

select_layout(layout=None)[source]#

Select layout for window.

Wrapper for $ tmux select-layout <layout>.

Return type:

Window

Parameters:

layout (str, optional) –

string of the layout, ‘even-horizontal’, ‘tiled’, etc. Entering None (leaving this blank) is same as select-layout with no layout. In recent tmux versions, it picks the most recently set layout.

’even-horizontal’

Panes are spread out evenly from left to right across the window.

’even-vertical’

Panes are spread evenly from top to bottom.

’main-horizontal’

A large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom.

’main-vertical’

Similar to main-horizontal but the large pane is placed on the left and the others spread from top to bottom along the right.

’tiled’

Panes are spread out as evenly as possible over the window in both rows and columns.

’custom’

custom dimensions (see tmux(1) manpages).

set_window_option(option, value)[source]#

Set option for tmux window.

Wraps $ tmux set-window-option <option> <value>.

Return type:

Window

Parameters:

  • option (str) – option to set, e.g. ‘aggressive-resize’

  • value (str) – window option value. True/False will turn in ‘on’ and ‘off’, also accepts string of ‘on’ or ‘off’ directly.

Raises:
show_window_options(g=False)[source]#

Return a dict of options for the window.

For familiarity with tmux, the option option param forwards to pick a single option, forwarding to Window.show_window_option(). :rtype: Dict[str, Any]

Changed in version 0.13.0: option removed, use show_window_option to return an individual option.

Parameters:

g (str, optional) – Pass -g flag for global variable, default False.

show_window_option(option, g=False)[source]#

Return a list of options for the window.

todo: test and return True/False for on/off string

Return type:

Union[str, int, None]

Parameters:

  • option (str) –

  • g (bool, optional) – Pass -g flag, global. Default False.

Raises:
rename_window(new_name)[source]#

Return Window object $ tmux rename-window <new_name>.

Return type:

Window

Parameters:

new_name (str) – name of the window

Examples

>>> window = session.attached_window

>>> window.rename_window('My project')
Window(@1 1:My project, Session($1 ...))

>>> window.rename_window('New name')
Window(@1 1:New name, Session($1 ...))
kill_window()[source]#

Kill the current Window object. $ tmux kill-window.

Return type:

None

move_window(destination='', session=None)[source]#

Move the current Window object $ tmux move-window.

Return type:

Window

Parameters:

  • destination (str, optional) – the target window or index to move the window to, default: empty string

  • session (str, optional) – the target session or index to move the window to, default: current session.

select_window()[source]#

Select window. Return self.

To select a window object asynchrously. If a window object exists and is no longer longer the current window, w.select_window() will make w the current window.

Return type:

Window

property attached_pane: Pane | None#

Return the attached Pane.

property id: str | None#

Alias of Window.window_id.

>>> window.id
'@1'

>>> window.id == window.window_id
True
property name: str | None#

Alias of Window.window_name.

>>> window.name
'...'

>>> window.name == window.window_name
True
property index: str | None#

Alias of Window.window_index.

>>> window.index
'1'

>>> window.index == window.window_index
True
property height: str | None#

Alias of Window.window_height.

>>> window.height.isdigit()
True

>>> window.height == window.window_height
True
property width: str | None#

Alias of Window.window_width.

>>> window.width.isdigit()
True

>>> window.width == window.window_width
True
get(key, default=None)[source]#

Return key-based lookup. Deprecated by attributes. :rtype: Any

Deprecated since version 0.16: Deprecated by attribute lookup.e.g. window['window_name'] is now accessed via window.window_name.

get_by_id(id)[source]#

Return pane by id. Deprecated in favor of panes.get(). :rtype: Optional[Pane]

Deprecated since version 0.16: Deprecated by panes.get().

where(kwargs)[source]#

Filter through panes, return list of Pane. :rtype: List[Pane]

Deprecated since version 0.16: Deprecated by panes.filter().

find_where(kwargs)[source]#

Filter through panes, return first Pane. :rtype: Optional[Pane]

Deprecated since version 0.16: Slated to be removed in favor of panes.get().

_list_panes()[source]#

Return list of panes (deprecated in favor of panes()). :rtype: List[Dict[str, Any]]

Deprecated since version 0.16: Slated to be removed in favor of panes.

property _panes: List[Dict[str, Any]]#

Property / alias to return _list_panes().

Deprecated since version 0.16: Slated to be removed in favor of panes.

list_panes()[source]#

Return list of Pane for the window. :rtype: List[Pane]

Deprecated since version 0.16: Slated to be removed in favor of panes.

property children: QueryList[Pane]#

Was used by TmuxRelationalObject (but that’s longer used in this class).

Deprecated since version 0.16: Slated to be removed in favor of panes.