Profile

Provides classes for representing, querying, and modifying iTerm2 profiles.

class Profile(session_id, connection, profile_property_list)

Represents a profile.

If a session_id is set then this is the profile attached to a session. Otherwise, it is a shared profile.

property advanced_working_directory_pane_directory

The advanced working directory pane directory.

Returns

Path.

property advanced_working_directory_pane_setting

The advanced working directory pane setting.

Returns

INITIAL_WORKING_DIRECTORY_xxx, excluding ADVANCED.

property advanced_working_directory_tab_directory

The advanced working directory tab directory.

Returns

Path.

property advanced_working_directory_tab_setting

The advanced working directory tab setting.

Returns

INITIAL_WORKING_DIRECTORY_xxx, excluding ADVANCED.

property advanced_working_directory_window_directory

The advanced working directory window directory.

Returns

Path.

property advanced_working_directory_window_setting

The advanced working directory window setting.

Returns

INITIAL_WORKING_DIRECTORY_xxx, excluding ADVANCED.

property all_properties

Returns the internal dictionary value.

property allow_title_reporting

Returns whether the session title can be reported

Returns

A bool

property allow_title_setting

Returns whether the session title can be changed by escape sequence

Returns

A bool

property ambiguous_double_width

Returns whether ambiguous-width text should be treated as double-width.

Returns

A bool

property ansi_0_color

Returns the ANSI 0 color.

Returns

A Color

property ansi_10_color

Returns the ANSI 10 color.

Returns

A Color

property ansi_11_color

Returns the ANSI 11 color.

Returns

A Color

property ansi_12_color

Returns the ANSI 12 color.

Returns

A Color

property ansi_13_color

Returns the ANSI 13 color.

Returns

A Color

property ansi_14_color

Returns the ANSI 14 color.

Returns

A Color

property ansi_15_color

Returns the ANSI 15 color.

Returns

A Color

property ansi_1_color

Returns the ANSI 1 color.

Returns

A Color

property ansi_2_color

Returns the ANSI 2 color.

Returns

A Color

property ansi_3_color

Returns the ANSI 3 color.

Returns

A Color

property ansi_4_color

Returns the ANSI 4 color.

Returns

A Color

property ansi_5_color

Returns the ANSI 5 color.

Returns

A Color

property ansi_6_color

Returns the ANSI 6 color.

Returns

A Color

property ansi_7_color

Returns the ANSI 7 color.

Returns

A Color

property ansi_8_color

Returns the ANSI 8 color.

Returns

A Color

property ansi_9_color

Returns the ANSI 9 color.

Returns

A Color

property answerback_string

Returns the answerback string.

Returns

A string

property application_keypad_allowed

Returns whether the terminal may be placed in application keypad mode

Returns

A bool

property ascii_anti_aliased

Returns whether ASCII text is anti-aliased.

Returns

A bool

property ascii_ligatures

Returns whether ligatures should be used for ASCII text.

Returns

A bool

static async_get(connection, guids=None) → List[iterm2.profile.Profile]

Fetches all profiles with the specified GUIDs.

Parameters

guids – The profiles to get, or if None then all will be returned.

Returns

A list of Profile objects.

static async_get_default(connection) → iterm2.profile.Profile

Returns the default profile.

async async_set_advanced_working_directory_pane_directory(value: str)

Sets the advanced working directory pane directory.

Parameters

value (str) – Path.

async async_set_advanced_working_directory_pane_setting(value: iterm2.profile.InitialWorkingDirectory)

Sets the advanced working directory pane setting.

Parameters

value (InitialWorkingDirectory) – New value. Excludes Advanced.

async async_set_advanced_working_directory_tab_directory(value: str)

Sets the advanced working directory tab directory.

Parameters

value (str) – Path.

async async_set_advanced_working_directory_tab_setting(value: iterm2.profile.InitialWorkingDirectory)

Sets the advanced working directory tab setting.

Parameters

value (InitialWorkingDirectory) – New value. Excludes Advanced.

async async_set_advanced_working_directory_window_directory(value: str)

Sets the advanced working directory window directory.

Parameters

value (str) – Path.

async async_set_advanced_working_directory_window_setting(value: iterm2.profile.InitialWorkingDirectory)

Sets the advanced working directory window setting.

Parameters

value (InitialWorkingDirectory) – New value. Excludes Advanced.

async async_set_allow_title_reporting(value: bool)

Sets whether the session title can be reported

Parameters

value (bool) – A bool

async async_set_allow_title_setting(value: bool)

Sets whether the session title can be changed by escape sequence

Parameters

value (bool) – A bool

async async_set_ambiguous_double_width(value: bool)

Sets whether ambiguous-width text should be treated as double-width.

Parameters

value (bool) – A bool

async async_set_ansi_0_color(value: iterm2.color.Color)

Sets the ANSI 0 color.

Parameters

value – A Color

async async_set_ansi_10_color(value: iterm2.color.Color)

Sets the ANSI 10 color.

Parameters

value – A Color

async async_set_ansi_11_color(value: iterm2.color.Color)

Sets the ANSI 11 color.

Parameters

value – A Color

async async_set_ansi_12_color(value: iterm2.color.Color)

Sets the ANSI 12 color.

Parameters

value – A Color

async async_set_ansi_13_color(value: iterm2.color.Color)

Sets the ANSI 13 color.

Parameters

value – A Color

async async_set_ansi_14_color(value: iterm2.color.Color)

Sets the ANSI 14 color.

Parameters

value – A Color

async async_set_ansi_15_color(value: iterm2.color.Color)

Sets the ANSI 15 color.

Parameters

value – A Color

async async_set_ansi_1_color(value: iterm2.color.Color)

Sets the ANSI 1 color.

Parameters

value – A Color

async async_set_ansi_2_color(value: iterm2.color.Color)

Sets the ANSI 2 color.

Parameters

value – A Color

async async_set_ansi_3_color(value: iterm2.color.Color)

Sets the ANSI 3 color.

Parameters

value – A Color

async async_set_ansi_4_color(value: iterm2.color.Color)

Sets the ANSI 4 color.

Parameters

value – A Color

async async_set_ansi_5_color(value: iterm2.color.Color)

Sets the ANSI 5 color.

Parameters

value – A Color

async async_set_ansi_6_color(value: iterm2.color.Color)

Sets the ANSI 6 color.

Parameters

value – A Color

async async_set_ansi_7_color(value: iterm2.color.Color)

Sets the ANSI 7 color.

Parameters

value – A Color

async async_set_ansi_8_color(value: iterm2.color.Color)

Sets the ANSI 8 color.

Parameters

value – A Color

async async_set_ansi_9_color(value: iterm2.color.Color)

Sets the ANSI 9 color.

Parameters

value – A Color

async async_set_answerback_string(value: str)

Sets the answerback string.

Parameters

value (str) – A string

async async_set_application_keypad_allowed(value: bool)

Sets whether the terminal may be placed in application keypad mode

Parameters

value (bool) – A bool

async async_set_ascii_anti_aliased(value: bool)

Sets whether ASCII text is anti-aliased.

Parameters

value (bool) – A bool

async async_set_ascii_ligatures(value: bool)

Sets whether ligatures should be used for ASCII text.

Parameters

value (bool) – A bool

async async_set_automatic_profile_switching_rules(value: List[str])

Sets the automatic profile switching rules.

Parameters

value – A list of rules (strings).

async async_set_background_color(value: iterm2.color.Color)

Sets the background color.

Parameters

value – A Color

async async_set_background_image_location(value: str)

Sets path to the background image.

Parameters

value (str) – Path.

async async_set_background_image_mode(value: iterm2.profile.BackgroundImageMode)

Sets how the background image is draw.

Parameters

value (BackgroundImageMode) – The new value.

async async_set_badge_color(value: iterm2.color.Color)

Sets the badge color. The alpha value is respected.

Parameters

value – A Color

async async_set_badge_text(value: iterm2.color.Color)

Sets the badge text.

Parameters

value – A Color

async async_set_blend(value: float)

Sets how much the default background color gets blended with the background image.

See also

Example “Modify Background Image Blending

Parameters

value (float) – A float in 0 to 1

Sets whether blinking text is allowed.

Parameters

value (bool) – A bool

async async_set_blinking_cursor(value: bool)

Sets whether the cursor blinks.

Parameters

value (bool) – A bool

async async_set_blur(value: bool)

Sets whether background blur should be enabled.

Parameters

value (bool) – A bool

async async_set_blur_radius(value: float)

Sets the blur radius (how blurry). Requires blur to be enabled.

Parameters

value (float) – A float between 0 and 30

async async_set_bm_growl(value: bool)

Sets whether notifications should be shown.

Parameters

value (bool) – A bool

async async_set_bold_color(value: iterm2.color.Color)

Sets the bold text color.

Parameters

value – A Color

async async_set_character_encoding(value: iterm2.profile.CharacterEncoding)

Sets the character encoding

Parameters

value (CharacterEncoding) – The new value.

async async_set_close_sessions_on_end(value: bool)

Sets whether the session should close when it ends.

Parameters

value (bool) – A bool

async async_set_color_preset(preset: iterm2.colorpresets.ColorPreset)

Sets the color preset.

Parameters

preset (ColorPreset) – The new value.

See also

async async_set_cursor_boost(value: float)

Sets the cursor boost level.

Parameters

value (float) – A float in 0 to 1

async async_set_cursor_color(value: iterm2.color.Color)

Sets the cursor color.

Parameters

value – A Color

async async_set_cursor_guide_color(value: iterm2.color.Color)

Sets the cursor guide color. The alpha value is respected.

Parameters

value – A Color

async async_set_cursor_text_color(value: iterm2.color.Color)

Sets the cursor text color.

Parameters

value – A Color

async async_set_cursor_type(value: iterm2.profile.CursorType)

Sets the cursor type

Parameters

value (CursorType) – The new value.

async async_set_disable_printing(value: bool)

Sets whether printing by escape sequence is disabled.

Parameters

value (bool) – A bool

async async_set_disable_smcup_rmcup(value: bool)

Sets whether alternate screen mode is disabled

Parameters

value (bool) – A bool

async async_set_disable_window_resizing(value: bool)

Sets whether the terminal can resize the window with an escape sequence.

Parameters

value (bool) – A bool

async async_set_flashing_bell(value: bool)

Sets whether the bell should flash the screen

Parameters

value (bool) – A bool

async async_set_foreground_color(value: iterm2.color.Color)

Sets the foreground color.

Parameters

value – A Color

async async_set_horizontal_spacing(value: float)

Sets the fraction of horizontal spacing.

Parameters

value (float) – A float at least 0

async async_set_idle_code(value: int)

Sets the ASCII code to send on idle

Parameters

value (int) – An int in 0…255

async async_set_idle_period(value: float)

Sets how often to send a code when idle

Parameters

value (float) – A float at least 0

async async_set_key_mappings(value: Dict[str, Any])

Sets the keyboard shortcuts.

Parameters

value – Dictionary mapping keystroke to action.

async async_set_left_option_key_sends(value: iterm2.profile.OptionKeySends)

Sets the behavior of the left option key.

Parameters

value (OptionKeySends) – The new value.

Sets the link color.

Parameters

value – A Color

async async_set_minimum_contrast(value: float)

Sets the minimum contrast.

Parameters

value (float) – A float in 0 to 1

async async_set_mouse_reporting(value: bool)

Sets whether mouse reporting is allowed

Parameters

value (bool) – A bool

async async_set_mouse_reporting_allow_mouse_wheel(value: bool)

Sets whether mouse reporting reports the mouse wheel’s movements.

Parameters

value (bool) – A bool

async async_set_name(value: str)

Sets the name.

Parameters

value (str) – A string

async async_set_non_ascii_anti_aliased(value: bool)

Sets whether non-ASCII text is anti-aliased.

Parameters

value (bool) – A bool

async async_set_non_ascii_ligatures(value: bool)

Sets whether ligatures should be used for non-ASCII text.

Parameters

value (bool) – A bool

async async_set_normal_font(value: str)

Sets the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii.

Parameters

value (str) – Font name and size as a string.

async async_set_normal_font(value: str)

Sets the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii.

Parameters

value (str) – Font name and size as a string.

async async_set_only_the_default_bg_color_uses_transparency(value: bool)

Sets whether window transparency shows through non-default background colors.

Parameters

value (bool) – A bool

async async_set_place_prompt_at_first_column(value: bool)

Sets whether the prompt should always begin at the first column (requires shell integration)

Parameters

value (bool) – A bool

async async_set_prompt_before_closing(value: bool)

Sets whether the session should prompt before closign

Parameters

value (bool) – A bool

async async_set_reduce_flicker(value: bool)

Sets whether the flicker fixer is on.

Parameters

value (bool) – A bool

async async_set_right_option_key_sends(value: iterm2.profile.OptionKeySends)

Sets the behavior of the right option key.

Parameters

value (OptionKeySends) – The new value.

async async_set_scrollback_in_alternate_screen(value: bool)

Sets whether text gets appended to scrollback in alternate screen mode.

Parameters

value (bool) – A bool

async async_set_scrollback_lines(value: int)

Sets the number of scrollback lines.

Parameters

value (int) – An int at least 0

async async_set_scrollback_with_status_bar(value: bool)

Sets whether text gets appended to scrollback when there is an app status bar

Parameters

value (bool) – A bool

async async_set_selected_text_color(value: iterm2.color.Color)

Sets the selection text color.

Parameters

value – A Color

async async_set_selection_color(value: iterm2.color.Color)

Sets the selection background color.

Parameters

value – A Color

async async_set_semantic_history(value: Dict[str, Any])

Sets the semantic history prefs.

Parameters

value – Semantic history settings dict.

async async_set_send_bell_alert(value: bool)

Sets whether notifications should be shown for the bell ringing

Parameters

value (bool) – A bool

async async_set_send_code_when_idle(value: bool)

Sets whether to send a code when idle

Parameters

value (bool) – A bool

async async_set_send_idle_alert(value: bool)

Sets whether notifications should be shown for becoming idle

Parameters

value (bool) – A bool

async async_set_send_new_output_alert(value: bool)

Sets whether notifications should be shown for new output

Parameters

value (bool) – A bool

async async_set_send_session_ended_alert(value: bool)

Sets whether notifications should be shown for a session ending

Parameters

value (bool) – A bool

async async_set_send_terminal_generated_alerts(value: bool)

Sets whether notifications should be shown for escape-sequence originated notifications

Parameters

value (bool) – A bool

async async_set_session_close_undo_timeout(value: float)

Sets amount of time you can undo closing a session

Parameters

value (float) – A float at least 0

async async_set_show_mark_indicators(value: bool)

Sets whether mark indicators should be visible

Parameters

value (bool) – A bool

async async_set_silence_bell(value: bool)

Sets whether the bell makes noise.

Parameters

value (bool) – A bool

async async_set_smart_cursor_color(value: iterm2.color.Color)

Sets the smart cursor color.

Parameters

value – A Color

async async_set_smart_cursor_color(value: iterm2.color.Color)

Sets the smart cursor color.

Parameters

value – A Color

async async_set_smart_selection_rules(value: List[Dict[str, Any]])

Sets the smart selection rules.

Parameters

value – A list of dicts of smart selection rules

async async_set_sync_title(value: bool)

Sets whether the profile name stays in the tab title, even if changed by an escape sequence.

Parameters

value (bool) – A bool

async async_set_tab_color(value: iterm2.color.Color)

Sets the tab color.

Parameters

value – A Color

async async_set_thin_strokes(value: iterm2.profile.ThinStrokes)

Sets whether thin strokes are used.

Parameters

value (ThinStrokes) – The new value.

async async_set_touchbar_mappings(value: Dict[str, Any])

Sets the touchbar actions.

Parameters

value – Dictionary mapping touch bar item to action.

async async_set_transparency(value: float)

Sets the level of transparency.

Parameters

value (float) – A float between 0 and 1

async async_set_triggers(value: List[Dict[str, Any]])

Sets the triggers.

Parameters

value – A list of dicts of trigger definitions.

async async_set_underline_color(value: iterm2.color.Color)

Sets the underline color.

Parameters

value – A Color or None

async async_set_unicode_normalization(value: iterm2.profile.UnicodeNormalization)

Sets the unicode normalization form to use

Parameters

value (UnicodeNormalization) – The new value.

async async_set_unicode_version(value: bool)

Sets the unicode version for wcwidth

Parameters

value (bool) – A bool

async async_set_unlimited_scrollback(value: bool)

Sets whether the scrollback buffer’s length is unlimited.

Parameters

value (bool) – A bool

async async_set_use_bold_font(value: bool)

Sets whether to use the bold variant of the font for bold text.

Parameters

value (bool) – A bool

async async_set_use_bright_bold(value: bool)

Sets whether bright colors should be used for bold text.

Parameters

value (bool) – A bool

async async_set_use_cursor_guide(value: bool)

Sets whether the cursor guide should be used.

Parameters

value (bool) – A boolean

async async_set_use_italic_font(value: bool)

Sets whether italic text is allowed.

Parameters

value (bool) – A bool

async async_set_use_non_ascii_font(value: bool)

Sets whether to use a different font for non-ASCII text.

Parameters

value (bool) – A bool

async async_set_use_tab_color(value: str)

Sets whether the tab color should be used.

Parameters

value (str) – A string

async async_set_use_underline_color(value: iterm2.color.Color)

Sets the underline color.

Parameters

value – A Color

async async_set_vertical_spacing(value: float)

Sets the fraction of vertical spacing.

Parameters

value (float) – A float at least 0

async async_set_visual_bell(value: bool)

Sets whether a bell should be shown when the bell rings

Parameters

value (bool) – A bool

property automatic_profile_switching_rules

The automatic profile switching rules.

Returns

A list of rules (strings).

property background_color

Returns the background color.

Returns

A Color

property background_image_location

Gets path to the background image.

Returns

Path.

property background_image_mode

Returns how the background image is drawn

Returns

A BackgroundImageMode

property badge_color

Returns the badge color. The alpha value is respected.

Returns

A Color

property badge_text

Returns the badge text.

Returns

A Color

property blend

Returns tow much the default background color gets blended with the background image.

Returns

A float in 0 to 1

Returns whether blinking text is allowed.

Returns

A bool

property blinking_cursor

Returns whether the cursor blinks.

Returns

A bool

property blur

Returns whether background blur should be enabled.

Returns

A bool

property blur_radius

Returns the blur radius (how blurry). Requires blur to be enabled.

Returns

A float between 0 and 30

property bm_growl

Returns whether notifications should be shown.

Returns

A bool

property bold_color

Returns the bold text color.

Returns

A Color

property character_encoding

Returns the character encoding

Returns

CHARACTER_ENCODING_xxx

property close_sessions_on_end

Returns whether the session should close when it ends.

Returns

A bool

property command

“The command to run when the session starts.

Returns

The command to run, provided use_custom_command is True.

property cursor_boost

Returns the cursor boost level.

Returns

A float in 0 to 1

property cursor_color

Returns the cursor color.

Returns

A Color

property cursor_guide_color

Returns the cursor guide color. The alpha value is respected.

Returns

A Color

property cursor_text_color

Returns the cursor text color.

Returns

A Color

property cursor_type

Returns the cursor type.

property custom_directory

Returns the initial working directory.

The initial_directory_mode must be set to InitialWorkingDirectory.INITIAL_WORKING_DIRECTORY_CUSTOM for this to take effect.

Returns

The specific directory this profile has been set to start in.

property disable_printing

Returns whether printing by escape sequence is disabled.

Returns

A bool

property disable_smcup_rmcup

Returns whether alternate screen mode is disabled

Returns

A bool

property disable_window_resizing

Returns whether the terminal can resize the window with an escape sequence.

Returns

A bool

property dynamic_profile_file_name

If the profile is a dynamic profile, returns the path to the file from which it came.

Returns

String file name

property dynamic_profile_parent_name

If the profile is a dynamic profile, returns the name of the parent profile.

Returns

String name

property flashing_bell

Returns whether the bell should flash the screen

Returns

A bool

property foreground_color

Returns the foreground color.

Returns

A Color

property guid

Returns globally unique ID for this profile.

Returns

A string identifying this profile

property horizontal_spacing

Returns the fraction of horizontal spacing.

Returns

A float at least 0

property idle_code

Returns the ASCII code to send on idle

Returns

An int in 0…255

property idle_period

Returns how often to send a code when idle

Returns

A float at least 0

property initial_directory_mode

Returns wether to use a custom (not home) initial working directory.

Returns

A value in InitialWorkingDirectory.

property key_mappings

The keyboard shortcuts.

Returns

Dictionary mapping keystroke to action.

property left_option_key_sends

Returns the behavior of the left option key.

Returns

OPTION_KEY_xxx

Returns the link color.

Returns

A Color

property local_write_only_copy

Returns a LocalWriteOnlyProfile containing the properties in this profile.

property minimum_contrast

Returns the minimum contrast.

Returns

A float in 0 to 1

property mouse_reporting

Returns whether mouse reporting is allowed

Returns

A bool

property mouse_reporting_allow_mouse_wheel

Returns whether mouse reporting reports the mouse wheel’s movements.

Returns

A bool

property name

Returns the name.

Returns

A string

property non_ascii_anti_aliased

Returns whether non-ASCII text is anti-aliased.

Returns

A bool

property non_ascii_font

The non-ASCII font.

This is used for non-ASCII characters if use_non_ascii_font is enabled.

Returns

Font name and size as a string.

property non_ascii_ligatures

Returns whether ligatures should be used for non-ASCII text.

Returns

A bool

property normal_font

The normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii.

Returns

Font name and size as a string.

See also

property only_the_default_bg_color_uses_transparency

Returns whether window transparency shows through non-default background colors.

Returns

A bool

property original_guid

The GUID of the original profile from which this one was derived.

Used for sessions whose profile has been modified from the underlying profile. Otherwise not set.

Returns

Guid

property place_prompt_at_first_column

Returns whether the prompt should always begin at the first column (requires shell integration)

Returns

A bool

property prompt_before_closing

Returns whether the session should prompt before closign

Returns

A bool

property reduce_flicker

Returns whether the flicker fixer is on.

Returns

A bool

property right_option_key_sends

Returns the behavior of the right option key.

Returns

OPTION_KEY_xxx

property scrollback_in_alternate_screen

Returns whether text gets appended to scrollback in alternate screen mode

Returns

A bool

property scrollback_lines

Returns the number of scrollback lines.

Returns

An int at least 0

property scrollback_with_status_bar

Returns whether text gets appended to scrollback when there is an app status bar

Returns

A bool

property selected_text_color

Returns the selection text color.

Returns

A Color

property selection_color

Returns the selection background color.

Returns

A Color

property semantic_history

The semantic history prefs.

Returns

Semantic history settings dict.

property send_bell_alert

Returns whether notifications should be shown for the bell ringing

Returns

A bool

property send_code_when_idle

Returns whether to send a code when idle

Returns

A bool

property send_idle_alert

Returns whether notifications should be shown for becoming idle

Returns

A bool

property send_new_output_alert

Returns whether notifications should be shown for new output

Returns

A bool

property send_session_ended_alert

Returns whether notifications should be shown for a session ending

Returns

A bool

property send_terminal_generated_alerts

Returns whether notifications should be shown for escape-sequence originated notifications

Returns

A bool

property session_close_undo_timeout

Returns tmount of time you can undo closing a session

Returns

A float at least 0

property show_mark_indicators

Returns whether mark indicators should be visible

Returns

A bool

property silence_bell

Returns whether the bell makes noise.

Returns

A bool

property smart_cursor_color

Returns whether smart cursor color is in use for box cursors.

Returns

A Color

property smart_cursor_color

Returns whether smart cursor color is in use for box cursors.

Returns

A Color

property smart_selection_rules

The smart selection rules.

Returns

A list of dicts of smart selection rules

property sync_title

Returns whether the profile name stays in the tab title, even if changed by an escape sequence.

Returns

A bool

property tab_color

Returns the tab color.

Returns

A Color

property thin_strokes

Returns whether thin strokes are used.

Returns

THIN_STROKES_SETTING_xxx

property touchbar_mappings

The touchbar actions.

Returns

Dictionary mapping touch bar item to action.

property transparency

Returns the level of transparency.

Returns

A float between 0 and 1

property triggers

The triggers.

Returns

A list of dicts of trigger definitions.

property underline_color

Returns the underline color.

Returns

A Color or None

property unicode_normalization

Returns the unicode normalization form to use

Returns

UNICODE_NORMALIZATION_xxx

property unicode_version

Returns the unicode version for wcwidth

Returns

A bool

property unlimited_scrollback

Returns whether the scrollback buffer’s length is unlimited.

Returns

A bool

property use_bold_font

Returns whether to use the bold variant of the font for bold text.

Returns

A bool

property use_bright_bold

Returns whether bright colors should be used for bold text.

Returns

A bool

property use_cursor_guide

Returns whether the cursor guide should be used.

Returns

A boolean

property use_custom_command

” Returns whether to use a custom command when the session is created.

Returns

Boolean, whether to use a custom command.

property use_italic_font

Returns whether italic text is allowed.

Returns

A bool

property use_non_ascii_font

Returns whether to use a different font for non-ASCII text.

Returns

A bool

property use_tab_color

Returns whether the tab color should be used.

Returns

A string

property use_underline_color

Returns the underline color.

Returns

A Color

property vertical_spacing

Returns the fraction of vertical spacing.

Returns

A float at least 0

property visual_bell

Returns whether a bell should be shown when the bell rings

Returns

A bool

class LocalWriteOnlyProfile(values=None)

A profile that can be modified but not read and does not send changes on each write.

You can safely create this with LocalWriteOnlyProfile(). Use async_set_profile_properties() to update a session without modifying the underlying profile.

See also

set_advanced_working_directory_pane_directory(value: str)

Sets the advanced working directory pane directory.

Parameters

value (str) – Path.

set_advanced_working_directory_pane_setting(value: iterm2.profile.InitialWorkingDirectory)

Sets the advanced working directory pane setting.

Parameters

value (InitialWorkingDirectory) – The new value. Excludes Advanced.

set_advanced_working_directory_tab_directory(value: str)

Sets the advanced working directory tab directory.

Parameters

value (str) – Path.

set_advanced_working_directory_tab_setting(value: iterm2.profile.InitialWorkingDirectory)

Sets the advanced working directory tab setting.

Parameters

value (InitialWorkingDirectory) – The new value. Excludes Advanced.

set_advanced_working_directory_window_directory(value: str)

Sets the advanced working directory window directory.

Parameters

value (str) – Path.

set_advanced_working_directory_window_setting(value: iterm2.profile.InitialWorkingDirectory)

Sets the advanced working directory window setting.

Parameters

value (InitialWorkingDirectory) – The new value. Excludes Advanced.

set_allow_title_reporting(value: bool)

Sets whether the session title can be reported

Parameters

value (bool) – A bool

set_allow_title_setting(value: bool)

Sets whether the session title can be changed by escape sequence

Parameters

value (bool) – A bool

set_ambiguous_double_width(value: bool)

Sets whether ambiguous-width text should be treated as double-width.

Parameters

value (bool) – A bool

set_ansi_0_color(value: iterm2.color.Color)

Sets the ANSI 0 color.

Parameters

value – A Color

set_ansi_10_color(value: iterm2.color.Color)

Sets the ANSI 10 color.

Parameters

value – A Color

set_ansi_11_color(value: iterm2.color.Color)

Sets the ANSI 11 color.

Parameters

value – A Color

set_ansi_12_color(value: iterm2.color.Color)

Sets the ANSI 12 color.

Parameters

value – A Color

set_ansi_13_color(value: iterm2.color.Color)

Sets the ANSI 13 color.

Parameters

value – A Color

set_ansi_14_color(value: iterm2.color.Color)

Sets the ANSI 14 color.

Parameters

value – A Color

set_ansi_15_color(value: iterm2.color.Color)

Sets the ANSI 15 color.

Parameters

value – A Color

set_ansi_1_color(value: iterm2.color.Color)

Sets the ANSI 1 color.

Parameters

value – A Color

set_ansi_2_color(value: iterm2.color.Color)

Sets the ANSI 2 color.

Parameters

value – A Color

set_ansi_3_color(value: iterm2.color.Color)

Sets the ANSI 3 color.

Parameters

value – A Color

set_ansi_4_color(value: iterm2.color.Color)

Sets the ANSI 4 color.

Parameters

value – A Color

set_ansi_5_color(value: iterm2.color.Color)

Sets the ANSI 5 color.

Parameters

value – A Color

set_ansi_6_color(value: iterm2.color.Color)

Sets the ANSI 6 color.

Parameters

value – A Color

set_ansi_7_color(value: iterm2.color.Color)

Sets the ANSI 7 color.

Parameters

value – A Color

set_ansi_8_color(value: iterm2.color.Color)

Sets the ANSI 8 color.

Parameters

value – A Color

set_ansi_9_color(value: iterm2.color.Color)

Sets the ANSI 9 color.

Parameters

value – A Color

set_answerback_string(value: str)

Sets the answerback string.

Parameters

value (str) – A string

set_application_keypad_allowed(value: bool)

Sets whether the terminal may be placed in application keypad mode

Parameters

value (bool) – A bool

set_ascii_anti_aliased(value: bool)

Sets whether ASCII text is anti-aliased.

Parameters

value (bool) – A bool

set_ascii_ligatures(value: bool)

Sets whether ligatures should be used for ASCII text.

Parameters

value (bool) – A bool

set_automatic_profile_switching_rules(value: List[str])

Sets the automatic profile switching rules.

Parameters

value – A list of rules (strings).

set_background_color(value: iterm2.color.Color)

Sets the background color.

Parameters

value – A Color

set_background_image_location(value: str)

Sets path to the background image.

Parameters

value (str) – Path.

set_background_image_mode(value: iterm2.profile.BackgroundImageMode)

Sets how the background image is drawn.

Parameters

value (BackgroundImageMode) – A BackgroundImageMode

set_badge_color(value: iterm2.color.Color)

Sets the badge color. The alpha value is respected.

Parameters

value – A Color

set_badge_text(value: str)

Sets the badge text.

Parameters

value (str) – A Color

set_blend(value: float)

Sets how much the default background color gets blended with the background image.

Parameters

value (float) – A float in 0 to 1

Sets whether blinking text is allowed.

Parameters

value (bool) – A bool

set_blinking_cursor(value: bool)

Sets whether the cursor blinks.

Parameters

value (bool) – A bool

set_blur(value: bool)

Sets whether background blur should be enabled.

Parameters

value (bool) – A bool

set_blur_radius(value: float)

Sets the blur radius (how blurry). Requires blur to be enabled.

Parameters

value (float) – A float between 0 and 30

set_bm_growl(value: bool)

Sets whether notifications should be shown.

Parameters

value (bool) – A bool

set_bold_color(value: iterm2.color.Color)

Sets the bold text color.

Parameters

value – A Color

set_character_encoding(value: iterm2.profile.CharacterEncoding)

Sets the character encoding

Parameters

value (CharacterEncoding) – The new value.

set_close_sessions_on_end(value: bool)

Sets whether the session should close when it ends.

Parameters

value (bool) – A bool

set_command(value: str)

“The command to run when the session starts.

custom_command must be set to “Yes” or this will be ignored.

Parameters

value (str) – A string giving the command to run.

set_cursor_boost(value: float)

Sets the cursor boost level.

Parameters

value (float) – A float in 0 to 1

set_cursor_color(value: iterm2.color.Color)

Sets the cursor color.

Parameters

value – A Color

set_cursor_guide_color(value: iterm2.color.Color)

Sets the cursor guide color. The alpha value is respected.

Parameters

value – A Color

set_cursor_text_color(value: iterm2.color.Color)

Sets the cursor text color.

Parameters

value – A Color

set_cursor_type(value: iterm2.profile.CursorType)

Sets the cursor type

Parameters

value (CursorType) – The new value

set_custom_directory(value: str)

Sets the initial working directory.

The initial_directory_mode must be set to InitialWorkingDirectory.INITIAL_WORKING_DIRECTORY_CUSTOM for this to take effect.

set_disable_printing(value: bool)

Sets whether printing by escape sequence is disabled.

Parameters

value (bool) – A bool

set_disable_smcup_rmcup(value: bool)

Sets whether alternate screen mode is disabled

Parameters

value (bool) – A bool

set_disable_window_resizing(value: bool)

Sets whether the terminal can resize the window with an escape sequence.

Parameters

value (bool) – A bool

set_flashing_bell(value: bool)

Sets whether the bell should flash the screen

Parameters

value (bool) – A bool

set_foreground_color(value: iterm2.color.Color)

Sets the foreground color.

Parameters

value – A Color

set_horizontal_spacing(value: float)

Sets the fraction of horizontal spacing.

Parameters

value (float) – A float at least 0

set_idle_code(value: int)

Sets the ASCII code to send on idle

Parameters

value (int) – An int in 0…255

set_idle_period(value: float)

Sets how often to send a code when idle

Parameters

value (float) – A float at least 0

set_initial_directory_mode(value: iterm2.profile.InitialWorkingDirectory)

Sets whether to use a custom (not home) initial working directory.

Parameters

value (InitialWorkingDirectory) – The new value.

set_key_mappings(value: Dict[str, str])

Sets the keyboard shortcuts.

Parameters

value – Dictionary mapping keystroke to action.

set_left_option_key_sends(value: iterm2.profile.OptionKeySends)

Sets the behavior of the left option key.

Parameters

value (OptionKeySends) – The new value.

Sets the link color.

Parameters

value – A Color

set_minimum_contrast(value: float)

Sets the minimum contrast.

Parameters

value (float) – A float in 0 to 1

set_mouse_reporting(value: bool)

Sets whether mouse reporting is allowed

Parameters

value (bool) – A bool

set_mouse_reporting_allow_mouse_wheel(value: bool)

Sets whether mouse reporting reports the mouse wheel’s movements.

Parameters

value (bool) – A bool

set_name(value: str)

Sets the name.

Parameters

value (str) – A string

set_non_ascii_anti_aliased(value: bool)

Sets whether non-ASCII text is anti-aliased.

Parameters

value (bool) – A bool

set_non_ascii_ligatures(value: bool)

Sets whether ligatures should be used for non-ASCII text.

Parameters

value (bool) – A bool

set_normal_font(value: str)

Sets the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii.

Parameters

value (str) – Font name and size as a string.

See also

set_normal_font(value: str)

Sets the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii.

Parameters

value (str) – Font name and size as a string.

See also

set_only_the_default_bg_color_uses_transparency(value: bool)

Sets whether window transparency shows through non-default background colors.

Parameters

value (bool) – A bool

set_place_prompt_at_first_column(value: bool)

Sets whether the prompt should always begin at the first column (requires shell integration)

Parameters

value (bool) – A bool

set_prompt_before_closing(value: bool)

Sets whether the session should prompt before closign

Parameters

value (bool) – A bool

set_reduce_flicker(value: bool)

Sets whether the flicker fixer is on.

Parameters

value (bool) – A bool

set_right_option_key_sends(value: iterm2.profile.OptionKeySends)

Sets the behavior of the right option key.

Parameters

value (OptionKeySends) – The new value.

set_scrollback_in_alternate_screen(value: bool)

Sets whether text gets appended to scrollback in alternate screen mode

Parameters

value (bool) – A bool

set_scrollback_lines(value: int)

Sets the number of scrollback lines.

Parameters

value (int) – An int at least 0

set_scrollback_with_status_bar(value: bool)

Sets whether text gets appended to scrollback when there is an app status bar

Parameters

value (bool) – A bool

set_selected_text_color(value: iterm2.color.Color)

Sets the selection text color.

Parameters

value – A Color

set_selection_color(value: iterm2.color.Color)

Sets the selection background color.

Parameters

value – A Color

set_semantic_history(value: Dict[str, Any])

Sets the semantic history prefs.

Parameters

value – Semantic history settings dict.

set_send_bell_alert(value: bool)

Sets whether notifications should be shown for the bell ringing

Parameters

value (bool) – A bool

set_send_code_when_idle(value: bool)

Sets whether to send a code when idle

Parameters

value (bool) – A bool

set_send_idle_alert(value: bool)

Sets whether notifications should be shown for becoming idle

Parameters

value (bool) – A bool

set_send_new_output_alert(value: bool)

Sets whether notifications should be shown for new output

Parameters

value (bool) – A bool

set_send_session_ended_alert(value: bool)

Sets whether notifications should be shown for a session ending

Parameters

value (bool) – A bool

set_send_terminal_generated_alerts(value: bool)

Sets whether notifications should be shown for escape-sequence originated notifications

Parameters

value (bool) – A bool

set_session_close_undo_timeout(value: float)

Sets amount of time you can undo closing a session

Parameters

value (float) – A float at least 0

set_show_mark_indicators(value: bool)

Sets whether mark indicators should be visible

Parameters

value (bool) – A bool

set_silence_bell(value: bool)

Sets whether the bell makes noise.

Parameters

value (bool) – A bool

set_smart_cursor_color(value: iterm2.color.Color)

Sets the smart cursor color.

Parameters

value – A Color

set_smart_selection_rules(value: List[Dict[str, Any]])

Sets the smart selection rules.

Parameters

value – A list of dicts of smart selection rules

set_sync_title(value: bool)

Sets whether the profile name stays in the tab title, even if changed by an escape sequence.

Parameters

value (bool) – A bool

set_tab_color(value: iterm2.color.Color)

Sets the tab color.

Parameters

value – A Color

set_thin_strokes(value: iterm2.profile.ThinStrokes)

Sets whether thin strokes are used.

Parameters

value (ThinStrokes) – The new value.

set_touchbar_mappings(value: Dict[str, str])

Sets the touchbar actions.

Parameters

value – Dictionary mapping touch bar item to action.

set_transparency(value: float)

Sets the level of transparency.

Parameters

value (float) – A float between 0 and 1

set_triggers(value: List[Dict[str, Any]])

Sets the triggers.

Parameters

value – A list of dicts of trigger definitions.

set_underline_color(value: iterm2.color.Color)

Sets the underline color.

Parameters

value – A Color or None

set_unicode_normalization(value: iterm2.profile.UnicodeNormalization)

Sets the unicode normalization form to use

Parameters

value (UnicodeNormalization) – the new value

set_unicode_version(value: bool)

Sets the unicode version for wcwidth

Parameters

value (bool) – A bool

set_unlimited_scrollback(value: bool)

Sets whether the scrollback buffer’s length is unlimited.

Parameters

value (bool) – A bool

set_use_bold_font(value: bool)

Sets whether to use the bold variant of the font for bold text.

Parameters

value (bool) – A bool

set_use_bright_bold(value: bool)

Sets whether bright colors should be used for bold text.

Parameters

value (bool) – A bool

set_use_cursor_guide(value: bool)

Sets whether the cursor guide should be used.

Parameters

value (bool) – A boolean

set_use_custom_command(value: str)

“Sets whether to use a custom command when the session is created.

Parameters

value (str) – The string “Yes” or “No”.

set_use_italic_font(value: bool)

Sets whether italic text is allowed.

Parameters

value (bool) – A bool

set_use_non_ascii_font(value: bool)

Sets whether to use a different font for non-ASCII text.

Parameters

value (bool) – A bool

set_use_tab_color(value: bool)

Sets whether the tab color should be used.

Parameters

value (bool) – A boolean

set_use_underline_color(value: iterm2.color.Color)

Sets the underline color.

Parameters

value – A Color

set_vertical_spacing(value: float)

Sets the fraction of vertical spacing.

Parameters

value (float) – A float at least 0

set_visual_bell(value: bool)

Sets whether a bell should be shown when the bell rings

Parameters

value (bool) – A bool

class PartialProfile(session_id, connection, profile_property_list)

Represents a profile that has only a subset of fields available for reading.

async async_get_full_profile() → iterm2.profile.Profile

Requests a full profile and returns it.

Raises BadGUIDException if the Guid is not set or does not match a profile.

Returns

A Profile.

See also

Example “Change Color Presets On Theme Change

async async_make_default()

Makes this profile the default profile.

static async_query(connection: iterm2.connection.Connection, guids: Optional[List[str]] = None, properties: List[str] = ['Guid', 'Name']) → List[iterm2.profile.PartialProfile]

Fetches a list of profiles by guid, populating the requested properties.

Parameters
  • connection (Connection) – The connection to send the query to.

  • properties – Lists the properties to fetch. Pass None for all. If you wish to fetch the full profile later, you must ensure the ‘Guid’ property is fetched.

  • guids – Lists GUIDs to list. Pass None for all profiles.

Returns

A list of PartialProfile objects with only the specified properties set.

class BackgroundImageMode

Describes how the background image should be accommodated to fit the window.

ASPECT_FILL = 2

Scale to fill the space, cropping if needed. Does not distort.

ASPECT_FIT = 3

Scale to fit the space, adding letterboxes or pillarboxes if needed. Does not distort.

STRETCH = 0

Stretch to fit

TILE = 1

Full size, undistorted, and tessellated if needed.

class CursorType

Describes the type of the cursor.

CURSOR_TYPE_BOX = 2

Box cursor

CURSOR_TYPE_UNDERLINE = 0

Underline cursor

CURSOR_TYPE_VERTICAL = 1

Vertical bar cursor

class ThinStrokes

When thin strokes should be used.

THIN_STROKES_SETTING_ALWAYS = 3

Always.

THIN_STROKES_SETTING_DARK_BACKGROUNDS_ONLY = 2

When the background is dark.

THIN_STROKES_SETTING_NEVER = 0

NEver

THIN_STROKES_SETTING_RETINA_DARK_BACKGROUNDS_ONLY = 1

When the background is dark and the display is a retina display.

THIN_STROKES_SETTING_RETINA_ONLY = 4

When the display is a retina display.

class UnicodeNormalization

How to perform Unicode normalization.

UNICODE_NORMALIZATION_HFSPLUS = 3

Apple’s HFS+ normalization form

UNICODE_NORMALIZATION_NFC = 1

Normalization form C

UNICODE_NORMALIZATION_NFD = 2

Normalization form D

UNICODE_NORMALIZATION_NONE = 0

Do not modify input

class CharacterEncoding

String encodings.

class OptionKeySends

How should the option key behave?

OPTION_KEY_ESC = 2

Adds ESC prefix.

OPTION_KEY_META = 1

Acts like Meta. Not recommended.

OPTION_KEY_NORMAL = 0

Standard behavior

class InitialWorkingDirectory

How should the initial working directory of a session be set?

INITIAL_WORKING_DIRECTORY_ADVANCED = 'Advanced'

Use advanced settings, which specify more granular behavior depending on whether the new session is a new window, tab, or split pane.

INITIAL_WORKING_DIRECTORY_CUSTOM = 'Yes'

Custom directory, specified elsewhere

INITIAL_WORKING_DIRECTORY_HOME = 'No'

Use default of home directory

INITIAL_WORKING_DIRECTORY_RECYCLE = 'Recycle'

Reuse the “current” directory, or home if there is no current.


Indices and tables