Authoring Python Extensions

Note: If you are new to VS Code extension authoring, you may want to read theYour First Extension tutorial first and try creating a simple Hello World extension.

ThePython extension provides APIs for other extensions to work with Python environments available on the user's machine. Check out@vscode/python-extension npm module that includes types and helper utilities to access these APIs from your extension.

Python extension template

ThePython extension template helps get you started building a Visual Studio Code extension for your favorite Python tool. It could be a linter, formatter, or code analysis, or all of those together. The template will give you the basic building blocks you need to build an extension that integrates your tool into VS Code, and it already has access to the Python APIs mentioned above.

Programming languages and frameworks

The extension template has two parts, the extension part and language server part. The extension part is written in TypeScript, and language server part is written in Python over thepygls (Python language server) library.

You will mostly be working on the Python part of the code when using this template. You will be integrating your tool with the extension part using theLanguage Server Protocol.pygls currently works on theversion 3.16 of LSP.

The TypeScript part handles working with VS Code and its UI. The extension template comes with a few settings built-in that can be used by your tool. If you need to add new settings to support your tool, you will have to work with a bit of TypeScript. The extension template has examples for a few settings and you can also look atextensions developed by our team for some of the popular tools.

Requirements

1. VS Code 1.64.0 or greater
2. Python 3.7 or greater
3. node >= 14.19.0
4. npm >= 8.3.0 (npm is installed with node, check npm version, usenpm install -g npm@8.3.0 to update)
5. Python extension for VS Code

You should know how to create and work with Python virtual environments.

Getting started

To get started, follow the instructions in the templateREADME. There you will learn how to use thetemplate to create your repository and how to install the necessary tools (for example, thenox task runner) and optional dependencies (testing support).

TheREADME has the most up-to-date instructions and also goes into details on how to customize the extension'spackage.json placeholders (<pythontool-module>,<pythontool-display-name>, etc.).

Features of the template

After creating your extension via the template, it will include the following extension contributions. Assume<pytool-module> was replaced withmytool, and<pytool-display-name> withMy Tool:

1. A commandMy Tool: Restart Server (command ID:mytool.restart).
2. Following settings:
   • mytool.logLevel
   • mytool.args
   • mytool.path
   • mytool.importStrategy
   • mytool.interpreter
   • mytool.showNotification
3. Following triggers for extension activation:
   • On Languagepython.
   • On File with.py extension found in the opened workspace.
   • On Commandmytool.restart.
4. Output channel for loggingOutput >My Tool.

Integrating your tool

The generatedbundled/tool/server.py file is where you will make most of your changes.TODO comments in the file point out the various customization points. Also search forTODO comments in other locations in the template, such as other Python and Markdown files. You will want to review the LICENSE file, even if you want to keep it MIT License.

Examples

There are several example implementations created from the template:

• Pylint - implements linting and Code Actions on fileopen,save, andclose.
• Flake8 - implements linting and Code Actions.
• Black Formatter - integrates theBlack formatter.
• autopep8 - integrates theautopep8 formatter.
• isort - adds Code Actions to sort imports.

You can also review theLanguage Server Protocol specification to better understand thepygls language server integration.

Extension development

The template README goes into detail on thedevelopment cycle support included with the template. The template has commands and configurations so you can build, run, debug, and test your extension.

If you run into problems during development, there is aTroubleshooting section to help with common issues.

Packaging and publishing

Before publishing your extension, you'll need to update the extensionpackage.json fields (such aspublisher andlicense) for your specific extension. You also want to update the auxiliary Markdown files (CODE_OF_CONDUCT.md,CHANGELOG.md, etc.).

Once your extension is ready to publish, there is anoxbuild-package task to create a.vsix file, which you can then upload to your extensionmanagement page.

If you are new to creating and publishing VS Code extensions, we recommend you follow best practices outlined in the main VS Codeextension authoring topics. Here you'll find guidance to help make your extension look great on the Marketplace and how to become a verified publisher so that the users feel confident installing your extension.