Package Control

https://github.com/sublimehq/package_control
Admin
Package Control is a package manager for Sublime Text that allows users to find, install, and keep...
Tokens:117,877
Snippets:991
Trust Score:6.8
License:MIT
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install Package Example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Example usage of the install_package method, demonstrating how to handle success, deferred installation, and failure states.

```python
manager = PackageManager()
result = manager.install_package('Emmet', unattended=True)
if result is True:
    print('installed')
elif result is None:
    print('deferred until next restart')
else:
    print('failed')
```

--------------------------------

### Startup hook example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_cleanup.md

Demonstrates how to start the cleanup thread shortly after Sublime Text starts using plugin_loaded.

```python
import sublime
from package_control.package_cleanup import PackageCleanup

def plugin_loaded():
    # start shortly after Sublime starts so package renames don't cause
    # errors with key bindings, settings, etc. disappearing mid-parse
    sublime.set_timeout(PackageCleanup().start, 2000)
```

--------------------------------

### Cache set and get example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/support_modules.md

Demonstrates storing data in the cache with a specific time-to-live and retrieving it.

```python
from package_control.cache import get_cache, set_cache
set_cache('my_key', [1, 2, 3], ttl=60)
print(get_cache('my_key'))
```

--------------------------------

### Usage example with error handling

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_io.md

Demonstrates checking for a file's existence, reading it as binary, and retrieving the installed package path with error handling.

```python
from package_control.package_io import (
    get_installed_package_path,
    package_file_exists,
    read_package_file,
)

if package_file_exists('Emmet', 'package-metadata.json'):
    data = read_package_file('Emmet', 'package-metadata.json', binary=True)
    if data is False:
        print('read failed (corrupt package or invalid filename)')
    else:
        print('read {} bytes'.format(len(data)))

print(get_installed_package_path('Emmet'))
```

--------------------------------

### events module consumer example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/support_modules.md

Demonstrates how a plugin can check for installation events using the events module.

```python
# typical consumer (in another package's plugin.py)
import package_control.events

def plugin_loaded():
    version = events.install('My Package')
    if version:
        print('installed', version)
```

--------------------------------

### DistInfoDir INSTALLER methods

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Methods for reading and writing the INSTALLER file.

```python
def read_installer(self):
def write_installer(self):
```

--------------------------------

### check_version usage examples

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/pep440.md

Examples demonstrating version comparison against specifiers, including handling of pre-release versions.

```python
from package_control.pep440 import check_version

assert check_version('>=3000', '4050') == True
assert check_version('<4000', '4050') == False
assert check_version('>=4107', '1.0.0b1', include_prereleases=True) == True
```

--------------------------------

### install_packages Method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Installs the specified packages. It creates tasks with INSTALL and OVERWRITE actions and returns None.

```python
def install_packages(self, packages, unattended=False, progress=None):
```

--------------------------------

### install_libraries(libraries, fail_early=True)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Installs a list of libraries. Returns True if all libraries are installed successfully, False otherwise. If fail_early is True, aborts on the first failure.

```APIDOC
## install_libraries(libraries, fail_early=True)

### Description
Installs a list of libraries. Returns True if all libraries are installed successfully, False otherwise. If fail_early is True, aborts on the first failure.

### Method
install_libraries

### Parameters
- **libraries** (list of library.Library) - Required - List of libraries to install.
- **fail_early** (bool) - Optional - If True, abort on the first failure. Default is True.

### Returns
- **bool** - True if all libraries are installed, False otherwise.
```

--------------------------------

### PackageTaskRunner usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Demonstrates how to use PackageTaskRunner to install packages with an activity indicator.

```python
from package_control.package_tasks import PackageTaskRunner
from package_control.activity_indicator import ActivityIndicator

runner = PackageTaskRunner()
with ActivityIndicator('Installing...') as progress:
    runner.install_packages(['Emmet', 'LSP'], unattended=True, progress=progress)
```

--------------------------------

### Initialize and query PackageRegistry

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_registry.md

Example of initializing the registry with channels and retrieving package information.

```python
from package_control.package_registry import PackageRegistry

registry = PackageRegistry({
    'channels': ['https://packagecontrol.io/channel_v3.json'],
    'repositories': [],
    'timeout': 30,
    'install_prereleases': ['some-beta-package'],
})
package = registry.get_package('Emmet')
if package:
    latest = package['releases'][0]
    print(package['name'], latest['version'], latest['url'])
else:
    print('Emmet not in registry (or in unavailable_packages):',
          'Emmet' in registry.unavailable_packages)
```

--------------------------------

### JSONApiClient usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/clients.md

Example of initializing the client and fetching JSON data from the GitHub API.

```python
from package_control.clients.json_api_client import JSONApiClient

client = JSONApiClient({'timeout': 30})
data = client.fetch_json('https://api.github.com/repos/wbond/package_control')
print('name:', data['name'])
```

--------------------------------

### GitUpgrader Usage Example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/upgraders.md

Example demonstrating how to instantiate GitUpgrader and use its incoming and run methods to update a package.

```APIDOC
## GitUpgrader Usage Example

### Description
Shows how to create a GitUpgrader instance and check for and apply updates.

### Example
```python
from package_control.upgraders.git_upgrader import GitUpgrader

upgrader = GitUpgrader(
    vcs_binary_paths=['/usr/bin/git'],
    update_command=['pull', '--ff-only', '--quiet'],
    working_copy='/path/to/Packages/MyPackage',
    cache_length=600,
    debug=False,
)
if upgrader.incoming():
    print('updating repo...')
    result = upgrader.run()
    print('updated' if result else 'update failed')
else:
    print('no incoming changes')
```
```

--------------------------------

### UrlLibDownloader usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/downloaders.md

Example of manually selecting and using the UrlLibDownloader backend with error handling.

```python
from package_control.downloaders.urllib_downloader import UrlLibDownloader
from package_control.downloaders.downloader_exception import DownloaderException

downloader = UrlLibDownloader({'timeout': 30, 'user_agent': 'my-tool'})
try:
    content = downloader.download('https://example.com/file.txt', 'Could not get file', 30, 3)
except DownloaderException as e:
    print('failed:', e)
finally:
    downloader.close()
```

--------------------------------

### PackageVersion usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_version.md

Demonstrates initializing PackageVersion with various string formats and handling invalid inputs.

```python
from package_control.package_version import PackageVersion

print(PackageVersion('2020.07.15.10.50.38'))          # keeps original str
print(PackageVersion('2020.07.15') < PackageVersion('1.0.0'))  # True
print(PackageVersion('1.0.0').version_string())       # normalized

try:
    PackageVersion(123)
except TypeError as e:
    print(e)

try:
    PackageVersion('not.a.version')
except ValueError:
    print('invalid')
```

--------------------------------

### Load list setting example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/support_modules.md

Demonstrates how to load a list-based setting from the Package Control settings file.

```python
from package_control.settings import load_list_setting, pc_settings_filename
import sublime
settings = sublime.load_settings(pc_settings_filename())
print(load_list_setting(settings, 'installed_packages'))
```

--------------------------------

### Invoke install_packages command

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Example of invoking the install_packages command with a list of packages.

```py
sublime.run_command("install_packages", {"packages": ["Package 1", "Package 2"], "unattended": False})
```

--------------------------------

### run_install_tasks(tasks, progress=None, unattended=False, package_kind='')

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Executes a list of PackageInstallTask tasks. Disables all task packages (INSTALL action), runs manager.install_package per task, installs and cleans up libraries, re-enables packages (excluding deferred ones). Returns None.

```APIDOC
## run_install_tasks(tasks, progress=None, unattended=False, package_kind='')

### Description
Executes a list of PackageInstallTask tasks. Disables all task packages (INSTALL action), runs manager.install_package per task, installs and cleans up libraries, re-enables packages (excluding deferred ones). Returns None.

### Method
Function call

### Signature
```python
def run_install_tasks(self, tasks, progress=None, unattended=False, package_kind=''):
```

### Parameters
- **tasks** (list of PackageInstallTask) - Required - Tasks to execute
- **progress** (ActivityIndicator or None) - Optional - Status indicator
- **unattended** (bool) - Optional - Suppress dialogs
- **package_kind** (str) - Optional - Message adjective (e.g. missing)

### Returns
None
```

--------------------------------

### PackageTaskRunner.install_packages

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Installs the specified packages. Creates tasks with actions (INSTALL, OVERWRITE). Returns None in all paths, but emits messages: if no packages are available upstream, a 'no packages available' message is shown; if every requested package is already installed, 'All specified packages already installed!' is shown; otherwise runs the tasks via run_install_tasks.

```APIDOC
## PackageTaskRunner.install_packages

### Description
Installs the specified packages. Creates tasks with actions (INSTALL, OVERWRITE). Returns None in all paths, but emits messages: if no packages are available upstream, a 'no packages available' message is shown; if every requested package is already installed, 'All specified packages already installed!' is shown; otherwise runs the tasks via run_install_tasks.

### Method
install_packages

### Signature
```python
def install_packages(self, packages, unattended=False, progress=None):
```

### Parameters
- **packages** (str | list | tuple | set or None) - Required - Names to install (any other type raises TypeError)
- **unattended** (bool) - Optional - Suppress dialogs / message focus
- **progress** (ActivityIndicator or None) - Optional - Status indicator

### Returns
None

```

--------------------------------

### Create a compatible library manifest

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Shows the process of creating a new .dist-info directory, writing metadata, installer information, wheel configuration, and recording files.

```python
did = distinfo.DistInfoDir('/tmp/pkg', 'mylib-1.0.0.dist-info')
did.ensure_exists()
did.write_metadata('mylib', '1.0.0', 'A library', 'https://example.com')
did.write_installer()
did.write_wheel('3.8', False)
did.write_record(['mylib'], ['mylib.py'])
did.add_installer_to_record()
```

--------------------------------

### install_library(lib)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Installs, upgrades, or verifies a single library. Returns True if the library is installed, upgraded, or up-to-date; False on failure. Downloads the release zip, verifies optional sha256, rejects path-traversal archives, verifies .dist-info records, and installs into the version-specific Lib/pythonXX path.

```APIDOC
## install_library(lib)

### Description
Installs, upgrades, or verifies a single library. Returns True if the library is installed, upgraded, or up-to-date; False on failure. Downloads the release zip, verifies optional sha256, rejects path-traversal archives, verifies .dist-info records, and installs into the version-specific Lib/pythonXX path.

### Method
install_library

### Parameters
- **lib** (library.Library) - Required - The library to install.

### Returns
- **bool** - True if installed/upgraded/up-to-date, False on failure.
```

--------------------------------

### Upgrade Packages Example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Demonstrates how to initialize the runner and perform an unattended upgrade for specific packages while ignoring others.

```python
from package_control.package_tasks import PackageTaskRunner
runner = PackageTaskRunner()
completed = runner.upgrade_packages(
    packages=['Emmet'],
    ignore_packages=['LSP'],
    unattended=True,
)
print('restart required' if not completed else 'upgraded')
```

--------------------------------

### DistInfoDir.write_installer

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Writes the INSTALLER file.

```APIDOC
## DistInfoDir.write_installer

### Description
Writes the INSTALLER file.

### Returns
- **None**
```

--------------------------------

### install_package(package_name, unattended=False)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Downloads and installs (or upgrades) a package. Returns True on success, False on failure, or None if the operation is deferred to the next restart. Handles VCS packages, unpacked installations, plugin host selection, and hidden packages.

```APIDOC
## install_package(package_name, unattended=False)

### Description
Downloads and installs (or upgrades) a package. Returns True on success, False on failure, or None if the operation is deferred to the next restart. Handles VCS packages, unpacked installations, plugin host selection, and hidden packages.

### Method
install_package

### Parameters
- **package_name** (str) - Required - Package to download and install.
- **unattended** (bool) - Optional - Suppress message dialogs; don't focus "Package Control Messages". Default is False.

### Returns
- **bool** - True on success, False on failure.
- **None** - If the operation is deferred to the next restart (a package-control.reinstall cookie file is created and the package should not be re-enabled by callers).

### Special Behaviors
- VCS packages are upgraded through their upgrader when ignore_vcs_packages does not block them.
- A Default package or an archive containing .no-sublime-package is installed unpacked into Packages/{name}/.
- A .python-version file inside the archive selects the plugin host; otherwise upstream python_versions are matched.
- Hidden packages (.hidden-sublime-package) are never overwritten (returns False).
- sha256 mismatch, zip errors, and failed downloads return False.

### Example
```python
manager = PackageManager()
result = manager.install_package('Emmet', unattended=True)
if result is True:
    print('installed')
elif result is None:
    print('deferred until next restart')
else:
    print('failed')
```
```

--------------------------------

### list_unmanaged()

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/library.md

Returns a set of InstalledLibrary objects whose INSTALLER file does not start with 'Package Control'.

```APIDOC
## list_unmanaged()

### Description
Returns a set of InstalledLibrary objects whose INSTALLER file does not start with 'Package Control'.

### Returns
- **set[InstalledLibrary]** - The set of unmanaged installed libraries.
```

--------------------------------

### GitHubClient usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/clients.md

Example usage of GitHubClient to fetch repository info and download info. Catches DownloaderException for error handling. Requires a timeout setting in the client constructor.

```python
from package_control.clients.github_client import GitHubClient
from package_control.downloaders.downloader_exception import DownloaderException

client = GitHubClient({'timeout': 30})
try:
    info = client.repo_info('https://github.com/wbond/package_control')
    downloads = client.download_info('https://github.com/wbond/package_control')
    print(info['name'], downloads[0]['version'])
except DownloaderException as e:
    print('error:', e)
```

--------------------------------

### install(dist_info, new_install_root)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/library.md

Moves every top-level path recorded in dist_info into new_install_root, creating parent directories and replacing existing directories.

```APIDOC
## install(dist_info, new_install_root)

### Description
Moves every top-level path recorded in dist_info into new_install_root, creating parent directories and replacing existing directories.

### Parameters
- **dist_info** (distinfo.DistInfoDir) - Required - The source library.
- **new_install_root** (str) - Required - The destination lib root.

### Raises
- **OSError** - On permission errors.
```

--------------------------------

### AddRepository command usage

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Example of using sublime.run_command to add a repository via a URL.

```py
sublime.run_command("add_repository", {"url": "https://my-server.com/repository.json"})
```

--------------------------------

### PEP440Version usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/pep440.md

Demonstrates parsing a version string, checking properties, comparing versions, and handling invalid version input.

```python
from package_control.pep440 import PEP440Version, PEP440InvalidVersionError

v = PEP440Version('1.0.0-rc1')
print(v.is_prerelease)          # True
print(v.major, v.minor, v.micro)  # 1 0 0
print(PEP440Version('1.0') < PEP440Version('1.0.1'))  # True

try:
    PEP440Version('not a version')
except PEP440InvalidVersionError:
    print('invalid')
```

--------------------------------

### get_metadata usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Demonstrates how to instantiate the PackageManager and retrieve metadata for a specific package like 'Emmet'.

```python
from package_control.package_manager import PackageManager
manager = PackageManager()
metadata = manager.get_metadata('Emmet')
if metadata.get('version'):
    print('Emmet', metadata['version'])
```

--------------------------------

### Error Handling Example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Example of detecting a deferred operation when creating package tasks.

```APIDOC
## Error Handling Example

### Description
Example of detecting a deferred operation when creating package tasks.

### Code
```python
tasks = runner.create_package_tasks(actions=(runner.UPGRADE, runner.PULL))
if tasks is False:
    print('no packages available upstream (connection error?)')
elif not tasks:
    print('all up to date')
else:
    ok = runner.run_upgrade_tasks(tasks, unattended=True)
    if ok is False:
        print('Package Control was upgraded - restart Sublime Text')
```
```

--------------------------------

### GitUpgrader usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/upgraders.md

Shows how to instantiate GitUpgrader with a git binary path, update command, working copy path, cache length, and debug flag. It then checks for incoming changes and runs the update if any are found.

```python
from package_control.upgraders.git_upgrader import GitUpgrader

upgrader = GitUpgrader(
    vcs_binary_paths=['/usr/bin/git'],
    update_command=['pull', '--ff-only', '--quiet'],
    working_copy='/path/to/Packages/MyPackage',
    cache_length=600,
    debug=False,
)
if upgrader.incoming():
    print('updating repo...')
    result = upgrader.run()
    print('updated' if result else 'update failed')
else:
    print('no incoming changes')
```

--------------------------------

### Invoke upgrade_packages command

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Example of invoking the upgrade_packages command.

```py
sublime.run_command("upgrade_packages", {"packages": ["Package 1", "Package 2"]})
```

--------------------------------

### DistInfoDir.generate_installer

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Static method that returns the INSTALLER file content.

```APIDOC
## DistInfoDir.generate_installer

### Description
Static method that returns the INSTALLER file content.

### Returns
- **str** - The string "Package Control\n".
```

--------------------------------

### Accessing sys_path information

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/sys_path.md

Example demonstrating how to import sys_path and retrieve data paths, supported Python versions, and library paths.

```python
from package_control import sys_path
print(sys_path.data_path())
print(sys_path.python_versions())
libs = sys_path.lib_paths()
for pyver, root in libs.items():
    print(pyver, root)
```

--------------------------------

### read_package_file usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_io.md

Demonstrates reading the package-metadata.json file from the Emmet package.

```python
from package_control.package_io import read_package_file
metadata = read_package_file('Emmet', 'package-metadata.json')
if metadata:
    print(metadata)
```

--------------------------------

### Install Package Control manually via Python script

Source: https://github.com/sublimehq/package_control/blob/master/readme.md

Run this script in the Sublime Text console to download and install the Package Control package file.

```py
from urllib.request import urlretrieve; urlretrieve(url="https://download.sublimetext.com/Package%20Control.sublime-package", filename=sublime.installed_packages_path() + '/Package Control.sublime-package')
```

--------------------------------

### Using repo_provider_for to fetch packages

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/providers.md

Example of using the repo_provider_for factory function to fetch and list packages from a repository URL.

```python
from package_control.providers import channel_provider_for, repo_provider_for
provider = repo_provider_for('https://github.com/user/pkg', {'timeout': 30})
if provider:
    provider.fetch()
    print([p['name'] for p in provider.get_packages()])
```

--------------------------------

### DistInfoDir.read_installer

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Reads the INSTALLER file and returns the first line stripped, or an empty string if missing.

```APIDOC
## DistInfoDir.read_installer

### Description
Reads the INSTALLER file and returns the first line stripped, or an empty string if missing.

### Returns
- **str** - First line stripped, or '' when missing.
```

--------------------------------

### satisfy_packages(progress=None, unattended=False)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Syncs installed_packages with the filesystem: installs missing packages (actions INSTALL, OVERWRITE, kind missing) and removes managed orphaned packages (kind orphaned). Success message: "All packages satisfied!".

```APIDOC
## satisfy_packages(progress=None, unattended=False)

### Description
Syncs installed_packages with the filesystem: installs missing packages (actions INSTALL, OVERWRITE, kind missing) and removes managed orphaned packages (kind orphaned). Success message: "All packages satisfied!".

### Method
Function call

### Signature
```python
def satisfy_packages(self, progress=None, unattended=False):
```

### Parameters
- **progress** (ActivityIndicator or None) - Optional - Status indicator
- **unattended** (bool) - Optional - Suppress dialogs

### Returns
None
```

--------------------------------

### Invoke upgrade_all_packages command

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Example of invoking the upgrade_all_packages command.

```py
sublime.run_command("upgrade_all_packages", {"unattended": False})
```

--------------------------------

### install_missing_packages method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_cleanup.md

Installs all installed_packages not present on the filesystem when install_missing is True.

```python
def install_missing_packages(self, found_packages):
```

--------------------------------

### render_quick_panel_items

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Renders a list of quick panel items for the given package installation tasks. Returns a list of sublime.QuickPanelItem objects (ST 4.1+) or fallback lists of strings.

```APIDOC
## render_quick_panel_items

### Description
Renders a list of quick panel items for the given package installation tasks. Returns a list of sublime.QuickPanelItem objects (ST 4.1+) or fallback lists of strings.

### Method
render_quick_panel_items

### Signature
```python
def render_quick_panel_items(self, tasks):
```

### Parameters
- **tasks** (list of PackageInstallTask) - Required - Tasks to render

### Returns
- A list of sublime.QuickPanelItem objects (ST 4.1+; module constant USE_QUICK_PANEL_ITEM = hasattr(sublime, 'QuickPanelItem')) or, as fallback, lists of [name, description, extra] strings.
```

--------------------------------

### Find color scheme packages example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_disabler.md

Demonstrates how to use find_color_scheme_packages to identify which packages contain a specific color scheme file.

```python
from package_control.package_disabler import find_color_scheme_packages
name, owners = find_color_scheme_packages('Mariana.sublime-color-scheme')
print(name, owners)   # e.g. Mariana {'Color Scheme - Default', 'User'}
```

--------------------------------

### install_packages

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Installs one or more packages. If packages is not provided, prompts the user for a comma-separated list. The unattended flag suppresses error dialogs.

```APIDOC
## install_packages

### Description
Installs one or more packages. If `packages` is not provided, prompts the user for a comma-separated list. The `unattended` flag suppresses error dialogs.

### Command
`sublime.run_command("install_packages", {...})`

### Parameters
- **packages** (list[str]) - Optional - Names of packages to install. When missing, prompts for a comma-separated list.
- **unattended** (bool) - Optional - Suppress error dialogs. Default: false.

### Request Example
```py
sublime.run_command("install_packages", {"packages": ["Package 1", "Package 2"], "unattended": False})
```
```

--------------------------------

### version_sort usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_version.md

Demonstrates sorting a list of release dictionaries by version and a secondary date field.

```python
from package_control.package_version import version_sort

releases = [
    {'version': '1.2.0', 'date': '2023-01-01'},
    {'version': '1.10.0', 'date': '2024-01-01'},
    {'version': '1.3.0', 'date': '2023-06-01'},
]
latest_first = version_sort(releases, 'date', reverse=True)
print([r['version'] for r in latest_first])   # ['1.10.0', '1.3.0', '1.2.0']
```

--------------------------------

### ClearPackageCacheCommand execution

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

The run method for ClearPackageCacheCommand and an example of how to invoke it via sublime.run_command.

```python
def run(self, unattended=False):
```

```py
sublime.run_command("clear_package_cache", {"unattended": False})
```

--------------------------------

### list_libraries

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Returns a list of library.Library objects for all installed libraries. Delegates to library.list_all().

```APIDOC
## list_libraries

### Description
Returns a list of `library.Library` objects for all installed libraries (delegates to `library.list_all()`).

### Method
list_libraries

### Signature
```python
def list_libraries(self):
```

### Returns
`list` of `library.Library` objects.
```

--------------------------------

### Asset template structure

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/types.md

Example of an asset template structure passed to download_info_from_releases, supporting glob patterns and platform/version constraints.

```python
[
    (
        "Name-${version}-st${st_build}-*-x??.sublime",   # glob pattern
        {
            "platforms": ["windows-x64"],
            "python_versions": ["3.3", "3.8"],
            "sublime_text": ">=4107"
        }
    )
]
```

--------------------------------

### install_package Method Definition

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Definition for the install_package method used to download and install or upgrade a package.

```python
def install_package(self, package_name, unattended=False):
```

--------------------------------

### DistInfoDir add_installer_to_record method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Appends or updates the INSTALLER entry in the RECORD file.

```python
def add_installer_to_record(self):
```

--------------------------------

### PEP440VersionSpecifier usage example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/pep440.md

Demonstrates creating a specifier and checking if a version satisfies it. Note that complex specifiers like '>=2.2,<3.0' are invalid and must be handled as separate specs.

```python
from package_control.pep440 import PEP440VersionSpecifier, PEP440Version

spec = PEP440VersionSpecifier('>=2.2,<3.0')   # invalid! use separate specs
spec = PEP440VersionSpecifier('>=2.2')
print(spec.contains(PEP440Version('2.5')))     # True

prefix = PEP440VersionSpecifier('==2.*')
print(prefix.contains(PEP440Version('2.9')))   # True
print(prefix.contains(PEP440Version('3.0')))   # False
```

--------------------------------

### install_missing_libraries method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_cleanup.md

Installs every missing required library via manager.install_library and sets updated_libraries to True on success.

```python
def install_missing_libraries(self):
```

--------------------------------

### DisablePackage and EnablePackage command usage

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Examples of using sublime.run_command to disable or enable a single package via quick-panel variants.

```py
sublime.run_command("disable_packages", {"packages": ["Package 1"]})
sublime.run_command("enable_packages", {"packages": ["Package 1"]})
```

--------------------------------

### Example: disable and re-enable packages during upgrade

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_disabler.md

Shows how to disable packages before an upgrade and re-enable them afterward using PackageDisabler. The disabled set is passed to reenable_packages.

```python
from package_control.package_disabler import PackageDisabler

disabled = PackageDisabler.disable_packages({
    PackageDisabler.UPGRADE: {'Emmet', 'LSP'},
})
# ... perform the upgrade ...
PackageDisabler.reenable_packages({PackageDisabler.UPGRADE: disabled})
```

--------------------------------

### PackageTaskRunner Usage Example

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_tasks.md

Example of using PackageTaskRunner to install packages with an activity indicator.

```APIDOC
## PackageTaskRunner Usage Example

### Description
Example of using PackageTaskRunner to install packages with an activity indicator.

### Code
```python
from package_control.package_tasks import PackageTaskRunner
from package_control.activity_indicator import ActivityIndicator

runner = PackageTaskRunner()
with ActivityIndicator('Installing...') as progress:
    runner.install_packages(['Emmet', 'LSP'], unattended=True, progress=progress)
```
```

--------------------------------

### Programmatic settings dictionary for DownloadManager

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/configuration.md

Example of passing a settings dictionary to the http_get function to configure timeout, user agent, authentication, and downloader precedence.

```python
settings = {
    'timeout': 30,
    'user_agent': 'Package Control v%s',
    'http_basic_auth': {'api.github.com': ['user', 'token']},
    'downloader_precedence': {'linux': ['urllib', 'curl']},
}
from package_control.download_manager import http_get
data = http_get('https://packagecontrol.io/channel_v3.json', settings)
```

--------------------------------

### GitHubClient.download_info(url, tag_prefix=None)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/clients.md

Combined entry point that first attempts to get download info from the branch, falling back to tags. Returns None if no match, False if no commits, or a list of download-info dicts.

```APIDOC
## GitHubClient.download_info(url, tag_prefix=None)

### Description
Combined entry point for retrieving download information. It first tries to get download info from the branch, and if that fails, falls back to tags. Returns None if no match, False if no commits, or a list of download-info dicts.

### Method
Instance method

### Signature
```python
def download_info(self, url, tag_prefix=None):
```

### Parameters
- **url** (str) - Required - The repository URL.
- **tag_prefix** (str) - Optional - Only consider tags with this prefix.

### Returns
- None - No match.
- False - No commits.
- list - List of download-info dicts with keys: 'version', 'url', 'date'.

### Example
```python
client = GitHubClient({'timeout': 30})
downloads = client.download_info('https://github.com/wbond/package_control')
```
```

--------------------------------

### Perform an HTTP GET request

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/download_manager.md

Example usage of the http_get function to fetch content from a URL with a specified timeout, including error handling for DownloaderException.

```python
from package_control.download_manager import http_get
from package_control.downloaders.downloader_exception import DownloaderException

try:
    content = http_get('https://packagecontrol.io/channel_v3.json', {'timeout': 30})
    print(len(content))
except DownloaderException as e:
    print('download failed:', e)
```

--------------------------------

### InstalledLibrary.is_managed()

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/library.md

Method to check if the installed library is managed by Package Control. Returns True if the INSTALLER content equals the generated installer string.

```APIDOC
## InstalledLibrary.is_managed()

### Description
Checks if the installed library is managed by Package Control.

### Method
is_managed

### Returns
- **bool** - True if INSTALLER content equals dist_info.generate_installer().strip() (i.e. installed by Package Control).
```

--------------------------------

### InstalledLibrary.__init__(install_root, dist_info_dir, python_version)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/library.md

Constructor for the InstalledLibrary class. Initializes an InstalledLibrary instance by reading metadata from a dist-info directory. Raises FileNotFoundError or KeyError if the dist-info directory is invalid.

```APIDOC
## InstalledLibrary.__init__(install_root, dist_info_dir, python_version)

### Description
Initializes an InstalledLibrary instance by reading metadata from a dist-info directory.

### Method
Constructor

### Parameters
- **install_root** (str) - Required - Absolute path of the library install root
- **dist_info_dir** (str) - Required - e.g. pyyaml-5.1.1.dist-info
- **python_version** (str) - Required - Python version string

### Raises
- FileNotFoundError or KeyError if read_metadata() fails (invalid dist-info dir)
```

--------------------------------

### remove_library(lib)

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Removes an installed library. Returns False if the library is not installed (DistInfoNotFoundError) or if removal hits an OSError.

```APIDOC
## remove_library(lib)

### Description
Removes an installed library. Returns False if the library is not installed (DistInfoNotFoundError) or if removal hits an OSError.

### Method
remove_library

### Parameters
- **lib** (InstalledLibrary) - Required - The library to remove.

### Returns
- **bool** - True on success, False when the library is not installed or removal hit an OSError.
```

--------------------------------

### download_info method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/clients.md

Combined entry point for download information. First attempts branch download info, falling back to tags. Returns None (no match), False (no commits), or a list of download-info dicts with keys 'version', 'url', and 'date'.

```python
def download_info(self, url, tag_prefix=None):
```

--------------------------------

### installed_packages_path()

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/sys_path.md

Returns the Installed Packages directory.

```APIDOC
## installed_packages_path()

### Description
Returns the `{Data}/Installed Packages` directory.

### Returns
- **string** - The installed packages directory path.
```

--------------------------------

### PEP440Version.__init__

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/pep440.md

Initializes a PEP440Version instance from a version string. Raises PEP440InvalidVersionError if the string does not match the version grammar.

```APIDOC
## PEP440Version.__init__

### Description
Initializes a PEP440Version instance from a version string. Raises PEP440InvalidVersionError if the string does not match the version grammar.

### Method
Constructor

### Parameters
- **string** (str) - Required - PEP 440 version string, e.g. "1.2.3", "1.0rc1", "2!1.0", "1.0+abc.5"

### Raises
- **PEP440InvalidVersionError** (ValueError) - If the string does not match the version grammar.

### Example
```python
from package_control.pep440 import PEP440Version, PEP440InvalidVersionError

v = PEP440Version('1.0.0-rc1')
print(v.is_prerelease)          # True
print(v.major, v.minor, v.micro)  # 1 0 0
print(PEP440Version('1.0') < PEP440Version('1.0.1'))  # True

try:
    PEP440Version('not a version')
except PEP440InvalidVersionError:
    print('invalid')
```
```

--------------------------------

### Invoke remove_packages command

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Example of invoking the remove_packages command.

```py
sublime.run_command("remove_packages", {"packages": ["Package 1", "Package 2"]})
```

--------------------------------

### upgrade_all_packages

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Upgrades all installed packages. Accepts an optional unattended flag.

```APIDOC
## upgrade_all_packages

### Description
Upgrades all installed packages. Accepts an optional `unattended` flag.

### Command
`sublime.run_command("upgrade_all_packages", {...})`

### Parameters
- **unattended** (bool) - Optional - Suppress error dialogs. Default: false.

### Request Example
```py
sublime.run_command("upgrade_all_packages", {"unattended": False})
```
```

--------------------------------

### install_package / upgrade_package / remove_package / revert_package

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Interactive quick-panel commands that prompt the user to select packages. They take no arguments.

```APIDOC
## install_package / upgrade_package / remove_package / revert_package

### Description
Interactive quick-panel commands that prompt the user to select packages. They take no arguments.

### Commands
- `install_package` - Prompts among available packages (INSTALL/OVERWRITE tasks).
- `upgrade_package` - Prompts among upgradable packages (PULL/UPGRADE tasks).
- `remove_package` - Prompts among installed packages; action "remove".
- `revert_package` - Prompts among installed packages; action "revert to".

### Usage
```py
sublime.run_command("install_package")
sublime.run_command("upgrade_package")
sublime.run_command("remove_package")
sublime.run_command("revert_package")
```
```

--------------------------------

### get_metadata

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Returns the parsed content of the installed package's package-metadata.json file.

```APIDOC
## get_metadata

### Description
Returns the parsed content of the installed package's `package-metadata.json`.

### Method
Python method

### Signature
`def get_metadata(self, package_name)`

### Parameters
- `package_name` (str) - Required - Name of the installed package

### Returns
`dict` with keys `version`, `url`, `description` (and any other keys stored when the package was installed), or an empty `dict` on parse error / missing file.

### Example
```python
from package_control.package_manager import PackageManager
manager = PackageManager()
metadata = manager.get_metadata('Emmet')
if metadata.get('version'):
    print('Emmet', metadata['version'])
```
```

--------------------------------

### DistInfoDir.add_installer_to_record

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

Appends or dedupes the INSTALLER line to the RECORD file, keeping it sorted.

```APIDOC
## DistInfoDir.add_installer_to_record

### Description
Appends or dedupes the `{dir}/INSTALLER,sha256=Hg_Q6w_I4zpFfb6C24LQdd4oTAMHJZDk9gtuV2yOgkw,16` line to the RECORD file, keeping the file sorted.

### Returns
- **None**
```

--------------------------------

### list_all()

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/library.md

Returns a set of InstalledLibrary objects for every *.dist-info directory containing a RECORD file in every sys_path.lib_paths() root.

```APIDOC
## list_all()

### Description
Returns a set of InstalledLibrary objects for every *.dist-info directory containing a RECORD file in every sys_path.lib_paths() root.

### Returns
- **set[InstalledLibrary]** - The set of installed libraries.
```

--------------------------------

### DownloadManager.__init__

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/download_manager.md

Initializes a DownloadManager instance with settings and an optional shared disk cache.

```APIDOC
## DownloadManager.__init__

### Description
Initializes a DownloadManager instance. Copies only downloader-relevant keys into a private settings dict, substitutes `__version__` into `user_agent` when it contains `%s`, and sets cache settings when an http_cache is provided.

### Constructor Signature
```python
def __init__(self, settings, http_cache=None):
```

### Parameters
- **settings** (dict) - Required - Settings dict (see `http_get`).
- **http_cache** (HttpCache/None) - Optional - Shared disk cache object. Defaults to None.

### Behavior
- Copies only downloader-relevant keys into a private `self.settings`.
- Substitutes `__version__` into `user_agent` when it contains `%s`.
- When `http_cache` is given, sets `settings['cache']` and a `max_age` (bounded by `cache_length` between 0 and 86400).
```

--------------------------------

### PackageVersion.__init__

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_version.md

Initializes a PackageVersion object from a version string. It handles date-based versions, v-prefixed strings, and SemVer-style pre-release compatibility.

```APIDOC
## PackageVersion.__init__

### Description
Initializes a PackageVersion object from a version string. It handles date-based versions, v-prefixed strings, and SemVer-style pre-release compatibility.

### Method
Constructor

### Signature
```python
PackageVersion(ver)
```

### Parameters
- **ver** (str) - Required - A version string

### Behavior
1. Raises TypeError if ver is not a str.
2. The original string is stored (with a leading v trimmed) so str() preserves the pre-normalization form.
3. Date-based versions (YYYY.MM.DD[.hh.mm.ss]) are rewritten to 0.0.1+YYYY.MM.DD.hh.mm.ss so any explicit tagged version sorts above them.
4. If the PEP 440 parse fails and the string contains -, it is reinterpreted as a SemVer pre-release: {ver}-dev+{pre}.

### Raises
- **TypeError** - ver is not a string
- **ValueError** (via PEP440InvalidVersionError) - invalid version string that also can't be treated as a SemVer pre-release

### Example
```python
from package_control.package_version import PackageVersion

print(PackageVersion('2020.07.15.10.50.38'))          # keeps original str
print(PackageVersion('2020.07.15') < PackageVersion('1.0.0'))  # True
print(PackageVersion('1.0.0').version_string())       # normalized

try:
    PackageVersion(123)
except TypeError as e:
    print(e)

try:
    PackageVersion('not.a.version')
except ValueError:
    print('invalid')
```
```

--------------------------------

### VcsUpgrader.__init__

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/upgraders.md

Constructor for the VcsUpgrader class, which initializes the upgrader with VCS binary paths, update command, working copy path, cache length, and debug flag.

```APIDOC
## VcsUpgrader.__init__

### Description
Initializes a VcsUpgrader instance with the given parameters.

### Method
Constructor

### Parameters
- **vcs_binary_paths** (str | list[str] | None) - Required - Binary location(s)
- **update_command** (list[str]) - Required - Command args appended to the binary (e.g. ["pull", "--ff-only", "--quiet"])
- **working_copy** (str) - Required - Local path of the package/repository
- **cache_length** (int) - Required - Seconds to cache the "incoming changes" result
- **debug** (bool) - Required - Debug flag

### Example
```python
from package_control.upgraders.vcs_upgrader import VcsUpgrader

upgrader = VcsUpgrader(
    vcs_binary_paths=['/usr/bin/git'],
    update_command=['pull', '--ff-only', '--quiet'],
    working_copy='/path/to/Packages/MyPackage',
    cache_length=600,
    debug=False,
)
```
```

--------------------------------

### Library Management Methods

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Definitions for library management methods including installation, cleanup, and removal.

```python
def install_libraries(self, libraries, fail_early=True):
def install_library(self, lib):
def cleanup_libraries(self, required_libraries=None):
def remove_library(self, lib):
```

--------------------------------

### download_info_from_releases method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/clients.md

Retrieves download info from GitHub releases. Accepts asset templates as a list of (asset-name glob, selectors) tuples. Supports glob syntax with * and ?, and variables ${version}, ${platform}, ${py_version}, ${st_build}. Honors settings['max_releases'] and paginates 100 releases per page. Returns None, False, or a list of dicts with keys url, version, date, platforms, python_versions, sublime_text.

```python
def download_info_from_releases(self, url, asset_templates, tag_prefix=None):
```

--------------------------------

### DistInfoDir class definition

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/distinfo.md

The I/O driver for managing .dist-info directories within a specified install root.

```python
class DistInfoDir:
    __slots__ = ["dir_name", "install_root"]

    def __init__(self, install_root, dist_info_dir):
        self.install_root = install_root
        self.dir_name = dist_info_dir
```

--------------------------------

### InstallPackagesCommand run method

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/commands.md

Defines the run method for the InstallPackagesCommand class.

```python
def run(self, packages=None, unattended=False):
```

--------------------------------

### init_default_settings static method signature

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_disabler.md

Loads the default theme/color-scheme values from Packages/Default/Preferences.sublime-settings into the class dictionaries. No-op if already initialized.

```python
@staticmethod
def init_default_settings():
```

--------------------------------

### select_libraries

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_manager.md

Takes a dict from a dependencies.json file and returns the library names applicable to the current machine. Keys are platform selectors; each value maps version ranges to lists of library names.

```APIDOC
## select_libraries

### Description
Takes a dict from a `dependencies.json` file and returns the library names applicable to the current machine. Keys are platform selectors; each value maps version ranges to lists of library names.

### Method
select_libraries

### Signature
```python
def select_libraries(self, library_info):
```

### Parameters
- `library_info` (dict) - Required - e.g. `{"*": {">=3000": ["lib1"], "<3000": ["lib2"]}}`

### Returns
`list` of library name strings (possibly empty).
```

--------------------------------

### http_get function signature

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/download_manager.md

The signature for the module-level http_get function used to perform HTTP GET requests.

```python
def http_get(url, settings, error_message=''):
```

--------------------------------

### init_default_settings()

Source: https://github.com/sublimehq/package_control/blob/master/_autodocs/api-reference/package_disabler.md

Loads the default theme/color-scheme values from Preferences.sublime-settings into the class dictionaries.

```APIDOC
## init_default_settings()

### Description
Loads the default theme/color-scheme values from `Packages/Default/Preferences.sublime-settings` into the class dictionaries. No-op if already initialized.

### Method
Static method

### Signature
```python
@staticmethod
def init_default_settings():
```
```
Tokens:
Raw