App

Provides access to application-level structures.

This module is the starting point for getting access to windows and other application-global data.

async async_get_app(connection: iterm2.connection.Connection, create_if_needed: bool = True) → Union[None, iterm2.app.App]

Returns the app singleton, creating it if needed.

Parameters

  • connection (Connection) – The connection to iTerm2.

  • create_if_needed (bool) – If True, create the global App instance if one does not already exists. If False, do not create it.

Returns

The global App instance. If create_if_needed is False this may return None if no such instance exists.

async async_invoke_function(connection: iterm2.connection.Connection, 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 global application context. 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.

class App(connection, windows, buried_sessions)

Represents the application.

Stores and provides access to app-global state. Holds a collection of terminal windows and provides utilities for them.

This object keeps itself up to date by getting notifications when sessions, tabs, or windows change.

async async_activate(raise_all_windows: bool = True, ignoring_other_apps: bool = False) → None

Activate the app, giving it keyboard focus.

Parameters

  • raise_all_windows (bool) – Raise all windows if True, or only the key window. Defaults to True.

  • ignoring_other_apps (bool) – If True, activate even if the user interacts with another app after the call.

async async_get_theme() → List[str]

Gets attributes the current theme.

The automatic and minimal themes will always include “dark” or “light”.

On macOS 10.14, the light or dark attribute may be inferred from the system setting.

Returns

A list of one or more strings from the set: light, dark, automatic, minimal, highContrast.

async async_get_variable(name: str) → Any

Fetches the value of a variable from the global context.

See Scripting Fundamentals for details on variables.

Parameters

name (str) – The variable’s name.

Returns

The variable’s value or empty string if it is undefined.

Throws

RPCException if something goes wrong.

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

Sets a user-defined variable in the application.

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.

property broadcast_domains: List[iterm2.broadcast.BroadcastDomain]

Returns the current broadcast domains.

See also

property buried_sessions: List[iterm2.session.Session]

Returns a list of buried sessions.

Returns

A list of buried Session objects.

property current_terminal_window: Optional[iterm2.window.Window]

Deprecated in favor of current_window.

get_session_by_id(session_id: str, include_buried: bool = True) → Union[None, iterm2.session.Session]

Finds a session exactly matching the passed-in id.

Note: the behavior of this method changed in version 2.3. Earlier versions never returned buried sesions.

Parameters

  • session_id (str) – The session ID to search for.

  • include_buried (bool) – OK to return buried sessions?

Returns

A Session or None.

get_tab_by_id(tab_id: str) → Optional[iterm2.tab.Tab]

Finds a tab exactly matching the passed-in id.

Parameters

tab_id (str) – The tab ID to search for.

Returns

A Tab or None.

get_window_and_tab_for_session(session: iterm2.session.Session) → Union[Tuple[None, None], Tuple[iterm2.window.Window, iterm2.tab.Tab]]

Finds the tab and window that own a session.

Parameters

session (Session) – The session whose tab and window you wish to find.

Returns

A tuple of (Window, Tab), or (None, None) if the session was not found.

get_window_by_id(window_id: str) → Optional[iterm2.window.Window]

Finds a window exactly matching the passed-in id.

Parameters

window_id (str) – The window ID to search for.

Returns

A Window or None.

get_window_for_tab(tab_id: str) → Optional[iterm2.window.Window]

Finds the window that contains the passed-in tab id.

Parameters

tab_id (str) – The tab ID to search for.

Returns

A Window or None.

pretty_str() → str

Returns the hierarchy as a human-readable string

property terminal_windows: List[iterm2.window.Window]

Deprecated in favor of windows

class CreateWindowException

A problem was encountered while creating a window.

Indices and tables