Provides access to screen contents.

class ScreenStreamer(connection, session_id, want_contents=True)

An asyncio context manager for monitoring the screen contents.

You can use this to be notified when screen contents change. Optionally, you can receive the actual contents of the screen.

Don’t create this yourself. Use Session.get_screen_streamer() instead. See its docstring for more info.

async async_get() → Union[None, iterm2.screen.ScreenContents]

Blocks until the screen contents change.

If this ScreenStreamer has been configured to provide screen contents, then they will be returned.


A ScreenContents (if so configured), otherwise None.


RPCException if something goes wrong.

class ScreenContents(proto)

Describes screen contents.

property cursor_coord

Returns the location of the cursor.


A Point

line(index: int) → iterm2.screen.LineContents

Returns the LineContents at the given index.

Return type



index (int) – should be at least 0 and less than number_of_lines.


A LineContents object.

property number_of_lines

The number of lines in this object.

property number_of_lines_above_screen

Returns the number of lines before the screen including scrollback history and lines lost from the head of scrollback history.


The number of lines ever received before the top line of the screen.

class LineContents(proto)

Describes the contents of a line.

property hard_eol

True if the line has a hard newline. If False, the text of a longer line wraps onto the next line.

property string

The line’s contents as a string.

string_at(x: int) → str

Returns the string of the cell at index x.

Return type



x (int) – The index to look up.


A string giving the contents of the cell at that index, or empty string if none.

Indices and tables