Converting existing Language Servers (fortls) to pygls

[gnikit]

I am the author of fortls, which is the only actively maintained Language Server for Fortran. A lot of the maintenance work for the server goes into supporting our own horrible LSP implementation, which uses Python dictionaries. I came across pygls and I think it is a perfect replacement of the ou current solution.

The change from our inhouse LSP implementation to pygls is definitely going to be a nontrivial task. From studying the available pygls examples I think I can identify similarities between the two implementations but I don't necessarily see how the current implementation could be converted to pygls callbacks. I was therefore wondering if you had any recommendations or advice for converting existing projects to pygls?

Issue is being tracked: fortran-lang/fortls#96

---

P.S. fortls will hopefully not continue being the only (or main) Language Server for Fortran, we are slowly working on an alternative using lfortran and a Python wrapper which will use pygls from the start to implement its server.

[tombh]

Hello @gnikit, and welcome. I'm the core maintainer, but I've only just got involved in the last month, so I'm not best placed to answer right now. Hopefully others will chime in too.

I had a quick look at fortls, it's very comprehensive, I can see how migration won't be a trivial task.

So let's see. What do you mean by the callbacks? Can you give a specific example?

[gnikit]

What do you mean by the callbacks? Can you give a specific example?

This was my, not very intuitive, way of saying "fortls using pygls for its LSP functionality".
An example would be converting serve_document_symbols to use pygls. What I think would be removed/altered are

• the explicit numbers in the map_types function, which maps our owen AST types to LSP SymbolKind types
• all the calls to the request Python dict
• the call to symbol_json which forms the jsonrpc2.0 as a Python dict to be returned

To start the conversion to pygls my guess would be that a call to the decorator has to be made

@json_server.feature(DOCUMENT_SYMBOL)
def serve_document_symbols(self, ...):
    ...

What I am not very clear about is:

• how would one query the request to get the info like the URI inside of serve_document_symbols
• with regards to hover, if you decide to use Markdown syntax, correct me if I am wrong but pygls does not offer any accompanying tools for the user to structure the Markdown message. For all intents and purposes pygls will just receive a Python string for that hover message. If that is the case, do you have any advice or know any libraries that would make composing the Markdown syntax easier? (I know of markdown but I am under the impression that it only outputs (X)HTML).

[alcarney]

I could be mistaken, but after glancing at your langserver.py file and in particular the handle method, I don't think fortls is too dissimilar to pygls, though there are more abstractions in pygls to deal with.

• Your handle method serves the same purpose as pygls' _procedure_handler
• pygls uses a FeatureManager to keep track of LSP method implementations, but aside from some extra book keeping it's basically a dict similar to fortls, the @server.feature(...) decorator is ultimately adding the decorated function to this dict.
• Rather than pass dicts around though, pygls uses pydantic to parse incoming requests into structured objects which are then passed into your decorated functions, so in the case of your example above...

  @json_server.feature(DOCUMENT_SYMBOL)
  def serve_document_symbols(ls: LanguageServer, params: DocumentSymbolParams):
      uri = params.text_document.uri
      doc = ls.workspace.get_document(uri)

Perhaps a potential starting point for porting fortls would be to convert your handle method into a setup function for a pygls powered server - something along the lines of

from pygls.server import LanguageServer

server = LanguageServer()
server.feature("initialize")(self.serve_initialize),
server.feature("textDocument/documentSymbol")(self.serve_document_symbols)
server.feature("textDocument/completion")(self.serve_autocomplete)
...
server.start_io()

Hopefully at least some of that made sense and/or was useful! 😄

---

If that is the case, do you have any advice or know any libraries that would make composing the Markdown syntax easier?

Unfortunately I don't :/

[gnikit]

Thanks @alcarney for the great feedback and help, it is extremely valuable and ultimately what I was looking for. I think at least the basic blocks for starting the port to pygls, so over the next few weeks I will make a start.

PS your esbonio server is great and it has been a much needed improvement in VS Code!