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 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 async_add_annotation(range: iterm2.util.CoordRange, text: str)

Adds an annotation.

This will not replace an existing annotation. It will always add a new one.

Throws an exception if the range is invalid.

Parameters:

  • range (CoordRange) – The range to annotate.

  • text (str) – The string to annotate with.

async 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 async_get_contents(first_line: int, number_of_lines: int) → List[iterm2.screen.LineContents]

Returns the contents of the session within a given range of lines.

Use async_get_line_info to determine the available line numbers.

first_lines should be at least as large as (await async_get_line_info()).overflow.

If it is less, then you won’t get as many lines as you asked for.

To use this reliably, you must call async_get_line_info() and this method in a Transaction to ensure the session doesn’t change between calls. See the example below.

Parameters:

  • first_line (int) – The first line number to fetch.

  • number_of_lines (int) – The number of lines to fetch.

Returns:

A list of iterm2.screen.LineContents. If some were unavailable then a subset is returned.

Throws:

RPCException if something goes wrong.

Example that prints the first ten lines of session.
async with iterm2.Transaction(connection) as txn:
  li = await session.async_get_line_info()
  lines = await session.async_get_contents(li.overflow, 10)
print(list(map(lambda line: line.string, lines)))
async async_get_coprocess() → Optional[str]

Returns the command line of the currently running coprocess, if any.

Returns:

Whether there is a coprocess currently running.

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

Throws:

RPCException if something goes wrong.

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

See also

Returns:

A string with the selection’s contents. Discontiguous selections are combined with newlines.

async async_get_variable(name: str) → Any

Fetches a session variable.

See the Scripting Fundamentals 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 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 (all tabs or current tab)”

async 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 async_restart(only_if_exited: bool = False) → None

Restarts a session.

Parameters:

only_if_exited (bool) – When True, this will raise an exception if the session is still running. When False, a running session will be killed and restarted.

Throws:

RPCException if something goes wrong.

async async_run_coprocess(command_line: str) → bool

Runs a coprocess, provided non is already running.

Return type:

bool

Parameters:

command_line (str) – The command line for the new coprocess.

Returns:

True if it was launched or False if one was already running.

async 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 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 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 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 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 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 unknown profile with a unique GUID.

Parameters:

profile (Profile) – The ~iterm2.profile.Profile to use.

Throws:

RPCException if something goes wrong.

async 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 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 async_set_variable(name: str, value: Any)

Sets a user-defined variable in the session.

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.

See also

Example “Escape Key Indicator”

async async_split_pane(vertical: bool = False, before: bool = False, profile: Optional[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”

async async_stop_coprocess() → bool

Stops the currently running coprocess, if any.

Returns:

True if a coprocess was stopped or False if non was running.

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 that calls do_something() with screen contents as they arrive.
async with session.get_screen_streamer() as streamer:
  while condition():
    contents = await streamer.async_get()
    do_something(contents)
property grid_size: iterm2.util.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.

property preferred_size: iterm2.util.Size

The size in cells to resize to when Tab.async_update_layout() is called. The size is a iterm2.util.Size.

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

A string describing the session.

property session_id: str
Returns:

the globally unique identifier for this session.

property tab: Optional[iterm2.tab.Tab]

Returns the containing tab.

property window: Optional[iterm2.window.Window]

Returns the containing terminal window.

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)

Describes a session’s geometry.

property first_visible_line_number: int

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

property mutable_area_height: int

Returns the height of the mutable area of the session.

property overflow: int

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

property scrollback_buffer_height: int

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.

property children: List[Union[iterm2.session.Splitter, iterm2.session.Session]]
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.

property sessions: List[iterm2.session.Session]
Returns:

All sessions in this splitter and all nested splitters. A list of Session objects.

property vertical: bool

Are the dividers in this splitter vertical?

Indices and tables