From 2765e56f518b7717c805de3f1e2ce4c79ae424bf Mon Sep 17 00:00:00 2001 From: Mohammad Zayan Khan Date: Wed, 16 Sep 2026 16:35:53 -0400 Subject: [PATCH 1/2] Document how to actually use the server with an editor The README explains how to install the package and how to develop the server against VS Code, but never how to connect it to an editor as a user. Two people asked for exactly that on #194 and neither got an answer: "Can we add some documentation on enabling it for some IDEs? I assumed that installing the pip package would somehow register it for vscode to catch", and later "there's so little support on actually using it". Adds a section covering that the package installs a pyls executable, that clients launch it over stdin and stdout, that --tcp exists for clients that cannot spawn it, that -v is the first thing to reach for when an editor reports nothing, and which LSP clients people commonly use per editor. Both invocations were checked against a running server. It also records, where someone looking for an extension will actually find it, that there is no official VS Code extension and no plans for one, and that the vscode-client directory is not that extension: it is unpublished, and it exists to develop the server rather than to use it. That question has been asked repeatedly since 2017. Refs #194 Co-Authored-By: Claude Opus 5 (1M context) --- README.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/README.rst b/README.rst index 2dbe128c..a881d909 100644 --- a/README.rst +++ b/README.rst @@ -56,6 +56,52 @@ Installing these plugins will add extra functionality to the language server: Please see the above repositories for examples on how to write plugins for the Python Language Server. Please file an issue if you require assistance writing a plugin. +Using the server with an editor +=============================== + +``pyls`` is a language server, not an editor plugin. It does nothing on its own: an LSP +client running inside your editor starts it and talks to it. Installing the package puts a +``pyls`` executable on your ``PATH``, and clients normally launch that and communicate over +stdin and stdout:: + + pyls + +It can also listen on a socket, which is useful when a client cannot spawn the process +itself, or to attach to a server running elsewhere:: + + pyls --tcp --host 127.0.0.1 --port 2087 + +Run ``pyls --help`` for the full set of options. ``pyls -v`` logs what the server is doing, +which is the first thing to reach for when an editor reports no results. + +Any editor with a generic LSP client can drive the server. Clients commonly used with it: + +* **Vim and Neovim** — ``nvim-lspconfig``, ``coc.nvim``, ``vim-lsp`` or ``ALE`` +* **Emacs** — ``lsp-mode`` or ``eglot`` +* **Sublime Text** — the ``LSP`` package +* **Kate** — the built-in LSP client + +Each client needs to be told to run ``pyls`` for Python files; see that client's own +documentation for where the setting lives. Server settings such as +``pyls.plugins.pydocstyle.enabled`` are sent by the client, so they go in the client's +configuration rather than anywhere in this repository. See Configuration_ below. + +Visual Studio Code +------------------ + +**There is no official extension for this server on the VS Code Marketplace, and there are +no plans to publish one.** The maintainers' answer, in `issue #194`_, is that most +contributors use the server with other editors. + +The ``vscode-client`` directory in this repository is not that extension. It exists to +develop and debug the language server itself: it is unpublished, and it deliberately +launches a separate instance of VS Code because it conflicts with other Python extensions. +If developing the server is what you want, see `Develop against VS Code`_. + +To use this server from a normal VS Code setup you need a third-party extension capable of +launching an arbitrary LSP server, configured to run ``pyls``. Note that VS Code's own +Python extension bundles a different language server, so the two will overlap. + Configuration ------------- @@ -153,6 +199,7 @@ License This project is made available under the MIT License. +.. _issue #194: https://github.com/palantir/python-language-server/issues/194 .. _Language Server Protocol: https://github.com/Microsoft/language-server-protocol .. _Jedi: https://github.com/davidhalter/jedi .. _Rope: https://github.com/python-rope/rope From 128708aa9bbdc3850d00a4bd2ff3cca32bab1588 Mon Sep 17 00:00:00 2001 From: Mohammad Zayan Khan Date: Wed, 16 Sep 2026 16:35:53 -0400 Subject: [PATCH 2/2] Use an RST literal block for the pydocstyle example The example was fenced with markdown backticks inside an .rst file, so docutils reported "Possible title underline, too short for the title" and rendered the snippet as ordinary text. README.rst is the long_description in setup.py, so this affects the PyPI page as well as GitHub. With this the README parses without warnings. Co-Authored-By: Claude Opus 5 (1M context) --- README.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index a881d909..da2a5f65 100644 --- a/README.rst +++ b/README.rst @@ -116,10 +116,9 @@ order to respect flake8 configuration instead. Overall configuration is computed first from user configuration (in home directory), overridden by configuration passed in by the language client, and then overriden by configuration discovered in the workspace. -To enable pydocstyle for linting docstrings add the following setting in your LSP configuration: -``` -"pyls.plugins.pydocstyle.enabled": true -``` +To enable pydocstyle for linting docstrings add the following setting in your LSP configuration:: + + "pyls.plugins.pydocstyle.enabled": true See `vscode-client/package.json`_ for the full set of supported configuration options.