Notifications

Subscribe/unsubscribe from async notifications.

This module provides functions that let you subscribe and unsubscribe from notifications. iTerm2 posts notifications when some event of interest (for example, a keystroke) occurs. By subscribing to a notifications your async callback will be run when the event occurs.

async_unsubscribe(connection, token)

Unsubscribes from a notification.

Parameters:
  • connection – A connected Connection.
  • token – The result of a previous subscribe call.
async_subscribe_to_new_session_notification(connection, callback)

Registers a callback to be run when a new session is created.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.NewSessionNotification.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_keystroke_notification(connection, callback, session=None, patterns_to_ignore=[])

Registers a callback to be run when a key is pressed.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.KeystrokeNotification.
  • session – The session to monitor, or None.
  • patterns_to_ignore – A list of keystroke patterns that iTerm2 should not handle, expecting the script will handle it alone. Objects are class KeystrokePattern.

Returns: A token that can be passed to unsubscribe.

async_subscribe_to_screen_update_notification(connection, callback, session=None)

Registers a callback to be run when the screen contents change.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.ScreenUpdateNotification..
  • session – The session to monitor, or None.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_prompt_notification(connection, callback, session=None)

Registers a callback to be run when a shell prompt is received.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.PromptNotification.
  • session – The session to monitor, or None.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_location_change_notification(connection, callback, session=None)

Registers a callback to be run when the host or current directory changes.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.LocationChangeNotification.
  • session – The session to monitor, or None.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_custom_escape_sequence_notification(connection, callback, session=None)

Registers a callback to be run when a custom escape sequence is received.

The escape sequence is OSC 1337 ; Custom=id=<identity>:<payload> ST

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.CustomEscapeSequenceNotification.
  • session – The session to monitor, or None.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_terminate_session_notification(connection, callback)

Registers a callback to be run when a session terminates.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.TerminateSessionNotification.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_layout_change_notification(connection, callback)

Registers a callback to be run when the relationship between sessions, tabs, and windows changes.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.LayoutChangedNotification.
Returns:

A token that can be passed to unsubscribe.
async_subscribe_to_focus_change_notification(connection, callback)

Registers a callback to be run when focus changes.

Parameters:
  • connection – A connected Connection.
  • callback – A coroutine taking two arguments: an Connection and iterm2.api_pb2.FocusChangedNotification.
Returns:

A token that can be passed to unsubscribe.
class KeystrokePattern

Describes attributes that select keystrokes.

Keystrokes contain modifiers (e.g., command or option), characters (what characters are generated by the keypress), and characters ignoring modifiers (what characters would be generated if no modifiers were pressed, excepting the shift key).

characters

List of characters that match the pattern. Values are strings (typically one character-long strings).

characters_ignoring_modifiers

List of characters “ignoring modifiers” that match the pattern.

“Ignoring modifiers” mostly means ignoring modifiers other than Shift. It has a lot of surprising edge cases which Apple did not document, so experiment to find how it works.

Values are strings (typically one character-long strings).

forbidden_modifiers

List of modifiers whose presence prevents the pattern from being matched.

Allowed values are: MODIFIER_CONTROL, MODIFIER_OPTION, MODIFIER_COMMAND, MODIFIER_SHIFT, MODIFIER_FUNCTION, MODIFIER_NUMPAD

keycodes

List of numeric keycodes that match the pattern. Values are numbers.

required_modifiers

List of modifiers that are required to match the pattern.

Allowed values are: MODIFIER_CONTROL, MODIFIER_OPTION, MODIFIER_COMMAND, MODIFIER_SHIFT, MODIFIER_FUNCTION, MODIFIER_NUMPAD

Indices and tables