General Information🔗

sublime Module🔗

sublime.version()→str🔗

Returns

The version number.

sublime.platform()→Literal['osx','linux','windows']🔗

Returns

The platform which the plugin is being run on.

sublime.arch()→Literal['x32','x64','arm64']🔗

Returns

The CPU architecture.

sublime.channel()→Literal['dev','stable']🔗

Returns

The release channel of this build of Sublime Text.

sublime.executable_path()→str🔗

This may be called at import time.

4081

Returns

The path to the main Sublime Text executable.

sublime.executable_hash()→tuple[str,str,str]🔗

This may be called at import time.

4081

Returns

A tuple uniquely identifying the installation of Sublime Text.

sublime.packages_path()→str🔗

This may be called at import time.

4081

Returns

The path to the “Packages” folder.

sublime.installed_packages_path()→str🔗

This may be called at import time.

4081

Returns

The path to the “Installed Packages” folder.

sublime.cache_path()→str🔗

This may be called at import time.

4081

Returns

The path where Sublime Text stores cache files.

sublime.status_message(msg:str)🔗

Show a message in the status bar.

sublime.error_message(msg:str)🔗

Display an error dialog.

sublime.message_dialog(msg:str)🔗

Display a message dialog.

sublime.ok_cancel_dialog(msg:str,ok_title='',title='')→bool🔗

Show aok / cancel question dialog.

Parameters

msg

The message to show in the dialog.

ok_title

Text to display on theok button.

title

4099

Title for the dialog. Windows only.

Returns

Whether the user pressed theok button.

sublime.yes_no_cancel_dialog(msg:str,yes_title='',no_title='',title='')→DialogResult🔗

Show ayes / no / cancel question dialog.

Parameters

msg

The message to show in the dialog.

yes_title

Text to display on theyes button.

no_title

Text to display on theno button.

title

4099

Title for the dialog. Windows only.

sublime.run_command(cmd:str,args:CommandArgs=None)🔗

Run the namedApplicationCommand.

sublime.get_clipboard(size_limit:int=16777216)→str🔗

Get the contents of the clipboard.

For performance reasons if the size of the clipboard content is bigger thansize_limit, an empty string will be returned.

Deprecated

Useget_clipboard_async instead.

4075

sublime.set_clipboard(text:str)🔗

Set the contents of the clipboard.

sublime.log_commands(flag:Optional[bool]=None)🔗

Control whether commands are logged to the console when run.

Parameters

flag

Whether to log.Passing None toggles logging.4099

sublime.log_input(flag:Optional[bool]=None)🔗

Control whether all key presses will be logged to the console. Use this tofind the names of certain keys on the keyboard.

Parameters

flag

Whether to log.Passing None toggles logging.4099

sublime.log_result_regex(flag:Optional[bool]=None)🔗

Control whether result regex logging is enabled. Use this to debug"file_regex" and"line_regex" in build systems.

Parameters

flag

Whether to log.Passing None toggles logging.4099

sublime.log_indexing(flag:Optional[bool]=None)🔗

Control whether indexing logs are printed to the console.

Parameters

flag

Whether to log.Passing None toggles logging.4099

sublime.log_build_systems(flag:Optional[bool]=None)🔗

Control whether build system logs are printed to the console.

Parameters

flag

Whether to log.Passing None toggles logging.4099

sublime.score_selector(scope_name:str,selector:str)→int🔗

Match theselector against the givenscope_name, returning a score for how well they match.

A score of0 means no match, above0 means a match. Differentselectors may be compared against the same scope: a higher score means theselector is a better match for the scope.

sublime.load_resource(name:str)→str🔗

Loads the given resource. The name should be in the format “Packages/Default/Main.sublime-menu”.

RaisesFileNotFoundError

if resource is not found

sublime.load_binary_resource(name)→bytes🔗

Loads the given resource. The name should be in the format “Packages/Default/Main.sublime-menu”.

RaisesFileNotFoundError

if resource is not found

sublime.find_resources(pattern:str)→list[str]🔗

Finds resources whose file name matches the given glob pattern.

sublime.encode_value(value:Value,pretty=False,update_text:str=None)→str🔗

Encode a JSON compatibleValue into a string representation.

Parameters

pretty

Whether the result should include newlines and be indented.

update_text

4156

Incrementally update the value encoded in this text. Best effort is madeto preserve the contents ofupdate_text - comments, indentation,etc. This is the same algorithm used to change settings values.Providing this makespretty have no effect.

sublime.decode_value(data:str)→Value🔗

Decode a JSON string into an object. Note that comments and trailing commasare allowed.

RaisesValueError

If the string is not valid JSON.

sublime.expand_variables(value:Value,variables:dict[str,str])→Value🔗

Expands any variables invalue using the variables defined in thedictionaryvariables. value may also be a list or dict, in which case thestructure will be recursively expanded. Strings should use snippet syntax,for example:expand_variables("Hello,${name}",{"name":"Foo"}).

sublime.load_settings(base_name:str)→Settings🔗

Loads the named settings. The name should include a file name and extension,but not a path. The packages will be searched for files matching thebase_name, and the results will be collated into the settings object.

Subsequent calls to load_settings() with the base_name will return the sameobject, and not load the settings from disk again.

sublime.save_settings(base_name:str)🔗

Flush any in-memory changes to the named settings object to disk.

sublime.set_timeout(callback:Callable,delay:int=0)🔗

Run thecallback in the main thread after the givendelay(in milliseconds). Callbacks with an equal delay will be run in the orderthey were added.

sublime.set_timeout_async(callback:Callable,delay:int=0)🔗

Runs the callback on an alternate thread after the given delay(in milliseconds).

sublime.active_window()→Window🔗

Returns

The most recently usedWindow.

sublime.windows()→list[sublime.Window]🔗

Returns

A list of all the open windows.

sublime.get_macro()→list[dict]🔗

Returns

A list of the commands and args that compromise the currentlyrecorded macro. Eachdict will contain the keys"command"and"args".

classsublime.Window🔗

Bases:object

id()→int🔗

Returns

A number that uniquely identifies this window.

is_valid()→bool🔗

Check whether this window is still valid. Will returnFalse for aclosed window, for example.

hwnd()→int🔗

Returns

A platform specific window handle. Windows only.

active_sheet()→Optional[Sheet]🔗

Returns

The currently focusedSheet.

active_view()→Optional[View]🔗

Returns

The currently editedView.

new_html_sheet(name:str,contents:str,flags=NewFileFlags.NONE,group=-1)→Sheet🔗

4065

Construct a sheet with HTML contents rendered usingminihtml Reference.

Parameters

name

The name of the sheet to show in the tab.

contents

The HTML contents of the sheet.

flags

OnlyNewFileFlags.TRANSIENT andNewFileFlags.ADD_TO_SELECTION are allowed.

group

The group to add the sheet to.-1 for the active group.

run_command(cmd:str,args:CommandArgs=None)🔗

Run the namedWindowCommand with the (optional) given args. Thismethod is able to run any sort of command, dispatching the command viainput focus.

new_file(flags=NewFileFlags.NONE,syntax='')→View🔗

Create a new empty file.

Parameters

flags

Either0,NewFileFlags.TRANSIENT orNewFileFlags.ADD_TO_SELECTION.

syntax

The name of the syntax to apply to the file.

Returns

The view for the file.

open_file(fname:str,flags=NewFileFlags.NONE,group=-1)→View🔗

Open the named file. If the file is already opened, it will be broughtto the front. Note that as file loading is asynchronous, operations onthe returned view won’t be possible until itsis_loading() methodreturnsFalse.

Parameters

fname

The path to the file to open.

flags

NewFileFlags

group

The group to add the sheet to.-1 for the active group.

find_open_file(fname:str,group=-1)→Optional[View]🔗

Find a opened file by file name.

Parameters

fname

The path to the file to open.

group

The group in which to search for the file.-1 for any group.

Returns

TheView to the file orNone if the file isn’t open.

file_history()→list[str]🔗

Get the list of previously opened files. This is the same listasFile > Open Recent.

num_groups()→int🔗

Returns

The number of view groups in the window.

active_group()→int🔗

Returns

The index of the currently selected group.

focus_group(idx:int)🔗

Focus the specified group, making it active.

focus_sheet(sheet:Sheet)🔗

Switches to the givenSheet.

focus_view(view:View)🔗

Switches to the givenView.

select_sheets(sheets:list[sublime.Sheet])🔗

4083

Change the selected sheets for the entire window.

bring_to_front()🔗

Bring the window in front of any other windows.

get_sheet_index(sheet:Sheet)→tuple[int,int]🔗

Returns

The a tuple of the group and index within the group of thegivenSheet.

get_view_index(view:View)→tuple[int,int]🔗

Returns

The a tuple of the group and index within the group of thegivenView.

set_sheet_index(sheet:Sheet,group:int,index:int)🔗

Move the givenSheet to the givengroup at the givenindex.

set_view_index(view:View,group:int,index:int)🔗

Move the givenView to the givengroup at the givenindex.

move_sheets_to_group(sheets:list[sublime.Sheet],group:int,insertion_idx=-1,select=True)🔗

4123

Moves all provided sheets to specified group at insertion indexprovided. If an index is not provided defaults to last index of thedestination group.

Parameters

sheets

The sheets to move.

group

The index of the group to move the sheets to.

insertion_idx

The point inside the group at which to insert the sheets.

select

Whether the sheets should be selected after moving them.

sheets()→list[sublime.Sheet]🔗

Returns

All open sheets in the window.

views(*,include_transient=False)→list[sublime.View]🔗

Parameters

include_transient

4081

Whether the transient sheet should be included.

Returns

All open sheets in the window.

selected_sheets()→list[sublime.Sheet]🔗

4083

Returns

All selected sheets in the window’s currently selected group.

selected_sheets_in_group(group:int)→list[sublime.Sheet]🔗

4083

Returns

All selected sheets in the specified group.

active_sheet_in_group(group:int)→Optional[Sheet]🔗

Returns

The currently focusedSheet in the given group.

active_view_in_group(group:int)→Optional[View]🔗

Returns

The currently focusedView in the given group.

sheets_in_group(group:int)→list[sublime.Sheet]🔗

Returns

A list of all sheets in the specified group.

views_in_group(group:int)→list[sublime.View]🔗

Returns

A list of all views in the specified group.

num_sheets_in_group(group:int)→int🔗

Returns

The number of sheets in the specified group.

num_views_in_group(group:int)→int🔗

Returns

The number of views in the specified group.

transient_sheet_in_group(group:int)→Optional[Sheet]🔗

Returns

The transient sheet in the specified group.

transient_view_in_group(group:int)→Optional[View]🔗

Returns

The transient view in the specified group.

promote_sheet(sheet:Sheet)🔗

Promote the ‘Sheet’ parameter if semi-transient or transient.

Since

4135

layout()→dict[str,Value]🔗

Get the group layout of the window.

get_layout()🔗

Deprecated

Uselayout() instead

set_layout(layout:dict[str,Value])🔗

Set the group layout of the window.

create_output_panel(name:str,unlisted=False)→View🔗

Find theView associated with the named output panel, creating it ifrequired. The output panel can be shown by running theshow_panelwindow command, with thepanel argument set to the name withan"output." prefix.

Parameters

name

The name of the output panel.

unlisted

Control if the output panel should be listed in the panel switcher.

find_output_panel(name:str)→Optional[View]🔗

Returns

TheView associated with the named output panel, orNone ifthe output panel does not exist.

destroy_output_panel(name:str)🔗

Destroy the named output panel, hiding it if currently open.

create_io_panel(name:str,on_input:Callable[[str],None],unlisted=False)→Tuple[View,View]🔗

Just likecreate_output_panel, find the view(s) associated with thenamed output panel, creating it if required. The output panel willadditionally be configured with an input box. The panel can be shown byrunning theshow_panel window command, with thepanel argumentset to the name with an"output." prefix.

Parameters

name

The name of the output panel.

on_input

Called with any text submitted from the input box.

unlisted

Control if the output panel should be listed in the panel switcher.

Returns

Atuple containing theView for the output and anotherViewfor the input.

find_io_panel(name:str)→Tuple[Optional[View],Optional[View]]🔗

Returns

The outputView associated with the named output panel and if theoutput panel has an input box it also returns itsView; or ``(None, None)`` if the output panel does not exist.

active_panel()→Optional[str]🔗

Returns the name of the currently open panel, or None if no panel isopen. Will return built-in panel names (e.g."console","find",etc) in addition to output panels.

panels()→list[str]🔗

Returns a list of the names of all panels that have not been marked asunlisted. Includes certain built-in panels in addition to outputpanels.

get_output_panel(name:str)🔗

Deprecated

Usecreate_output_panel instead.

show_input_panel(caption:str,initial_text:str,on_done:Optional[Callable[[str],None]],on_change:Optional[Callable[[str],None]],on_cancel:Optional[Callable[[],None]])🔗

Shows the input panel, to collect a line of input from the user.

Parameters

caption

The label to put next to the input widget.

initial_text

The initial text inside the input widget.

on_done

Called with the final input when the user pressesenter.

on_change

Called with the input when it’s changed.

on_cancel

Called when the user cancels input usingesc

Returns

TheView used for the input widget.

show_quick_panel(items:list[str]|list[list[str]]|list[sublime.QuickPanelItem],on_select:Callable[[int],None],flags=QuickPanelFlags.NONE,selected_index=-1,on_highlight:Optional[Callable[[int],None]]=None,placeholder:Optional[str]=None)🔗

Show a quick panel to select an item in a list. on_select will be calledonce, with the index of the selected item. If the quick panel wascancelled, on_select will be called with an argument of -1.

Parameters

items

May be either a list of strings, or a list of lists of strings wherethe first item is the trigger and all subsequent strings aredetails shown below.

May be aQuickPanelItem.

4083

on_select

Called with the selected item’s index when the quick panel iscompleted. If the panel was cancelled this is called with-1.

A secondEvent argument may be passed when theQuickPanelFlags.WANT_EVENT flag is present.

4096

flags

QuickPanelFlags controlling behavior.

selected_index

The initially selected item.-1 for no selection.

on_highlight

Called every time the highlighted item in the quick panel is changed.

placeholder

4081

Text displayed in the filter input field before any query is typed.

is_sidebar_visible()→bool🔗

Returns

Whether the sidebar is visible.

set_sidebar_visible(flag:bool,animate=True)🔗

Hides or shows the sidebar.

is_minimap_visible()→bool🔗

Returns

Whether the minimap is visible.

set_minimap_visible(flag:bool)🔗

Hides or shows the minimap.

is_status_bar_visible()→bool🔗

Returns

Whether the status bar is visible.

set_status_bar_visible(flag:bool)🔗

Hides or shows the status bar.

get_tabs_visible()→bool🔗

Returns

Whether the tabs are visible.

set_tabs_visible(flag:bool)🔗

Hides or shows the tabs.

is_menu_visible()→bool🔗

Returns

Whether the menu is visible.

set_menu_visible(flag:bool)🔗

Hides or shows the menu.

folders()→list[str]🔗

Returns

A list of the currently open folders in thisWindow.

project_file_name()→Optional[str]🔗

Returns

The name of the currently opened project file, if any.

workspace_file_name()→Optional[str]🔗

4050

Returns

The name of the currently opened workspace file, if any.

project_data()→Value🔗

Returns

The project data associated with the current window. The datais in the same format as the contents of a.sublime-project file.

set_project_data(data:Value)🔗

Updates the project data associated with the current window. If thewindow is associated with a.sublime-project file, the projectfile will be updated on disk, otherwise the window will store the datainternally.

settings()→Settings🔗

Returns

TheSettings object for thisWindow. Any changes to thissettings object will be specific to this window.

template_settings()→Settings🔗

Returns

Per-window settings that are persisted in the session, andduplicated into new windows.

symbol_locations(sym:str,source=SymbolSource.ANY,type=SymbolType.ANY,kind_id=KindId.AMBIGUOUS,kind_letter='')→list[sublime.SymbolLocation]🔗

4085

Find all locations where the symbolsym is located.

Parameters

sym

The name of the symbol.

source

Sources which should be searched for the symbol.

type

The type of symbol to find

kind_id

TheKindId of the symbol.

kind_letter

The letter representing the kind of the symbol. SeeKind.

Return

the found symbol locations.

lookup_symbol_in_index(symbol:str)→list[sublime.SymbolLocation]🔗

Returns

All locations where the symbol is defined across files in the current project.

Deprecated

Usesymbol_locations() instead.

lookup_symbol_in_open_files(symbol:str)→list[sublime.SymbolLocation]🔗

Returns

All locations where the symbol is defined across open files.

Deprecated

Usesymbol_locations() instead.

lookup_references_in_index(symbol:str)→list[sublime.SymbolLocation]🔗

Returns

All locations where the symbol is referenced across files in the current project.

Deprecated

Usesymbol_locations() instead.

lookup_references_in_open_files(symbol:str)→list[sublime.SymbolLocation]🔗

Returns

All locations where the symbol is referenced across open files.

Deprecated

Usesymbol_locations() instead.

extract_variables()→dict[str,str]🔗

Get thedict of contextual keys of the window.

May contain:*"packages"*"platform"*"file"*"file_path"*"file_name"*"file_base_name"*"file_extension"*"folder"*"project"*"project_path"*"project_name"*"project_base_name"*"project_extension"

Thisdict is suitable for use withexpand_variables().

status_message(msg:str)🔗

Show a message in the status bar.

classsublime.Edit🔗

Bases:object

A grouping of buffer modifications.

Edit objects are passed toTextCommands, and can not be created by theuser. Using an invalid Edit object, or an Edit object from a differentView, will cause the functions that require them to fail.

classsublime.Region🔗

Bases:object

A singular selection region. This region has a order -b may be beforeor ata.

Also commonly used to represent an area of the text buffer, where orderingandxpos are generally ignored.

a:Point🔗

The first end of the region.

b:Point🔗

The second end of the region. In a selection this is the location of thecaret. May be less thana.

xpos:DIP🔗

In a selection this is the target horizontal position of the region.This affects behavior when pressing the up or down keys. Use-1 ifundefined.

__len__()→int🔗

Returns

The size of the region.

__contains__(v:Region|Point)→bool🔗

40233.8

Returns

Whether the providedRegion orPoint is entirely containedwithin this region.

to_tuple()→tuple[Point,Point]🔗

4075

Returns

This region as a tuple(a,b).

empty()→bool🔗

Returns

Whether the region is empty, ie.a==b.

begin()→Point🔗

Returns

The smaller ofa andb.

end()→Point🔗

Returns

The larger ofa andb.

size()→int🔗

Equivalent to__len__.

contains(x:Point)→bool🔗

Equivalent to__contains__.

cover(region:Region)→Region🔗

Returns

ARegion spanning both regions.

intersection(region:Region)→Region🔗

Returns

ARegion covered by both regions.

intersects(region:Region)→bool🔗

Returns

Whether the provided region intersects this region.