Understanding YouCompleteMe's 'Configuring through Vim Options' Mechanics

Question

There is a bit in YouCompleteMe that I do not understanding. It is the following bit from the documentation: Configuring through Vim Options

--- EDIT ---

So to clarify the question: How different is the "Configuring through Vim Options" approach to "Having a .ycm_extra_conf.py inside your project's root" approach?

Could you please help me understand the mechanics and the purpose behind this client_data and the concept of "configuring through vim options."

Answer 1

So, I did a bit of research and they were very helpful at the YouCompleteMe gist chat room. Here is what I know now. Also this is probably only python-completion specific, but I am sure the mechanics are applicable to all kind of completion tasks.

The Answer

YouCompleteMe offers two ways to pass data to the completer engine:

1. Through a .ycm_extra_conf.py located inside your project.

2. Through a global global_extra_conf.py file that provides hooks so that you can take care of what goes into the completer yourself (the name of the file is something you define and can be anything, see below).

The confusing bit here was that I was not able to understand how the second (2) scenario works. This second case is known as the Configuring through Vim options approach. So here it is:

You set this up at VIM start up (in your .vimrc):

let g:ycm_python_interpreter_path = ''
let g:ycm_python_sys_path = []
let g:ycm_extra_conf_vim_data = [
  \  'g:ycm_python_interpreter_path',
  \  'g:ycm_python_sys_path'
  \]
let g:ycm_global_ycm_extra_conf = '~/global_extra_conf.py'

The lines above prepare your hooks.

In the above example, the most important bit is the g:ycm_extra_conf_vim_data variable. The other variables, g:ycm_python_interpreter_path and g:ycm_python_sys_path, you can name them whatever you want, as long as you keep it consistent across your workflow.

So now you have two access points, whatever goes into these variables (g:ycm_python_interpreter_path, g:ycm_python_sys_path) gets passed to the completer engine through the client_data[] API. This API bridging happens inside the global configuration file that you have defined in the stage above, the one called ~/global_extra_conf.py. The following is what goes into your ~/global_extra_conf.py file. This is from the documentation by the way.

def Settings( **kwargs ):
  client_data = kwargs[ 'client_data' ]
  return {
    'interpreter_path': client_data[ 'g:ycm_python_interpreter_path' ],
    'sys_path': client_data[ 'g:ycm_python_sys_path' ]
  }

That's all, you are all set. So now, ever time you load your project (well, this case study is focusing on a python workflow - so, every time you load your python project), you can set the g:ycm_python_interpreter_path to your virtual environment's or your project's python binary. And if you need any third party modules that are outside your project's python binary's scope, you can introduce them through the g:ycm_python_sys_path variable.

Please do not forget, this case is only if you would like to NOT have a .ycm_extra_conf.py file in the root of every one of your projects. This gives you the flexibility to manage what you pass to the completer yourself, on the fly, without dealing with extra config files. So you just do:

let g:ycm_python_interpreter_path='/some/path/to/my/project's/python'
let g:ycm_python_sys_path='/some/path/to/a/third/party/module'

And you sould get the completion working.

One Important Thing

The first mistake I made, when I was looking into this, was that I tried to work with the g:ycm_server_python_interpreter option, thinking that this was what was controlling the scope of my autocompletion. THAT IS NOT THE CASE! The g:ycm_server_python_interpreter option is designed to guide ycm when it comes to choosing the python used to run the actual completer, it has nothing to do with the completion scope and the completion process itself. In most cases, you will not be even touching that option. I used the g:ycm_server_python_interpreter option only once, when YouCompleteMe has accidentally picked my System Python on OSX. My MacVim relied on a different Python and this was causing YouCompleteMe to crash. I updated the g:ycm_server_python_interpreter option to point to the correct python and that fixed my issues.

What we are using here is g:ycm_python_interpreter_path and this is a variable we have named ourselves anyway. Just keep that in mind :)

One Final Important Thing

The pyhton that is used to run YouCompleteMe, has nothing to do with your project's python scope. My MacVim and YouCompleteMe python is the same install with no extra modules in there. But when I work on a project, I usually work with a python that has many modules installed in there, possibly even a totally different python version. These two python scopes are enterly different, please make sure to understand that bit very well, it will save you some pain.

I hope this was helpful.