Questions about configuration and improving the README

[smackesey]

version: [coc.nvim] coc-pyright 1.1.164 with Pyright 1.1.163

I am very confused about the configuration of coc-pyright and think the README could really benefit from some clarification. I would be happy to write a PR with this documentation, but I have some questions:

1. How does the coc-pyright concept of a "service" relate to a "workspace"?

When I open a fresh instance of nvim (I use the VimR GUI on macOS) and then open a file in a Python project (mosaic), this is the output I get from CocCommand workspace.showOutput pyright:

Workspace: /Users/smackesey
Using python from .venv/bin/python

[Info  - 2:32:08 PM] Pyright language server 1.1.163 starting
[Info  - 2:32:08 PM] Server root directory: /Users/smackesey/.cache/nvimplugin/coc-pyright/node_modules/pyright/dist/
[Info  - 2:32:08 PM] No configuration file found.
[Info  - 2:32:08 PM] No pyproject.toml file found.
[Info  - 2:32:08 PM] Setting pythonPath for service "mosaic": "/Users/smackesey/stm/code/lib/python/mosaic/.venv/bin/python"
[Warn  - 2:32:08 PM] stubPath /Users/smackesey/stm/code/lib/python/mosaic/typings is not a valid directory.
[Info  - 2:32:08 PM] Assuming Python version 3.9
[Info  - 2:32:08 PM] Assuming Python platform Darwin
[Info  - 2:32:09 PM] Searching for source files
[Info  - 2:32:09 PM] Auto-excluding /Users/smackesey/stm/code/lib/python/mosaic/.venv
[Info  - 2:32:09 PM] Found 142 source files

And for every additional Python project I open in the same instance, I get more log messages like Setting pythonPath for service <project-name>. So it looks like coc-pyright scans each new project opened and calls it a service (it does this even for non-python projects).

Given that pythonPath is resolved with respect to the root of each open project ("service"), what is the role of the "Workspace" in the top line of the log? Despite the fact that my home folder is announced as "Workspace", my home folder: (a) does not show up in CocList folders (so it's not considered by CoC to be a "workspace folder"); (b) Doesn't actually contain a venv at .venv/bin/python that it says it's using.

2. Does coc-pyright maintain separation of different projects with different virtualenvs?

e.g. If I open two projects A and B simultaneously in a single Vim instance, each with their own virtualenv, will completion options inside a project A file reflect the project A venv while those inside a project B file reflect the project B venv? Or will the two projects be considered part of a "multi-root" workspace, with the most recently recognized environment overwriting the last recognized one?

3. What is the logic used to determine the Python environment used by coc-pyright from configuration parameters? Is the environment the same for the language server, linting, and formatting functionality?

• coc-pyright provides the settings pythonPath and venvPath (no venv).
• PyRight provides the settings venv and venvPath (no pythonPath).
• PyRight's venvPath is defined with respect to venv-- venvPath is a directory containing virtual envs and venv names a specific virtual env. This makes sense. But coc-pyright just gives you venvPath but doesn't let you name an actual virtual env. What is the point of this? Under what conditions would I want to set venvPath in coc-settings.json?
• Suppose I set pythonPath in coc-settings.json and venv/venvPath in pyrightconfig.json-- what happens then?

Furthermore, it seems like coc-pyright uses different logic to determine the environment depending on the exact bit of functionality requested. For instance, when I start editing a Python project with a virtual env that has rope installed, completions etc seem to work well, i.e. the configured virtual env is being used. But when I try to auto-import with a code action, I get an error message saying that rope is not installed in the current environment, despite the fact that it is.

But if I then restart the server, I get a new log message saying Workspace: <path-to-project>, and then I can format with rope. So the completion functionality seems to work based on the project-specific venv discovered in the "service" log message, but external executables (like rope) aren't resolved w.r.t. this environment, but rather the path announced as the "Workspace".

4. Why does the configuration for coc-pyright support a small subset of the configuration parameters defined for PyRight itself? Is there any difference between setting a value in coc-settings.json vs pyrightconfig.json?

For example, useLibraryCodeForTypes can be set either through coc-settings.json (via python.analysis.useLibraryCodeForTypes) or in pyrightconfig.json. Does it make a difference where it is set? If not, then why is this parameter exposed in coc-pyright at all, given that the vast majority of other PyRight config parameters cannot be set in coc-settings.json?

5. Why are there configuration settings for mypy and pytype? Aren't these alternative Python type checkers that compete directly with PyRight?

Why would I use mypy and PyRight at the same time? And if this project is intended to allow you to choose an arbitrary type checker, then why is there no option to disable PyRight type-checking, and why is the project called coc-pyright?

6. Why are there 3 different output channels (Pyright, 'coc-pyright-formatting, coc-pyright-linting`). Under what circumstances will a log message appear in which channel?

[fannheyward]

1. How does the coc-pyright concept of a "service" relate to a "workspace"?

It's recommend to open vim in your project root, that 1. cd to your project root, 2. open vim. coc-pyright will try to detect the Python from venv to use. From the logs:

Workspace: /Users/smackesey
Using python from .venv/bin/python

I found that you're using VimR to open a project to work, but coc-pyright failed to detect the Python.

Setting pythonPath for service

This log was came from Pyright, do you have pyrightconfig.json file in your project root?

2. Does coc-pyright maintain separation of different projects with different virtualenvs?

No.

3. What is the logic used to determine the Python environment used by coc-pyright from configuration parameters? Is the environment the same for the language server, linting, and formatting functionality?

But coc-pyright just gives you venvPath but doesn't let you name an actual virtual env. What is the point of this? Under what conditions would I want to set venvPath in coc-settings.json?

the python.venvPath is came from https://github.com/microsoft/pyright/blob/main/packages/vscode-pyright/package.json#L745, also there's no python.venv. TBO I don't know what's the point of python.venvPath.

4. Why does the configuration for coc-pyright support a small subset of the configuration parameters defined for PyRight itself? Is there any difference between setting a value in coc-settings.json vs pyrightconfig.json?

Because https://github.com/microsoft/pyright/blob/main/packages/vscode-pyright/package.json has this.

Does it make a difference where it is set

I don't think there is any difference. You can custom settings by coc-settings.json and pyrightconfig.json, but why are there different subset options on both? I don't know.

5. Why are there configuration settings for mypy and pytype? Aren't these alternative Python type checkers that compete directly with PyRight?

Yes, Pyright, mypy, pytype are different static typing check tools for Python. coc-pyright uses Pyright to do type checking and LSP related things like completions, goto definitions etc. You disable Pyright's type checking by pyright.disableDiagnostics.

mypy/pytype should not be part of coc-pyright, also pylint/flake8/pycodestyle etc. But lots of users are using pylint/mypy etc in their project, so I added them into coc-pyright as linters, you can enable it as your like. Just like you can use Pylance(based by Pyright) with vscode-python (provides many linters) together.

In short, coc-pyright uses Pyright as Language Server, to do completions, goto definitions, find references etc. coc-pyright also provides code formatting by black/yapf and lint from pylint/pytype, you can enable them as you like. (You don't need rope to do completions.

6. Why are there 3 different output channels (Pyright, 'coc-pyright-formatting, coc-pyright-linting`). Under what circumstances will a log message appear in which channel?

I can put them into one output channel, but there're too many logs from different tools, so I separate them into three channels.

Pyright logs will go Pyright channel. If you use code formatting by black/yapf, these logs will go coc-pyright-formatting. If you use pylint/pytype linters, logs go coc-pyright-linting.

Hope I answered your questions.

[oblitum]

1. How does the coc-pyright concept of a "service" relate to a "workspace"?

It's recommend to open vim in your project root, that 1. cd to your project root, 2. open vim.

I'd like to point out, just a little bit, that this workspace topic can really be a problem:

• Can Metals function without a workspace? scalameta/metals#3079
  • Allow working with an empty workspace scalameta/metals-feature-requests#231
• feat(lsp): allow root_dir to be nil neovim/neovim#15430 (comment)

So just to assure you folks are inline on that topic, I'm sharing that info above.

I don't think it should be needed to cd to a project root first and open vim there for it to work (why? you have to read up those links). It might be recommended just due to a currently, not optimal , implementation.

[smackesey]

@oblitum Definitely agree that requiring Vim to be opened in a particular CWD is not ideal. I don't have this problem with other language servers, and was planning to suggest an alternative once I have time to figure out how they work.

[oblitum]

and was planning to suggest an alternative once I have time to figure out how they work

How they need to work is inside those links. There's a bunch that don't do it right though. So how some given one might work may or may not be correct.

[fannheyward]

@oblitum yes, you don't need to cd to your project root, you can nvim ~/src/hello-python/main.py directly, coc will handle the workspaceFolders to null.

Remember that in this case, Pyright may use the wrong Python path for the project, this is the main reason for recommending to open vim in your project root: let coc-pyright to do better Python path detecting.

There're so many Python venv tools, pyenv/virtualenv/conda/miniforge etc.

1. someone like to put different venvs to a special path like ~/.venv, activate the different venv for different project.
2. someone like to generate venv in project root .venv.
3. someone uses pyenv to manage Python for shell/local/global
4. something like poetry also can manage venv

In these cases, you need to find and activate the correct Python for the project, then vim to code. coc-pyright did a small but useful feature IMO: coc-pyright will check .python-version or Pipfile or poetry.lock or pyvenv.cfg file in your project root, find the Python path and send it to Pyright, now Pyright can use the correct Python and pip packages to work. You don't need to activate venv first.