Documentation Plugin Porting Guide
Sublime Text 3 contains some important differences from Sublime Text 2 when it comes to plugins, and most plugins will require at least a small amount porting to work. The changes are:
- Python 3.3
- Out of Process Plugins
- Asynchronous Events
- Zipped Packages
- Importing Modules
Sublime Text 3 uses Python 3.3, while Sublime Text 2 used Python 2.6. Furthermore, on OS X, the system build of Python is no longer used, instead Sublime Text is bundled with its own version. Windows and Linux are also bundled with their own version, as they were previously.
Out of Process Plugins
Plugins are now run in a separate process,
plugin_host. From a plugin authors perspective, there should be no observable difference, except that a crash in the plugin host will no longer bring down the main application.
In Sublime Text 2, only the
set_timeout() method was thread-safe. In Sublime Text 3, every API method is thread-safe. Furthermore, there are now asynchronous event handlers, to make writing non-blocking code easier:
When writing threaded code, keep in mind that the buffer will be changing underneath you as your function runs.
end_edit() are no longer directly accessible, except in some special circumstances. The only way to get a valid instance of an Edit object is to place your code in a TextCommand subclass. In general, most code can be refactored by placing the code between
end_edit() in a TextCommand, and then running the command via
This approach removes the issue of dangling Edit objects, and ensures the repeat command and macros work as they should.
Packages in Sublime Text 3 are able to be run from .sublime-package (i.e., renamed .zip files) files directly, in contrast to Sublime Text 2, which unzipped them prior to running.
While in most changes this should lead to no differences, it is important to keep this in mind if you are accessing files in your package.
Importing other plugins is simpler and more robust in Sublime Text 3, and can be done with a regular import statement, e.g.,
import Default.comment will import Packages/Default/Comment.py.
Restricted API Usage at Startup
Due to the
plugin_host loading asynchronously, it is not possible to use the API at import time. This means that all top-level statements in your module must not call any functions from the sublime module. During startup, the API is in a dormant state, and will silently ignore any requests made.