Repository files navigation

• Introduction
• Installing
  • Downloading
  • Configuring Vim
  • Python Version
  • Initializing Vim with Remote Plugin
  • Testing the New Plugin
• Development
  • Debugging
  • Plugin Interface Changes
• Troubleshooting
  • Refreshing the Manifest File
  • Python Client Log File
  • Neovim Log File
  • Neovim Library
• References

As part of the changes included in Neovim there is a new plugin model whereplugins are separate processes which Neovim communicates to using theMessagePack protocol.

Since plugins are distinct from the Neovim process, it is possible to writeplugins in many languages.

This is a minimal example of a Python plugin. When you want to create a newPython plugin, you should be able to (and feel free to) copy this repository,rename a couple files, include the plugin in your Vim config and see somethinghappen.

The intention of this repository is to make it quick and easy to start a newplugin. It is just enough to show how to make the basics work.

git clone --depth 1 https://github.com/jacobsimpson/nvim-example-python-plugin~/.vim/bundle/nvim-example-python-pluginrm -Rf~/.vim/bundle/nvim-example-python-plugin/.git

I use NeoBundle so this is an example of how to load this plugin in NeoBundle.

" Required:callneobundle#begin(expand('~/.vim/bundle/'))" Let NeoBundle manage NeoBundle" Required:    NeoBundleFetch'Shougo/neobundle.vim'" You probably have a number of other plugins listed here." Add this line to make your new plugin load, assuming you haven't renamed it.    NeoBundle'nvim-example-python-plugin'callneobundle#end()

If you use vim-plug, you can add this line to your plugin section:

Plug'jacobsimpson/nvim-example-python-plugin'

After running:PlugInstall, the files should appear in your~/.config/nvim/plugged directory (or whatever path you have configured for plugins).

This plugin code works with Python 2. You can make it work with Python 3 by changing therplugin/python directory to berplugin/python3. See thepython-client remote plugin documentation for more information.

The next thing to do is to initialize the manifest for the Python part of theplugin. The manifest is a cache that Vim keeps of the interface implemented bythe Python part of the plugin. The functions and commands it implements.

To initialize the manifest, execute:

:UpdateRemotePlugins

NOTE: After initializing the manifest, you must restart neovim for the pythonfunctions be be available.

There is some VimL in the plugin that will print when Neovim is starting up:

Starting the example Python Plugin

That will confirm that the VimL portions of the plugin are loading correctly.

There is a function defined in the VimL portion of the plugin which echos sometext. You can execute the function like this:

:execDoItVimL()

Now that the manifest is initialized, it should be possible to invoke thefunction defined in the Python part of the plugin. Look in __init__ to seethe implementation.

:execDoItPython()

On it's own, this plugin doesn't do anything interesting, so the expectation isthat you will want to modify it.

In order to take advantage of the Python REPL and make it easier to test changes in your Python code, I usually take the following steps:

1. Open a Neovim instance.
2. Open a terminal inside Neovim. (:term)
3. Start the Python, or IPython, interpreter in the Neovim terminal. (python, ipython)
4. Execute this code in the Python interpreter:

importneovimimportosnvim=neovim.attach('socket',path=os.environ['NVIM_LISTEN_ADDRESS'])

At this point, you can either execute commands directly against Neovim, to test the behavior of the interface:

nvim.current.buffer.name

or load your own plugin class and work with it directly.

%run"rplugin/python/nvim-example-python-plugin.py"m=Main(nvim)m.doItPython([])

Neovim includes a step where the interface of the remote plugin is cached forNeovim, so that Neovim knows what functions and commands your plugin is makingavailable without having to wait while the external process containing theplugin is started.

:UpdateRemotePlugins

Run this command forevery change in the plugin interface. Without this, youmay see errors on from Neovim telling you methods are missing from your plugin.Or the new functionality you are trying to add just won't work.

For each change to the interface of the Python plugin, that is to say, anyalterations to the @neovim decorators, you need to update Neovim's manifestfile:

:UpdateRemotePlugins

Restart Neovim after you update to make the changes take effect.

If there is a syntax error in the Python file, it may result in the plugin notloading. There may be no visible error. If you run the update command, and thecommands and functions defined in the remote plugin are not available, the nextuseful troubleshooting step is to load your plugin directly in a Pythoninterpreter to see if it works.

Define this environment variable to get output logged from your Python client.

export NVIM_PYTHON_LOG_FILE=${HOME}/.nvim-python.log

The output files will have a number appended, and should be visible with this:

ls${HOME}/.nvim-python.log*

ls~/.nvimlog

One problem I encountered when I was first getting started was the Pythonneovim module was not installed on my system. I didn't see any great errorsthat lead me to that conclusion, so it is worth checking:

python -c"import neovim"

Should execute without an error.

• Neovim Remote Plugin Documentation

The Neovim docs for remote plugins. It's a little sparse, but captures the coredetail.

• Neovim Python Client

The Neovim Python client is the Python API that wraps the MessagePack protocolNeovim uses to communicate with remote plugins. If you are looking for moreinformation on how to use the vim parameter to the main object to controlNeovim, this is the place to go.