Documentation | Python API

Tab¶

Provides a class that represents an iTerm2 tab.

class Tab(connection, tab_id, root, tmux_window_id=None, tmux_connection_id=None)¶

Represents a tab.

Don’t create this yourself. Instead, use App.

async async_activate(order_window_front: bool = True) → None¶

Selects this tab.

Parameters: order_window_front (bool) – Whether the window this session is in should be brought to the front and given keyboard focus.

See also

Example “Sort Tabs”

async async_invoke_function(invocation: str, timeout: float = -1)¶

Invoke an RPC. Could be a registered function by this or another script of a built-in function.

This invokes the RPC in the context of this tab. Note that most user-defined RPCs expect to be invoked in the context of a session. Default variables will be pulled from that scope. If you call a function from the wrong context it may fail because its defaults will not be set properly.

Parameters

invocation (str) – A function invocation string.
timeout (float) – Max number of secondsto wait. Negative values mean to use the system default timeout.

Returns

The result of the invocation if successful.

Throws

RPCException if something goes wrong.

async async_move_to_window() → iterm2.window.Window¶

Moves this tab to its own window, provided there are multiple tabs in the window it belongs to.

Returns: The new window ID.
Throws: RPCException if something goes wrong.

async async_select(order_window_front: bool = True) → None¶: Deprecated in favor of async_activate.

async async_select_pane_in_direction(direction: iterm2.tab.NavigationDirection) → Optional[str]¶

Activates a split pane adjacent to the currently selected pane. Requires iTerm2 version 3.3.2.

Parameters: direction (NavigationDirection) – Specifies the direction to move. For example, LEFT will cause the pane to the left of the currently active one.
Returns: The ID of the newly selected session ID, or None if there was no session in that direction.
Throws: RPCException if something goes wrong.

async async_set_title(title: str)¶

Changes the tab’s title.

This is equivalent to editing the tab’s title with the menu item Edit Tab Title. The title is an interpolated string.

Parameters: title (str) – The new title. Set it to an empty string to use the default value (the current session’s title).
Throws: RPCException if something goes wrong.

async async_set_variable(name: str, value: Any) → None¶

Sets a user-defined variable in the tab.

See the Scripting Fundamentals documentation for more information on user-defined variables.

Parameters

name (str) – The variable’s name. Must begin with user..
value – The new value to assign.

Throws

RPCException if something goes wrong.

async async_update_layout() → None¶

Adjusts the layout of the sessions in this tab.

Change the Session.preferred_size of any sessions you wish to adjust before calling this.

Throws: RPCException if something goes wrong.

property current_session¶

Returns: The active session in this tab or None if it could not be determined.

pretty_str(indent: str = '') → str¶

Returns: A human readable description of the tab and its sessions.

property root¶

A tab’s sessions are stored in a tree. This returns the root of that tree.

An interior node of the tree is a Splitter. That corresponds to a collection of adjacent sessions with split pane dividers that are all either vertical or horizontal.

Leaf nodes are Sessions.

Returns: The root of the session tree.

property sessions¶

A tab contains a list of sessions, which are its split panes.

Returns: The sessions belonging to this tab, in no particular order.

property tab_id¶

Each tab has a globally unique identifier.

Returns: The tab’s identifier, a string.

property tmux_connection_id¶: Returns the connection ID.

property tmux_window_id¶

Returns this tab’s tmux window id or None.

Returns: A tmux window id or None if this is not a tmux integration window.

property window¶: Returns the window this tab belongs to.

Tab¶

Indices and tables¶