Docs

Events

Package Control 3.0 adds an API for package developers to be able to more easily respond to events that affect their packages. The events API is used in concert with the Sublime Text package load/unload handlers.

The following events can be detected:

• After Install
• Before Upgrade
• After Upgrade
• Before Removal

Please note that this API is only available starting with Package Control 3.0. Users who have not upgraded to 3.0 will not have the package_control modules available to all packages and errors will occur. In an effort to solve this issue, the old channel files for Package Control 1.x and 2.0 will only contain Package Control itself as of early January 2015. This will ensure that only Package Control 3.0 users will be installing and upgrading packages, making it possible for package developers to use the new events API and dependencies.

Sublime Text Load/Unload Handlers

The events API is a layer of extra information that allows code being run inside of the Sublime Text 3 plugin_loaded() and plugin_unloaded() handlers. These handlers are automatically executed whenever a package is installed/enabled or removed/disabled, respectively.

Part of what makes these handlers applicable is that Package Control always disables and reenables packages when performing operations on them. This helps ensure that Sublime Text does not parse partially extracted file contents or retain a filesystem lock on files about to be written or removed.

Packages that run on Sublime Text 2 also have slightly different handlers. The example below will include code and comments showing how to support both ST2 and ST3.

API

The events API is located in the package_control.events module. It has four functions. Each of these functions returns either a string version number, or None if the package is not in the state specified.

• events.install("Package Name") - package was just installed
• events.pre_upgrade("Package Name") - package is about to be upgraded
• events.post_upgrade("Package Name") - package was just upgraded
• events.remove("Package Name") - package is about to be removed

Example Code

The following code should be located in one of the .py files in the root of your package.

import sys


package_name = 'My Package'


def plugin_loaded():
    from package_control import events

    if events.install(package_name):
        print('Installed %s!' % events.install(package_name))
    elif events.post_upgrade(package_name):
        print('Upgraded to %s!' % events.post_upgrade(package_name))


def plugin_unloaded():
    from package_control import events

    if events.pre_upgrade(package_name):
        print('Upgrading from %s!' % events.pre_upgrade(package_name))
    elif events.remove(package_name):
        print('Removing %s!' % events.remove(package_name))


# Compat with ST2
if sys.version_info < (3,):
    plugin_loaded()
    unload_handler = plugin_unloaded