Getting Started

This document explains how to install pygls and get started writing language servers that are based on it.

Note

Before going any further, if you are not familiar with language servers and Language Server Protocol, we recommend reading following articles:

Installation

To get the latest release from PyPI, simply run:

pip install pygls

Alternatively, pygls source code can be downloaded from our GitHub page and installed with following command:

python setup.py install

Quick Start

Spin the Server Up

pygls is a language server that can be started without writing any additional code:

from pygls.server import LanguageServer

server = LanguageServer()

server.start_tcp('localhost', 8080)

After running the code above, server will start listening for incoming Json RPC requests on http://localhost:8080.

Register Features and Commands

pygls comes with an API for registering additional features like code completion, find all references, go to definition, etc.

@server.feature(COMPLETION, trigger_characters=[','])
def completions(params: CompletionParams):
    """Returns completion items."""
    return CompletionList(False, [
        CompletionItem('Item1'),
        CompletionItem('Item2'),
        CompletionItem('Item3'),
    ])

… as well as custom commands:

@server.command('myVerySpecialCommandName')
def cmd_return_hello_world(ls, *args):
    return 'Hello World!'

Features that are currently supported by the LSP specification can be found in pygls.features module, while corresponding request/response classes can be found in pygls.types module.

Advanced usage

To reveal the full potential of pygls (thread management, coroutines, multi-root workspace, TCP/STDIO communication, etc.) keep reading.

Tutorial

We recommend completing the tutorial, especially if you haven’t worked with language servers before.