Session

Provides classes for interacting with iTerm2 sessions.

class Session(connection, link, summary=None)

Represents an iTerm2 session.

static active_proxy(connection: iterm2.connection.Connection) → iterm2.session.Session

Use this to register notifications against the currently active session.

Parameters:connection (Connection) – The connection to iTerm2.
Returns:A proxy for the currently active session.
static all_proxy(connection: iterm2.connection.Connection)

Use this to register notifications against all sessions, including those not yet created.

Parameters:connection (Connection) – The connection to iTerm2.
Returns:A proxy for all sessions.
async_activate(select_tab: bool = True, order_window_front: bool = True) → None

Makes the session the active session in its tab.

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

See also

Example “Asymmetric Broadcast Input

async_close(force: bool = False) → None

Closes the session.

Parameters:force (bool) – If True, the user will not be prompted for a confirmation.
Throws:RPCException if something goes wrong.
async_get_line_info() → iterm2.session.SessionLineInfo

Fetches the number of lines that are visible, in history, and that have been removed after history became full.

Returns:Information about the session’s wrapped lines of text.

See also

Example “Zoom on Screen

async_get_profile() → iterm2.profile.Profile

Fetches the profile of this session

Returns:The profile for this session, including any session-local changes not in the underlying profile.
Throws:RPCException if something goes wrong.

See also

async_get_screen_contents() → iterm2.screen.ScreenContents

Returns the contents of the mutable area of the screen.

Returns:A iterm2.screen.ScreenContents, containing the screen contents.
async_get_selection() → iterm2.selection.Selection
Returns:The selected regions of this session. The selection will be empty if there is no selected text.
Throws:RPCException if something goes wrong.

See also

Example “George’s Title Algorithm

async_get_selection_text(selection: iterm2.selection.Selection) → str

Fetches the text within a selection region.

Return type:str
Parameters:selection (Selection) – A Selection defining a region in the session.
Returns:A string with the selection’s contents. Discontiguous selections are combined with newlines.
async_get_variable(name: str) → Any

Fetches a session variable.

See Badges documentation for more information 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.

See also

Example “Per-Host Colors

async_inject(data: bytes) → None

Injects data as though it were program output.

Parameters:data (bytes) – A byte array to inject.
Throws:RPCException if something goes wrong.

See also

Example “Clear All Sessions

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

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

This invokes the RPC in the context of this session. Most user-defined RPCs are invoked in a session context (for example, invocations attached to triggers or key bindings). 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_run_tmux_command(command: str, timeout: float = -1) → str

Invoke a tmux command and return its result. Raises an exception if this session is not a tmux integration session.

Return type:

str

Parameters:
  • command (str) – The tmux command to run.
  • timeout (float) – The amount of time to wait for a response, or -1 to use the default.
Returns:

The output from tmux.

Throws:

RPCException if something goes wrong.

async_send_text(text: str, suppress_broadcast: bool = False) → None

Send text as though the user had typed it.

Parameters:
  • text (str) – The text to send.
  • suppress_broadcast (bool) – If True, text goes only to the specified session even if broadcasting is on.

See also

async_set_buried(buried: bool) → None

Buries or disinters a session.

Parameters:buried (bool) – If True, bury the session. If False, disinter it.
Throws:RPCException if something goes wrong.
async_set_grid_size(size: iterm2.util.Size) → None

Sets the visible size of a session.

Note: This is meant for tabs that contain a single pane. If split panes are present, use async_update_layout() instead.

Parameters:size (Size) – The new size for the session, in cells.
Throws:RPCException if something goes wrong.

Note: This will fail on fullscreen windows.

async_set_name(name: str)

Changes the session’s name.

This is equivalent to editing the session’s name manually in the Edit Session window.

Parameters:name (str) – The new name to use.
Throws:RPCException if something goes wrong.
async_set_profile(profile: iterm2.profile.Profile)

Changes this session’s profile.

The profile may be an existing profile, an existing profile with modifications, or a previously uknown profile with a unique GUID.

Parameters:profile (Profile) – The ~iterm2.profile.Profile to use.
Throws:RPCException if something goes wrong.
async_set_profile_properties(write_only_profile: iterm2.profile.LocalWriteOnlyProfile) → None

Sets the value of properties in this session.

When you use this function the underlying profile is not modified. The session will keep a copy of its profile with these modifications.

Parameters:write_only_profile (LocalWriteOnlyProfile) – A write-only profile that has the desired changes.
Throws:RPCException if something goes wrong.

See also

async_set_selection(selection: iterm2.selection.Selection) → None
Parameters:selection (Selection) – The regions of text to select.
Throws:RPCException if something goes wrong.

See also

Example “Zoom on Screen

async_set_variable(name: str, value: Any)

Sets a user-defined variable in the session.

See Badges documentation for more information on user-defined variables.

Parameters:
  • name (str) – The variable’s name.
  • value – The new value to assign.
Throws:

RPCException if something goes wrong.

See also

Example “Escape Key Indicator

async_split_pane(vertical: bool = False, before: bool = False, profile: Union[None, str] = None, profile_customizations: Union[None, iterm2.profile.LocalWriteOnlyProfile] = None) → iterm2.session.Session

Splits the pane, creating a new session.

Parameters:
  • vertical (bool) – If True, the divider is vertical, else horizontal.
  • before (bool) – If True, the new session will be to the left of or above the session being split. Otherwise, it will be to the right of or below it.
  • profile – The profile name to use. None for the default profile.
  • profile_customizations – Changes to the profile that should affect only this session, or None to make no changes.
Returns:

A newly created Session.

Throws:

SplitPaneException if something goes wrong.

See also

Example “Asymmetric Broadcast Input

get_screen_streamer(want_contents: bool = True) → iterm2.screen.ScreenStreamer

Provides a nice interface for receiving updates to the screen.

The screen is the mutable part of a session (its last lines, excluding scrollback history).

Return type:

ScreenStreamer

Parameters:

want_contents (bool) – If True, the screen contents will be provided. See ScreenStreamer for details.

Returns:

A new screen streamer, suitable for monitoring the contents of this session.

Example:
async with session.get_screen_streamer() as streamer:
while condition():

contents = await streamer.async_get() do_something(contents)

grid_size

Returns the size of the visible part of the session in cells.

Returns:The size of the visible part of the session in cells.
preferred_size

The size in cells to resize to when Tab.async_update_layout() is called.

pretty_str(indent: str = '') → str
Returns:A string describing the session.
session_id
Returns:the globally unique identifier for this session.
class InvalidSessionId

The specified session ID is not allowed in this method.

class SplitPaneException

Something went wrong when trying to split a pane.

class SessionLineInfo(line_info)
first_visible_line_number

Returns the line number of the first line currently displayed onscreen. Changes when the user scrolls.

mutable_area_height

Returns the height of the mutable area of the session.

overflow

Returns the number of lines lost to overflow. These lines were removed after scrollback history became full.

scrollback_buffer_height

Returns the height of the immutable area of the session.

class Splitter(vertical: bool = False)

A container of split pane sessions where the dividers are all aligned the same way.

children
Returns:This splitter’s children. A list of Session or Splitter objects.
pretty_str(indent: str = '') → str
Returns:A string describing this splitter. Has newlines.
sessions
Returns:All sessions in this splitter and all nested splitters. A list of Session objects.
vertical

Are the dividers in this splitter vertical?


Indices and tables