Nvim API methods:vim.api

Exposes Neovim API methods.For instance to callnvim_strwidth:

result=vim.api.strwidth("some text")

Note the initialnvim_ is not included.Also, object methods can be called directly on their object:

buf=vim.current.bufferlength=buf.api.line_count()

callsnvim_buf_line_count.Alternatively msgpack requests can be invoked directly:

result=vim.request("nvim_strwith","some text")length=vim.request("nvim_buf_line_count",buf)

Bothvim.api andvim.request can take anasync_=True keyword argumentto instead send a msgpack notification. Nvim will execute the API method thesame way, but python will not wait for it to finish, so the return value isunavailable.

Vimscript functions: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')

These functions can also take theasync_=True keyword argument, just like APImethods.

Lua integration

Python plugins can define and invoke lua code in Nvim’s in-process luainterpreter. This is especially useful in asynchronous contexts, where an asyncevent handler can schedule a complex operation with many api calls to beexecuted by nvim without interleaved processing of user input or other eventsources (unless requested).

The recommended usage is the following pattern. First usevim.exec_lua(code)to define a module with lua functions:

vim.exec_lua("""   local a = vim.api   local function add(a,b)       return a+b   end   local function buffer_ticks()      local ticks ={}      for _, buf in ipairs(a.nvim_list_bufs()) do          ticks[#ticks+1] = a.nvim_buf_get_changedtick(buf)      end      return ticks   end   _testplugin = {add=add, buffer_ticks=buffer_ticks}""")

Alternatively, place the code in/lua/testplugin.lua under your plugin reporoot, and usevim.exec_lua("_testplugin=require('testplugin')").In both cases, replacetestplugin with a unique string based on your pluginname.

Then, the module can be accessed asvim.lua._testplugin.

mod=vim.lua._testpluginmod.add(2,3)# => 5mod.buffer_ticks()# => list of ticks

These functions can also take theasync_=True keyword argument, just like APImethods.

It is also possible to pass arguments directly to a code block. Usingvim.exec_lua(code,args...), the arguments will be available in lua as....

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:

:pythonvim.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),andvim.async_call can be used to send results back to Neovim.

Some methods accept anasync_ keyword argument:vim.eval,vim.command,vim.request as well as thevim.funcs,vim.api`and``vim.lua` wrappers. Whenasync_=True is passed the client will not waitfor Neovim to complete the request (which also means that the return value isunavailable).