Installation
#

pylsp install: pip install "python-lsp-server[all]"
3rd party plugins:
- python-lsp-isort: pip install python-lsp-isort
- pylsp-mypy: pip install pylsp-mypy
- pylsp-black: pip install python-lsp-black

I also tried with pylsp-rope, but it works like sh*t, so I won’t waste my time on it.

Neovim lsp configuration
#

Use your favorite plugin manager to install nvim-lspconfig. Here is my configuration for nvim-lsp with the help of nvim-lspconfig.

lspconfig = require("lspconfig")
lspconfig.pylsp.setup {
on_attach = custom_attach,
settings = {
    pylsp = {
    plugins = {
        -- formatter options
        black = { enabled = true },
        autopep8 = { enabled = false },
        yapf = { enabled = false },
        -- linter options
        pylint = { enabled = true, executable = "pylint" },
        pyflakes = { enabled = false },
        pycodestyle = { enabled = false },
        -- type checker
        pylsp_mypy = { enabled = true },
        -- auto-completion options
        jedi_completion = { fuzzy = true },
        -- import sorting
        pyls_isort = { enabled = true },
    },
    },
},
flags = {
    debounce_text_changes = 200,
},
capabilities = capabilities,
}

Note that for some of the plugins, you can pass other configuration to the execute, but I prefer to control their behavior using in their configuration files, not using nvim-lsp.

ref:

python-lsp configuration: https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md

Configuration pylint and black in `pyproject.toml`
#

pyproject.toml
#

For project-specific settings, it is convenient to configure all this in the file pyproject.toml.

Ref:

learn toml: https://learnxinyminutes.com/docs/toml/

Pylint
#

Pylint recognizes configurations in pyproject.toml file. However, configuring pylint in pyproject.toml requires a bit understanding. First, we can generate a full pylint configuration for later reference:

pylint --generate-rcfile > pylintrc

We can see that pylint configuration is separated into multiple sections (or table by TOML’s jargon). When we want to configure a certain option for Pylint, we must know its table in pylintrc. For example, suppose we want to set max-line-length to 100, first check which table it belongs to in the original pylintrc. After checking, we know it belongs to FORMAT table, then we can use either two confs in pyproject.toml:

[tool.pylint.format]
max-line-length = 100

[tool.pylint.'FORMAT']
max-line-length = 100

Note that for values which are a list, we must use a list notation in pyproject.toml. For example, if we want to disable both missing-module-docstring and missing-function-docstring, we can write the config as this:

[tool.pylint.'MESSAGES CONTROL']
disable = ["missing-module-docstring", "missing-function-docstring"]

The following also works:

[tool.pylint.messages_control]
disable = ["missing-module-docstring", "missing-function-docstring"]

In this case, the syntax is not the same as pylintrc, where you only need to separated the warnings with comma.

As another way, we can also use pylint --generate-toml-config to generate a copy of pylintrc options in toml format. This would be much easier for hand-picking the options that we want to change.

There are a lot of examples on using pylint in pyproject.toml in GitHub, e.g., in AiiDA, jax, example conf from pylint offical.

ref:

pylint’s support for pyproject.toml: https://pylint.pycqa.org/en/latest/user_guide/usage/run.html#command-line-options
handle rich types in TOML: https://github.com/pylint-dev/pylint/commit/489508cc68705cf07e9fea8acd2b449ea88aa962
how to decide what option belongs to which section: https://github.com/pylint-dev/pylint/issues/3181#issuecomment-846129966
search pylint config in setup.cfg and pyproject.toml: https://github.com/pylint-dev/pylint/issues/617#issuecomment-541474172

Black
#

Configuration can be inside pyproject.toml, the section of black is [tool.black]. For example, your configuration may look like the following:

[tool.black]
line-length = 100

You can also check how the black project configures itself here.

ref:

https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#what-on-earth-is-a-pyproject-toml-file

Make Pylsp work inside a virtual env
#

In my computer, pylsp, mypy, black, pylint and isort are all installed globally. I do not want to install all of these tools separately for each virtual env I use. For black and isort, they seem to work fine without any additional settings.

For Pylsp, there seem to be not much mature solution¹. I experimented with different configuration and find what is working for me.

Change PYTHONPATH
#

We can also update the PYTHONPATH variable to make the global pylint and mypy be aware of the packages installed inside the virtual environment. That is we can set variable to the package directory for the virtual environment:

export PYTHONPATH=$PYTHONPATH:/path/to/project/venv/lib/<python-version>/site-packages

After this setup, pylint and mypy seem to work fine.

ref:

https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH

Change config for individual tool
#

Pylint
#

For pylint installed globally, it can not recognize the packages installed inside the virtual environment, even if we are inside the virtual env. First, we can install pylint-venv in the global level (outside the virtual env):

pip install pylint-venv

Then inside the pyproject.toml file for this project, we can configure a init-hook for pylint:

[tool.pylint.main]
init-hook ="""
try:
  import pylint_venv
except ImportError:
  pass
else:
  pylint_venv.inithook()
"""

This seems to work pretty good to prevent pylint from complaining missing package errors.

mypy
#

To use global mypy, we need to instruct mypy the python path inside the virtual environment.

[tool.mypy]
python_executable="../venv/bin/python"

Another way to do this is to directly change the options passed to mypy in neovim-lsp configuration:

  local venv_path = os.getenv('VIRTUAL_ENV')
  local py_path = nil
  -- decide which python executable to use for mypy
  if venv_path ~= nil then
    py_path = venv_path .. "/bin/python3"
  else
    py_path = vim.g.python3_host_prog
  end

  lspconfig.pylsp.setup {
    on_attach = custom_attach,
    settings = {
      pylsp = {
        plugins = {
          -- formatter options
          black = { enabled = true },
          autopep8 = { enabled = false },
          yapf = { enabled = false },
          -- linter options
          pylint = { enabled = true, executable = "pylint" },
          ruff = { enabled = false },
          pyflakes = { enabled = false },
          pycodestyle = { enabled = false },
          -- type checker
          pylsp_mypy = {
            enabled = true,
            overrides = { "--python-executable", py_path, true },
            report_progress = true,
            live_mode = false
          },
          -- auto-completion options
          jedi_completion = { fuzzy = true },
          -- import sorting
          isort = { enabled = true },
        },
      },
    },
    flags = {
      debounce_text_changes = 200,
    },
    capabilities = capabilities,
  }