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 uknown 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