README.md

cookiecutter-pylsp-plugin

Using cookiecutter-pylsp-plugin is the easiest way to start writing pylsp plugin. This repo also aims to document how python-lsp-plugins plugins are wired if you want to do-it-yourself instead of using the template.

Features

• License selection
• Optionally configure PyTest with some basic fixtures
• Optionally configure publishing to PyPI using Twine
• Optionally configure Github project metadata (e.g. ISSUE_TEMPLATE.md)

Quickstart

Install the latest Cookiecutter if you haven't installed it yet:

pip install -U cookiecutter

Generate a pylsp plugin project:

cookiecutter https://github.com/python-lsp/cookiecutter-pylsp-plugin

Follow the prompts to configure your plugin project.

Install your plugin to the same environment as pylsp so that it can discover your plugin.

cd pylsp-myplugin
pip install --editable '.[dev]'

Don't forget to commit the generated package to your version control, for example with Git:

git init
git add .
git commit -m "Initial commit"

Writing hooks

The most important file in the generated package is plugin.py, this is where you will write pylsp hooks. The pylsp hooks corresponds to Language Server Protocol messages, you should read through the LSP specification. for the hook that you want to use.

A pylsp hook is a function with a specific name, decorated by @hookimpl:

@hookimpl
def pylsp_definitions(config, workspace, document, position):
    ...

Refer to list of hookspecs for the full list of all supported hooks.

Don't confuse @hookimpl with the @hookspec decorator, which is used to define hooks. You'll almost never need to use @hookspec when writing a plugin.

You should also write some tests for your hooks. If you choose to use pytest when generating the template, you should have everything you needed to start writing basic test in the test/test_plugin.py file. The test/fixtures.py contains some useful functions that you'll likely need to test your hooks. Refer to pytest documentation if you are unfamiliar with how to write tests in pytest.

pylsp plugin developer documentation

The following section documents how pylsp plugin is wired to pylsp. You do not need to understand this section if you are creating your plugin from this cookiecutter template, but it may help you if you needed to make changes to the entry_points setup when using this template, or if you want to replicate what this template does in your own project that does not use this template.

On startup, pylsp will automatically discover plugins by querying pkg_resources for entrypoints. So that your plugin can be discovered by pylsp, you must configure the following in the setup.py/setup.cfg of your plugin's package:

[options.entry_points]
pylsp = pylsp_myplugin = pylsp_myplugin.plugin

The entrypoint name can be anything but it's recommended to use the same name as your plugin package's import name.

Next, you need to install your plugin package. During development, usually you'd want to install with something like:

pip install --editable 'path/to/package/'

where path/to/package/ is the folder where your plugin's setup.py/setup.cfg is found.

This installs your plugin as an editable package, which is suitable during development.

pylsp uses pluggy for plugin management. It would be helpful to be familiar and read through pluggy documentation, but we'll go through a quick rundown here.

pylsp plugin is composed of a set of callbacks that are registered using @hookimpl decorator:

from pylsp import hookimpl, uris, _utils

@hookimpl
def pylsp_definitions(config, workspace, document, position):
    logger.info('Retrieving definitions: %s %s %s %s', config, workspace, document, position)
    filename = __file__
    uri = uris.uri_with(document.uri, path=filename)
    with open(filename) as f:
        lines = f.readlines()
        for lineno, line in enumerate(lines):
            if 'def pylsp_definitions' in line:
                break
    return [
        {
            'uri': uri,
            'range': {
                'start': {
                    'line': lineno,
                    'character': 4,
                },
                'end': {
                    'line': lineno,
                    'character': line.find(')') + 1,
                },
            }
        }
    ]

Refer to list of hookspecs for the full list of all supported hooks.

And that's all you need to make a pylsp plugin. Once you have your entrypoint configured and register some @hookimpl, pylsp will call your callbacks to perform its functions.

What comes next, is that you'll want to publish your package in a repository like Github and in PyPI so your package can be easily used and discovered by your users. You can use any way to publish your plugin package, but this cookiecutter will set you up to publish to PyPI using twine.