Plugins

See also

API Reference
More information on the Python API.

Plugins are Python scripts implementing *Command classes from sublime_plugin.

Where to Store Plugins

Sublime Text will look for plugins in these places:

  • Packages
  • Packages/<pkg_name>
  • .sublime-package files

Plugin files nested deeper in Packages won’t be loaded.

All plugins should live inside a folder of their own and not directly under Packages. This will spare you confusions when Sublime Text attempts to sort packages for loading.

Conventions for Command Names

By convention, Sublime Text command class names are suffixed with Command and written as NamesLikeThisCommand.

However, command names are automatically transformed from NamesLikeThisCommand to name_like_this. Thus, ExampleCommand would become example, and AnotherExampleCommand would become another_example.

In names for classes defining commands, use NameLikeThisCommand. To call a command from the API, use the standardized name_like_this.

Types of Commands

  • sublime_plugin.WindowCommand
  • sublime_plugin.TextCommand
  • sublime_plugin.EventListener

Instances of WindowCommand have a .window attribute pointing to the window instance that created them. Similarly, instances of TextCommand have a .view attribute.

Shared Traits for Commands

All commands must implement a .run() method.

All commands can receive an arbitrarily long number of keyword arguments that must be valid JSON types.

How to Call Commands from the API

Depending on the type of command, use a reference to a View or a Window and call <object>.run_command('command_name'). In addition to the command’s name, .run_command accepts a dictionary whose keys are the names of valid parameters for said command:

window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."})

Command Arguments

All user-provided arguments to commands must be valid JSON types.

Text Commands and the edit Object

Text commands receive an edit object passed to them by Sublime Text.

All actions done within an edit are grouped as a single undo action. Callbacks such as on_modified() and on_selection_modified() are called when the edit is finished.

Contrary to earlier versions of Sublime Text, the edit object’s life time is now managed solely by the editor. Plugin authors must ensure to perform all editing operations within the run() method of text commands so that macros and repeating commands work as expected.

To call other commands from your own commands, use the run_command() function.

Responding to Events

Any subclass of EventListener will be able to respond to events. You cannot make a class derive both from EventListener and from any other type of command.

A Word of Warning about EventListener

Expensive operations in event listeners can cause Sublime Text to become unresponsive, especially in events triggered frequently, like on_modified() and on_selection_modified(). Be careful of how much work is done in these and don’t implement events you don’t need, even if they just pass.

Sublime Text and the Python Standard Library

Sublime Text ships with a trimmed down standard library.

Automatic Plugin Reload

Sublime Text will reload topmost Python modules as they change (perhaps because you are editing a .py file within Packages). By contrast, Python subpackages won’t be reloaded automatically, and this can lead to confusion while you’re developing plugins. Generally speaking, it’s best to restart Sublime Text after you’ve made changes to plugin files, so all changes can take effect.

Multithreading

Only the set_timeout() function is safe to call from different threads.