Python Plugin API¶
Neovim has a new mechanism for defining plugins,
as well as a number of extensions to the python API.
The API extensions are accessible no matter if the traditional :python
interface or the new mechanism is used,
as discussed on Remote (new-style) plugins.
vim.funcs
¶
Exposes vimscript functions (both builtin and global user defined functions) as a python namespace. For instance to set the value of a register:
vim.funcs.setreg('0', ["some", "text"], 'l')
vim.api
¶
Exposes Neovim API methods.
For instance to call nvim_strwidth
:
result = vim.api.strwidth("some text")
Note the initial nvim_
is not included.
Also, object methods can be called directly on their object:
buf = vim.current.buffer
len = buf.api.line_count()
calls nvim_buf_line_count
.
Alternatively msgpack requests can be invoked directly:
result = vim.request("nvim_strwith", "some text")
len = vim.request("nvim_buf_line_count", buf)
Async calls¶
The API is not thread-safe in general.
However, vim.async_call
allows a spawned thread to schedule code to be executed on the main thread.
This method could also be called from :python
or a synchronous request handler,
to defer some execution that shouldn’t block Neovim:
:python vim.async_call(myfunc, args...)
Note that this code will still block the plugin host if it does long-running computations.
Intensive computations should be done in a separate thread (or process),
and vim.async_call
can be used to send results back to Neovim.
Some methods accept an async
keyword argument:
vim.eval
, vim.command
, vim.request
as well as the vim.funcs
and vim.api
wrappers.
When async=True
is passed the client will not wait for Neovim to complete the request
(which also means that the return value is unavailable).